{"title":"Server Agent help","summary":"Server Agent queues headless Grok CLI jobs (grok -p) on this MD Hub host. Enqueue large prompts, plans, or agentic server work from the backoffice; a cron worker runs them outside the web request so timeouts do not kill long runs.","sections":[{"heading":"What it is for","body":"• Long prompts that would time out in a normal browser request\n• Implementation plans and multi-step agent work with tools\n• DB/schema reviews, code exploration, and ops tasks on the server repo\n• Any work that should use the same Grok CLI you use in a terminal\n\nJobs run only on the local host that serves this MD Hub install (not remote fleet VMs unless you open this module on that host)."},{"heading":"How a job runs","body":"1. Fill Title (optional), Type, Working directory, Model, Max turns, Timeout, and Prompt\n2. Click Enqueue job — the row is saved as status queued (not claimed yet)\n3. A worker claims the job: php tools/cron/run_grok_jobs.php (or --max=N / UI Run)\n4. Status moves queued → running → done / failed (or cancelled while still queued)\n5. Open Results to see prompt, stdout, stderr, exit code, and duration\n6. When a job finishes, you get a notification via your preferred method (Profile → Keep in touch: email, SMS, Telegram, or backoffice notification)\n7. Job types prompt, db_task, code, and custom also post the full agent response into Comms chat and auto-open the Comms panel when you are in the backoffice\n\nJobs stay queued until a worker claims them so cron can recover if a background spawn fails.\nA stuck-job reaper auto-fails running jobs past timeout (or PHP-internal jobs with no progress for 30 minutes).\nStop on a running job sends a cooperative halt, kills the recorded worker PID when safe, and cancels immediately (no forever “stopping” zombies).\nThe web UI does not run the full Grok session inline. Without the worker cron, jobs stay queued forever."},{"heading":"Job types","body":"Labels for filtering and history (they do not change the runner binary):\n• prompt — general headless prompt\n• plan — create a new plan; prompt is auto-prefixed to store it in the plans database table\n• update_plan — revise an existing plan with answers, changes, or questions (select plan + notes)\n• execute_plan — run an unexecuted plan from the plans table (steps_done = 0)\n• db_task — database or schema work (full response posted to Comms on finish)\n• packaging_ai_fill — Packaging Manager: AI description + FMV for modules priced at $0 (PHP worker, no Grok CLI). Honors timeout_sec between modules (scaled by module count, up to 4h); re-run to continue remaining $0 modules after a timeout.\n• site_generate — Sites wizard: brochure/info/merch sites use the Agentic Coder Grok CLI builder (VitalForge / SocialForge methodology); DAPP and scavenger hunts stay on the PHP worker\n• site_regenerate — Sites: full rebuild uses the same CLI builder; theme/media/content stay on the PHP worker\n• site_brand_media — Sites wizard step 4: AI brand media images (PHP worker)\n• site_page_edit — Sites page content: focused-item AI edit (PHP worker; timeout from Page Content pulldown)\n• site_consultant — Sites Website Consultant chat (PHP worker; status in consultant chat history)\n• dapp_custom_widget — Sites DAPP: custom widget AI build/display (PHP worker)\n• ai_media_cnc — MD Media CNC: 1-layer SVG generate (PHP worker)\n\nControls: Pause / Stop on running or queued jobs; Resume on paused. Stop force-cancels running work (cooperative flag + kill worker PID when recorded; CLI children terminated). Failed jobs show an error report in Results.\n• code — code edits or reviews in the repo cwd (full response posted to Comms on finish)\n• custom — anything else; use Title to describe it (full response posted to Comms on finish)\n• prompt — general headless prompt (full response posted to Comms on finish)"},{"heading":"Updating a plan","body":"After a plan job creates a plan, use type update_plan:\n1. Choose the plan from the list\n2. In Prompt, write answers to open questions, requested changes, and/or questions about the plan\n3. Enqueue and Run — the agent loads the current plan, applies your notes, and saves the same plan_id\n\nUse the quick chips under Prompt for starter wording. Improve my prompt can polish your notes."},{"heading":"When a job fails","body":"Failed jobs stay in the list with stderr and error_message:\n• Recent job errors — the Jobs tab lists the latest failures with the date each job was added, plus Open, Retry, and Remove\n• Results — inspect Error report and Stderr / errors (timeout, missing auth, bad cwd, CLI errors)\n• Retry — opens an edit modal with the failure cause and suggestions; adjust Max turns, Timeout, model, or prompt, then queue a new job (title prefixed with Retry:). Plan / RFP retries keep that type so the plans table is updated.\n• Clone — open the full New job form with fields filled so you can re-queue a variant\n• Delete — remove the failed row when you no longer need the log\n\nYou are also notified on failure via your preferred Profile notification method."},{"heading":"Form fields","body":"• Title — short label in the jobs list (optional; first field)\n• Type — job type; drives plan pickers and prefixes\n• Knowledge Base (optional) — attach one of your KBs (owned or team-shared). Relevant items are injected when the job runs\n• Prompt — required except execute_plan (notes optional). For update_plan: answers, changes, questions\n• Working directory — repo root by default; Grok tools run relative to this cwd\n• Model — optional override; leave blank for CLI default\n• Max turns — tool-loop budget (default 40)\n• Timeout — hard stop in minutes\n\nProbe CLI checks whether the worker user can find the grok binary."},{"heading":"Knowledge Base on a job","body":"On New job, pick a Knowledge Base to ground the agent in your docs:\n• The link is stored on the job (kb_id). Retry and Clone keep the same KB.\n• When the job runs, fresh KB excerpts are prepended to the prompt (RAG-style; stored prompt stays clean).\n• Works with any job type (prompt, plan, update_plan, execute_plan, etc.).\n• Only KBs you own or that are shared with your teams appear in the list.\n• Create and fill KBs in the Knowledge Bases / Agents modules first."},{"heading":"Worker setup","body":"Install a system cron (or Task Scheduler) that runs every minute as a user that can read the repo and execute grok:\n\n * * * * * cd /path/to/md_hub && php tools/cron/run_grok_jobs.php --max=1\n\n• --max=1 processes one job per run (safe for single-host)\n• Use the same PHP binary as your app (php8.x path if needed)\n• Ensure grok is on PATH for that user, or set config (below)\n• Also available under Servers → open a server detail → Server agent tab"},{"heading":"Configuration","body":"Optional keys in config/secrets.json (or env):\n\n \"grok_cli\": {\n \"binary\": \"/usr/local/bin/grok\",\n \"home\": \"/home/deploy\",\n \"cwd\": \"/var/www/md_hub\"\n }\n\nEnv overrides: GROK_CLI_BINARY, GROK_CLI_HOME, GROK_CLI_CWD.\nTable: grok_server_jobs (created automatically on first use)."},{"heading":"Safety","body":"Jobs run with elevated tool permissions on the server filesystem (permission mode bypass for headless batch). The runner applies deny rules for dangerous shell patterns, but treat prompts carefully:\n• Server Agent capability is required (Agent Manager toggle; default on). Disable for untrusted accounts.\n• Working directory is server-controlled (repo root / allowlisted subpaths only; client cwd is ignored).\n• Rate limits: max 3 active jobs and 30 jobs/hour per account.\n• Plan update/execute is owner-only (shared plans cannot be updated/executed via jobs).\n• Do not enqueue secrets in free text if logs are shared\n• Cancel only works while status is still queued\n• Failed jobs keep stderr and error_message for diagnosis"},{"heading":"Troubleshooting","body":"• CLI not found — install Grok CLI for the worker user; set grok_cli.binary; click Probe CLI\n• Jobs stuck on queued — cron not running, wrong PHP path, or worker missing config/config.json DB bootstrap (worker must load MySQL_master into session before connecting)\n• Cron output says “No queued jobs” while rows are queued — almost always DB credentials not loaded in the CLI worker\n• Status failed quickly — check Results → Stderr; often bad cwd, missing auth for grok, or timeout. Use Retry or Clone after fixing config\n• Module missing from sidebar — attach Server Agent in Menus, or hard-refresh after deploy so ensure can attach once if orphaned\n• Empty stdout on done — model returned little text; check result_summary and exit code"},{"heading":"Tips","body":"• Put large context in the prompt or rely on tools under cwd instead of pasting huge trees\n• Link a Knowledge Base instead of pasting long reference docs into the prompt\n• Use plan type + a clear “deliverable” section for design/PR plans\n• Keep one active job at a time on small hosts (--max=1)\n• Refresh polls every few seconds while any job is queued or running\n• Prefer this queue over exec() inside PHP web requests"}]}

/var/www/md_hub_repo