@songsid/agend 2.1.3 → 2.1.4-beta.10

package/dist/general-knowledge/skills/backend-providers/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: backend-providers
+description: Configure custom model providers when creating or editing AgEnD Codex or OpenCode instances. Use for local, OpenAI-compatible, GLM, or other non-default provider endpoints and for backend_options provider selection.
+roles: [general]
+---
+
+# Backend Providers
+
+AgEnD selects a provider; the backend CLI owns endpoint and credential definitions.
+
+## Choose the backend
+
+| Backend | Provider configuration |
+|---|---|
+| Codex | Select with `backend_options.codex.provider`; define the provider in Codex `config.toml`. |
+| OpenCode | Define the provider in `opencode.json`; use model ID `<provider>/<model>`. |
+| Claude Code, Kiro CLI, Antigravity, Grok | Provider is fixed by the CLI; do not set `backend_options` for provider selection. |
+
+## Create a Codex custom-provider instance
+
+1. Define the provider in the fleet user's `~/.codex/config.toml`. The table name is the provider ID used by AgEnD:
+
+```toml
+[model_providers.glm]
+name = "GLM"
+base_url = "https://provider.example.com/v1"
+env_key = "GLM_API_KEY"
+```
+
+Keep credentials out of `config.toml`. `env_key` names an environment variable; it is not the secret itself.
+
+2. Put the credential in the fleet process environment before startup. `~/.agend/.env` is the usual location:
+
+```dotenv
+GLM_API_KEY=replace-with-the-real-secret
+```
+
+Restart the fleet after changing its environment. Exporting a variable in an unrelated shell after the fleet has started does not update the running fleet process.
+
+3. Create the instance with the MCP tool:
+
+```json
+{
+  "directory": "/home/user/projects/my-project",
+  "topic_name": "glm-worker",
+  "backend": "codex",
+  "model": "GLM-5.2",
+  "backend_options": {
+    "codex": {
+      "provider": "glm"
+    }
+  }
+}
+```
+
+The equivalent per-instance fleet.yaml override is:
+
+```yaml
+instances:
+  glm-worker:
+    working_directory: /home/user/projects/my-project
+    backend: codex
+    model: GLM-5.2
+    backend_options:
+      codex:
+        provider: glm
+```
+
+AgEnD copies the user's Codex settings into the instance-isolated `CODEX_HOME`, then launches Codex with `model_provider="glm"`. Provider IDs may contain only letters, digits, `_`, and `-`.
+
+## Configure OpenCode
+
+Define the endpoint, SDK adapter, credentials, and models in OpenCode's `opencode.json` provider block:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "glm": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "GLM",
+      "options": {
+        "baseURL": "https://provider.example.com/v1",
+        "apiKey": "{env:GLM_API_KEY}"
+      },
+      "models": {
+        "GLM-5.2": {
+          "name": "GLM-5.2"
+        }
+      }
+    }
+  }
+}
+```
+
+Then use the fully qualified model ID in AgEnD:
+
+```yaml
+instances:
+  glm-opencode:
+    working_directory: /home/user/projects/my-project
+    backend: opencode
+    model: glm/GLM-5.2
+```
+
+OpenCode provider IDs and model IDs come from its own config. Do not use `backend_options.codex.provider` for OpenCode.
+
+## Verify and troubleshoot
+
+- Run `validate_config` before reload or restart.
+- Use `describe_instance` to verify the effective backend and model after creation.
+- If Codex says the provider is unknown, verify the `[model_providers.<id>]` table is in `~/.codex/config.toml` before the instance starts.
+- If authentication fails, verify the variable named by `env_key` exists in the fleet process environment; never paste the secret into fleet.yaml or `backend_options`.
+- A model-metadata fallback warning can be normal for a custom model with no built-in metadata. Provider connection, authentication, or unsupported-model errors are not normal and should still be investigated.

package/dist/general-knowledge/skills/cross-instance-messaging/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: cross-instance-messaging
 description: Fire-and-queue cross-instance tools — send once, never resend on queued
+roles: [general, worker]
 ---
 
 ## How to send
@@ -18,5 +19,6 @@ Use fleet tools only (`send_to_instance`, `delegate_task`, `request_information`
 
 ## Task flow
 
-- `delegate_task` → silent work → `report_result` (zero ack-only pings)
+- Coordinator flow: `delegate_task` → silent work → `report_result` (zero ack-only pings).
+- Worker flow: finish with `report_result`, or use `request_information` when blocked. A normal worker must not call `delegate_task` or re-delegate work.
 - Cross-instance traffic is `[from:name]` → answer with `send_to_instance` / `report_result`, never `reply`

package/dist/general-knowledge/skills/delegation-playbook/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: delegation-playbook
+description: Delegation protocol, loop prevention, parallel vs sequential execution, result/failure handling, team management, and instance configuration tips for the fleet coordinator
+roles: [general]
+---
+
+## Delegation Protocol
+
+Every delegation via send_to_instance() MUST include:
+
+1. Task scope — what exactly to do, bounded clearly
+2. Expected output — what to return and in what form
+3. Policy reminder — "Follow Development Workflow policy" (for code tasks)
+
+### Loop Prevention
+
+- Never re-delegate a task back to the instance that sent it to you
+- If a task has bounced 3 times, stop and solve locally or reduce scope
+
+### Execution Strategy
+
+- Parallel — use only when tasks are independent with no shared state
+- Sequential — use when one task's output feeds into the next
+
+## Result Handling
+
+When an instance reports back, classify the outcome:
+
+- Success → Summarize key results for user. Omit internal coordination noise.
+- Partial → State what succeeded, what remains, proposed next steps.
+- Failure → Retry up to 2 times. If still failing: try alternative instance, reduce scope, or return partial result clearly marked.
+- No response → Ping again after reasonable wait. If still silent: report to user with options.
+
+## Shared Decisions
+
+Use post_decision() / list_decisions() for any choice that affects more than 1 instance, changes an API contract, introduces a new dependency, or alters deployment process.
+
+When instances disagree, collect both viewpoints, make a decision, and record it via post_decision.
+
+## Team Management
+
+- Always check existing teams before creating new ones
+- Default to ephemeral teams (created for a specific task, dissolved after completion)
+- Clean up ephemeral teams and instances after task completion
+
+## Instance Configuration Tips
+
+When users create specialized instances, suggest these configurations:
+
+- **Reviewer instances**: Add `pre_task_command: "/chat load reviewer-base"` to reset context before each review, preventing influence from previous conversations.
+- **Collab mode**: For multi-bot channels, use `/collab` to enable @mention-based triggering.
+- **Cost control**: Set per-instance `cost_guard` for expensive backends.

package/dist/general-knowledge/skills/development-workflow/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: development-workflow
+description: The fleet-wide code-change policy the coordinator enforces when delegating code tasks — stages, review pairing, merge conditions
+roles: [general]
+---
+
+All code changes across the fleet should follow this workflow.
+The coordinator enforces compliance but does not perform these steps directly.
+Remind instances of this policy when delegating code tasks.
+
+## Workflow Stages
+
+Design Proposed → Design Approved → Implementation → Submit for Review → Under Review → Approved → Merge
+
+## Policy Rules
+
+1. Design before code — developer sends design proposal to reviewer before implementation. Consensus required before proceeding.
+2. Challenger pairing — every code task should have a developer + reviewer. Reviewer actively questions decisions and finds risks.
+3. Verify by execution — backend/CLI changes must be tested by running them. Do not trust documentation alone.
+4. Independent review — every merge requires code review from someone other than the author.
+5. Root cause first — bug fixes require confirmed root cause before proposing a fix.
+6. Merge conditions: tests pass, reviewer approved, branch and worktree cleaned up.
+
+## Specialist Instance Rules
+
+- Execute within defined scope only
+- Return structured output: result, assumptions, uncertainties, verification status
+- Do NOT create new instances without coordinator approval

package/dist/general-knowledge/skills/fleet-config/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: fleet-config
 description: fleet.yaml and classicBot.yaml structure, validation, common mistakes
+roles: [general]
 ---
 
 ## Configuration Quick Reference

package/dist/general-knowledge/skills/fleet-health/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: fleet-health
 description: Check instance health and what an agent is doing; recover a stuck instance
+roles: [general]
 ---
 
 ## Check health

package/dist/general-knowledge/skills/fleet-restart/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: fleet-restart
 description: Fleet restart types, recovery from tmux crash, rate limit handling, safe update
+roles: [general]
 ---
 
 ## Fleet Restart & Recovery

package/dist/general-knowledge/skills/instance-lifecycle/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: instance-lifecycle
 description: restart vs replace vs pause/wake; when to use each
+roles: [general]
 ---
 
 ## Restart vs Replace

package/dist/general-knowledge/skills/model-discovery/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: model-discovery
 description: Set and discover models — pass-through to the CLI, no AgEnD allowlist gate
+roles: [general, worker]
 ---
 
 ## How to set a model

package/dist/general-knowledge/skills/multi-channel/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: multi-channel
 description: Setting up multiple platforms (Telegram + Discord) with proper general routing
+roles: [general]
 ---
 
 ## Multi-Channel Setup

package/dist/general-knowledge/skills/scheduling/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: scheduling
 description: Cron, one-shot, and silent schedules via the schedule MCP tools
+roles: [general, worker]
 ---
 
 ## Tools

package/dist/general-knowledge/skills/session-management/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: session-management
 description: Session stores, forking, and auth-pause recovery
+roles: [general]
 ---
 
 ## Auth failure (auto-pause)

package/dist/general-knowledge/skills/tui-effort/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: tui-effort
 description: 在 Kiro CLI TUI instance 中，透過 tmux 查看或設定模型的 reasoning effort
+roles: [general]
 ---
 
 # Kiro TUI Effort

package/dist/general-knowledge/skills/worker-collaboration/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: worker-collaboration
+description: Complete assigned fleet work as a worker, report the result to the assigning instance, and request missing information without taking over coordinator duties.
+roles: [worker]
+---
+
+# Worker Collaboration
+
+## Complete assigned work
+
+- Treat the assignment as the full scope unless the sender explicitly expands it.
+- Work without acknowledgment-only messages. Silence means the task is in progress.
+- Do not call `delegate_task`; delegation and fleet orchestration belong to General.
+
+## Request missing information
+
+Use `request_information` only when a concrete missing fact blocks safe progress. Ask the assigning instance one focused question and preserve the task correlation ID when the tool supports it.
+
+Do not resend after a timeout without checking delivery evidence. A timeout can mean the request was queued or delivered while the caller stopped waiting.
+
+## Report the result
+
+Call `report_result` exactly once when the assignment is complete or genuinely blocked. Send it to the assigning instance with the original correlation ID. Include:
+
+- the conclusion or delivered artifact;
+- material changes and file paths;
+- tests or checks run and their results;
+- remaining risk, blocker, or follow-up, if any.
+
+Do not put user-facing results only in terminal text; the fleet report is the delivery channel.

package/dist/instance-lifecycle.d.ts

@@ -49,6 +49,10 @@ export interface LifecycleContext {
     touchActivity(name: string): void;
     sendHangNotification(name: string, unchangedForMs?: number): Promise<void>;
     notifyInstanceTopic(name: string, text: string): void;
+    /** Notify the blocked instance and offer an interactive assist action in General. */
+    notifyInteractivePrompt(name: string, kind: string): Promise<void>;
+    /** Notify a clean CLI exit and offer an admin-only restart action in General. */
+    notifyNormalExit(name: string): Promise<void>;
     /** True for a dynamic ClassicBot channel instance (not a fleet topic). */
     isClassicInstance?(name: string): boolean;
     /** True while the fleet is stopping on purpose or an `agend update` is running. */
@@ -71,6 +75,10 @@ export interface LifecycleContext {
 export interface IncidentEventSource {
     on(event: string, handler: (...args: any[]) => void): unknown;
     requestPauseWhenIdle(): void;
+    /** Present on real daemons; hang buttons attach only when it returns one. */
+    getHangDetector?(): {
+        on(event: string, handler: (...args: any[]) => void): unknown;
+    } | null;
 }
 /** Arguments accepted by handleCreate — mirrors CreateInstanceArgs in outbound-schemas.ts
  *  plus internal-only fields forwarded by deploy_template (profile-derived). */
@@ -80,6 +88,8 @@ export interface LifecycleCreateArgs {
     description?: string;
     model?: string;
     backend?: string;
+    /** Backend-specific launch options, e.g. { codex: { provider: "glm" } }. */
+    backend_options?: Record<string, Record<string, unknown>>;
     branch?: string;
     detach?: boolean;
     worktree_path?: string;

package/dist/instance-lifecycle.js

@@ -165,6 +165,39 @@ export class InstanceLifecycle {
      * means a real tmux window, which is why this rule went untested before.
      */
     attachIncidentHandlers(name, daemon) {
+        const hangDetector = daemon.getHangDetector?.();
+        if (hangDetector) {
+            hangDetector.on("hang", safeHandler(async (data) => {
+                this.ctx.eventLog?.insert(name, "hang_detected", {});
+                this.ctx.logger.warn({ name }, "Instance appears hung");
+                if (this.ctx.isPlannedRestart()) {
+                    // A graceful stop makes every pane look frozen; alerting on that (with
+                    // a restart button, no less) during `agend update` is pure noise. The
+                    // same suppression interactive-prompt and normal-exit already apply.
+                    // Checked BEFORE the task nudge: injecting new work into a CLI that is
+                    // being shut down would only delay the stop.
+                    this.ctx.logger.info({ name }, "Hang notification suppressed — planned restart in progress");
+                    return;
+                }
+                // Check if instance has claimed tasks — nudge it to continue
+                const claimedTasks = this.ctx.listClaimedTasks(name);
+                if (claimedTasks.length > 0) {
+                    const task = claimedTasks[0];
+                    this.ctx.eventLog?.insert(name, "idle_task_nudge", { taskId: task.id, taskTitle: task.title });
+                    // Inject nudge message into the instance's CLI session
+                    const ipc = this.ctx.instanceIpcClients.get(name);
+                    if (ipc?.connected) {
+                        ipc.send({
+                            type: "fleet_inbound",
+                            content: `[system] You have a claimed task: "${task.title}" (#${task.id}). Continue working on it, or use task(done) / task(update, status=blocked) to update status.`,
+                            meta: { chat_id: "", thread_id: "", ts: new Date().toISOString() },
+                        });
+                    }
+                }
+                await this.ctx.sendHangNotification(name, data?.unchangedForMs);
+                this.ctx.webhookEmit("hang", name);
+            }, this.ctx.logger, `hangDetector[${name}]`));
+        }
         daemon.on("crash_respawn", safeHandler(() => {
             this.ctx.eventLog?.insert(name, "crash_respawn", {});
             this.ctx.logger.warn({ name }, "Instance crashed and respawned");
@@ -178,11 +211,22 @@ export class InstanceLifecycle {
             this.ctx.eventLog?.insert(name, "snapshot_failed", {});
             this.notifyIncident(name, "snapshot_failed", t("inst.restarted_no_context", name));
         }, this.ctx.logger, `daemon.snapshot_failed[${name}]`));
-        daemon.on("supervision_ended", safeHandler((data) => {
+        daemon.on("supervision_ended", safeHandler(async (data) => {
             // The instance is dead and nothing will restart it. Say so where the operator
             // is looking, and mark the topic — otherwise messages routed here just queue
             // or fail with a bare ❌ and the dashboard still looks normal.
             this.ctx.eventLog?.insert(name, "supervision_ended", { reason: data.reason });
+            if (data.exitCode === 0) {
+                this.ctx.logger.info({ name, exitCode: data.exitCode }, "CLI exited normally and will not restart automatically");
+                if (this.ctx.isPlannedRestart()) {
+                    this.ctx.logger.info({ name }, "Normal-exit controls suppressed — planned restart in progress");
+                }
+                else {
+                    await this.ctx.notifyNormalExit(name);
+                }
+                this.ctx.setTopicIcon(name, "red");
+                return;
+            }
             this.ctx.logger.error({ name, reason: data.reason }, "Instance is no longer supervised");
             this.notifyIncident(name, "supervision_ended", `🛑 ${name} is no longer running and will not be restarted automatically — ${data.reason}.\n${data.remedy}`);
             this.ctx.setTopicIcon(name, "red");
@@ -244,18 +288,14 @@ export class InstanceLifecycle {
             // server.
             this.ctx.restartSingleInstance(name).catch(err => this.ctx.logger.error({ err, name }, "MCP auto-restart failed"));
         }, this.ctx.logger, `daemon.mcp_restart_requested[${name}]`));
-        daemon.on("interactive_prompt", safeHandler((data) => {
+        daemon.on("interactive_prompt", safeHandler(async (data) => {
             this.ctx.eventLog?.insert(name, "interactive_prompt", { kind: data.kind });
             this.ctx.logger.warn({ name, kind: data.kind, prompt: data.prompt }, "Instance is waiting for interactive terminal input");
-            const general = this.findGeneralInstance();
-            if (!general) {
-                this.ctx.logger.warn({ name }, "Interactive prompt has no General topic notification target");
+            if (this.ctx.isPlannedRestart()) {
+                this.ctx.logger.info({ name }, "Interactive prompt notification suppressed — planned restart in progress");
                 return;
             }
-            const label = data.kind === "sudo_password" || data.kind === "password"
-                ? "sudo password"
-                : data.kind === "press_enter" ? "Press Enter" : "Y/N confirmation";
-            this.notifyIncident(general, "interactive_prompt", `⚠️ \`${name}\` 正在等待人工輸入（${label}）。General 可以透過 tmux attach 查看並協助操作。\n請勿在 Telegram/Discord 傳送密碼。`);
+            await this.ctx.notifyInteractivePrompt(name, data.kind);
         }, this.ctx.logger, `daemon.interactive_prompt[${name}]`));
         daemon.on("pty_error", safeHandler((data) => {
             this.ctx.eventLog?.insert(name, "pty_error", { type: data.type, action: data.action });
@@ -353,30 +393,6 @@ export class InstanceLifecycle {
         });
         await daemon.start();
         this.daemons.set(name, daemon);
-        const hangDetector = daemon.getHangDetector();
-        if (hangDetector) {
-            hangDetector.on("hang", safeHandler(async (data) => {
-                this.ctx.eventLog?.insert(name, "hang_detected", {});
-                this.ctx.logger.warn({ name }, "Instance appears hung");
-                // Check if instance has claimed tasks — nudge it to continue
-                const claimedTasks = this.ctx.listClaimedTasks(name);
-                if (claimedTasks.length > 0) {
-                    const task = claimedTasks[0];
-                    this.ctx.eventLog?.insert(name, "idle_task_nudge", { taskId: task.id, taskTitle: task.title });
-                    // Inject nudge message into the instance's CLI session
-                    const ipc = this.ctx.instanceIpcClients.get(name);
-                    if (ipc?.connected) {
-                        ipc.send({
-                            type: "fleet_inbound",
-                            content: `[system] You have a claimed task: "${task.title}" (#${task.id}). Continue working on it, or use task(done) / task(update, status=blocked) to update status.`,
-                            meta: { chat_id: "", thread_id: "", ts: new Date().toISOString() },
-                        });
-                    }
-                }
-                await this.ctx.sendHangNotification(name, data?.unchangedForMs);
-                this.ctx.webhookEmit("hang", name);
-            }, this.ctx.logger, `hangDetector[${name}]`));
-        }
         daemon.on("auto_pause_requested", safeHandler(async () => {
             await this.pause(name);
         }, this.ctx.logger, `autoPause[${name}]`));
@@ -786,6 +802,7 @@ export class InstanceLifecycle {
                 ...(systemPrompt ? { systemPrompt } : {}),
                 ...(args.model ? { model: args.model } : {}),
                 ...(args.backend ? { backend: args.backend } : {}),
+                ...(args.backend_options ? { backend_options: args.backend_options } : {}),
                 ...(args.model_failover ? { model_failover: args.model_failover } : {}),
                 ...(args.tool_set ? { tool_set: args.tool_set } : {}),
                 ...(args.skipPermissions != null ? { skipPermissions: args.skipPermissions } : {}),