@songsid/agend 2.1.5 → 2.1.6-beta.10

package/dist/tool-permissions-notice.js

@@ -0,0 +1,92 @@
+/**
+ * What to tell an operator whose fleet predates the `worker` default.
+ *
+ * Two things can be true of an existing installation and neither of them is
+ * something to fix on the operator's behalf:
+ *
+ * - `defaults.tool_set: full` may be written in their `fleet.yaml`, in which
+ *   case the new code default never applies and every worker still holds the
+ *   whole toolbox. Rewriting that line would be a surprise placed inside their
+ *   own file.
+ * - Some instances really are coordinating, and marking them is a judgement
+ *   about how their fleet is organised.
+ *
+ * So this computes the advice and says it once, naming the instances that will
+ * actually break rather than the ones that merely look like coordinators. A
+ * notice that asks someone to mark twenty instances they did not need to mark
+ * is a notice they stop reading.
+ */
+import { mayUseTool, resolveToolSet } from "./tool-permissions.js";
+/**
+ * Which instances would lose something they have actually been using.
+ *
+ * The rule is "called a tool the resolved profile refuses" — that is the
+ * definition of breaking, not a guess at intent. An instance that only ever
+ * called `delegate_task` does not appear, because `delegate_task` stays with
+ * the worker and nothing about it changes.
+ */
+export function coordinatorCandidates(input) {
+    const out = [];
+    for (const use of input.recent) {
+        // The activity log outlives the config. An instance that has since been
+        // deleted resolves to `worker` like any other unknown name, and would be
+        // named in a list of things to go and edit that no longer exist.
+        if (!Object.hasOwn(input.instances, use.instance))
+            continue;
+        const config = input.instances[use.instance];
+        // An instance that is already explicitly widened, or is a general, is not
+        // about to lose anything.
+        const profile = resolveToolSet(config, use.instance);
+        const refused = [...use.tools.entries()]
+            .filter(([tool]) => !mayUseTool(profile, tool))
+            .sort((a, b) => b[1] - a[1]);
+        if (refused.length > 0)
+            out.push({ instance: use.instance, refusedTools: refused });
+    }
+    return out.sort((a, b) => b.refusedTools.reduce((n, [, c]) => n + c, 0) - a.refusedTools.reduce((n, [, c]) => n + c, 0));
+}
+/** True when this fleet asked for `full` out loud, so the new default cannot reach it. */
+export function hasExplicitFullDefault(input) {
+    return input.defaultsToolSet === "full";
+}
+export function instancesExplicitlyFull(input) {
+    return Object.entries(input.instances)
+        .filter(([, config]) => config?.tool_set === "full")
+        .map(([name]) => name)
+        .sort();
+}
+/**
+ * The whole notice, or null when there is nothing worth saying.
+ *
+ * One message rather than two: an operator who needs to hear both hears them
+ * together, in the order they have to act on them.
+ */
+export function buildToolPermissionsNotice(input) {
+    const lines = [];
+    const explicitFull = hasExplicitFullDefault(input);
+    const alsoFull = instancesExplicitlyFull(input);
+    const candidates = coordinatorCandidates(input);
+    if (explicitFull) {
+        lines.push("Your fleet.yaml sets `defaults.tool_set: full`, so every agent still gets all of AgEnD's tools —", "including create_instance, delete_instance and update_fleet_defaults. AgEnD's own default is now", "`worker`, but an explicit setting wins and yours has not been changed.", "", "To take the new default, remove that line (or set it to `worker`).");
+    }
+    else if (alsoFull.length > 0) {
+        lines.push(`These instances are set to \`tool_set: full\` and keep every tool: ${alsoFull.join(", ")}.`, "AgEnD's default is now `worker`; an explicit setting wins and yours have not been changed.");
+    }
+    if (candidates.length > 0) {
+        if (lines.length > 0)
+            lines.push("");
+        lines.push(`${candidates.length} instance${candidates.length === 1 ? " has" : "s have"} used tools a worker does not get.`, "Mark them `tool_set: coordinator` so they keep working:", "");
+        for (const c of candidates) {
+            const used = c.refusedTools.map(([tool, count]) => `${tool}×${count}`).join(" ");
+            lines.push(`  ${c.instance}   ${used}`);
+        }
+        lines.push("", 
+        // The derivation only sees one of the three paths a tool call can take,
+        // so this says what it found rather than claiming it found everything.
+        "That list is what recent activity shows; an agent that has been quiet may still need marking.");
+    }
+    if (lines.length === 0)
+        return null;
+    return ["AgEnD tool permissions have changed.", "", ...lines].join("\n");
+}
+//# sourceMappingURL=tool-permissions-notice.js.map

package/dist/tool-permissions-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-permissions-notice.js","sourceRoot":"","sources":["../src/tool-permissions-notice.ts"],"names":[],"mappings":"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"}

package/dist/tool-permissions.d.ts

@@ -0,0 +1,120 @@
+export type ToolSetName = "full" | "standard" | "worker" | "coordinator" | "minimal" | "general";
+/**
+ * Three tiers plus the three that already existed.
+ *
+ * `general` is not `coordinator` plus channel I/O — it is deliberately smaller:
+ * a dispatcher has no business deleting instances or rewriting fleet defaults.
+ */
+export declare const TOOL_PROFILES: Readonly<Record<ToolSetName, readonly string[]>>;
+/**
+ * `Object.hasOwn`, not `in`.
+ *
+ * `"constructor" in PROFILE_SETS` is true — every object inherits it — so an
+ * instance whose `tool_set` was written as `constructor` or `__proto__` used to
+ * pass this check and then reach `PROFILE_SETS[...].has(...)` on a function,
+ * which throws inside the sink. A name that is not a profile has to answer no,
+ * whatever Object.prototype happens to carry.
+ */
+export declare function isToolSetName(value: unknown): value is ToolSetName;
+export declare function toolsFor(profile: ToolSetName): ReadonlySet<string>;
+export declare function mayUseTool(profile: ToolSetName, tool: string): boolean;
+/**
+ * Which profile an instance runs under.
+ *
+ * An explicit `tool_set` always wins, including `full`: a general that has been
+ * deliberately narrowed must stay narrowed, and a worker that has been
+ * deliberately widened must stay wide. Only when nothing was written does the
+ * role decide.
+ *
+ * `unsetDefault` is the answer for an ordinary instance that said nothing, and
+ * it is `"worker"`. It used to be every tool there is, which is what #804
+ * actually was: nobody chose to give a worker `create_instance`, it arrived by
+ * saying nothing. An instance that needs more says so.
+ *
+ * A value that is not a profile is not an explicit choice, and falls to the
+ * role rather than to the toolbox. Before, an unrecognised `AGEND_TOOL_SET`
+ * fell back to all 47 tools — a typo was the shortest path to maximum
+ * privilege, which is the wrong direction for a mistake to travel.
+ */
+export declare function resolveToolSet(config: {
+    tool_set?: string;
+    general_topic?: boolean;
+} | undefined, name: string, unsetDefault?: ToolSetName): ToolSetName;
+/**
+ * The profile for a process that only has the environment variable.
+ *
+ * mcp-server runs on the other side of a spawn and never sees fleet.yaml, so it
+ * resolves from `AGEND_TOOL_SET` alone. Same rules, same fallback, one function
+ * — the alternative is two copies of "what does an unknown name mean" that
+ * drift the first time one of them is edited.
+ */
+export declare function resolveToolSetFromEnv(value: string | undefined): ToolSetName;
+/**
+ * The IPC message types that reach a handler of their own.
+ *
+ * `fleet_outbound` carries its tool name in the body; everything below is a
+ * type that IS a tool, dispatched at `fleet-manager`'s IPC switch without ever
+ * passing through the outbound handler. They were invisible to the permission
+ * question until this table existed, which is how `update_decision` — a tool on
+ * the coordinator-only list — kept a way through.
+ */
+/**
+ * The tool an IPC message type means, or null if it is not one.
+ *
+ * Own-property only, for the same reason as `isToolSetName`: a message with
+ * `type: "constructor"` would otherwise pass the gate and hand a function to
+ * the permission check.
+ */
+export declare function toolForIpcType(type: unknown): string | null;
+export declare const IPC_TYPE_TOOLS: Readonly<Record<string, string>>;
+/**
+ * Agent-endpoint ops that never reach its `OP_MAP`.
+ *
+ * `dispatchAgentOperation` answers these before the map is consulted, so a
+ * table built from the map alone would have six gaps in it.
+ */
+export declare const EARLY_AGENT_OP_TOOLS: Readonly<Record<string, string>>;
+/**
+ * What to say to an agent that was refused.
+ *
+ * It will read this as an instruction, so it says what to do instead rather
+ * than only what went wrong. Naming the profile matters too: "not allowed" with
+ * no reason invites retrying.
+ */
+export declare function toolRefusedMessage(profile: ToolSetName, tool: string): string;
+export type ScheduleOp = "create" | "update" | "delete";
+/**
+ * Whether a schedule write is allowed, decided on its TARGET (#895).
+ *
+ * Having the tool is not the control: a worker holds create/update/delete so it
+ * can schedule its own heartbeats and follow-ups. The control is here, and it
+ * is pure so every case can be enumerated in a test.
+ *
+ * - `caller` is the instance the SERVER resolved for the request — the IPC
+ *   connection or the agent token. Never a field of the request.
+ * - create: the target is `requestedTarget`, or the caller when omitted.
+ * - update: the existing schedule, AND `requestedTarget` when present. Checking
+ *   only the existing one would let a worker create a schedule for itself and
+ *   then `update {target: other}` — a bypass in two calls.
+ * - update/delete: a non-coordinator may only touch a schedule it OWNS, meaning
+ *   it targets the caller AND the caller created it. A heartbeat a coordinator
+ *   put on a worker stays the coordinator's to change.
+ *
+ * Returns null when allowed, or the refusal to hand back to the agent.
+ */
+export declare function scheduleOpRefusal(profile: ToolSetName, caller: string, op: ScheduleOp, subject: {
+    requestedTarget?: string | null;
+    existing?: {
+        target: string;
+        source: string;
+    } | null;
+}): string | null;
+/** Where a permission question came from. Recorded so the gaps stay visible. */
+export type ToolSink = "ipc-outbound" | "ipc-typed" | "agent-endpoint";
+export interface ToolUseRecord {
+    readonly sink: ToolSink;
+    readonly instance: string;
+    readonly profile: ToolSetName;
+    readonly tool: string;
+    readonly allowed: boolean;
+}

package/dist/tool-permissions.js

@@ -0,0 +1,277 @@
+/**
+ * One answer to "may this instance use this tool", for every way of asking.
+ *
+ * There are four ways an agent can reach a fleet tool and only one of them ever
+ * consulted a tool list:
+ *
+ * 1. MCP `tools/list` — the model sees a filtered menu.
+ * 2. MCP `tools/call` — takes the name it was given and forwards it. The filter
+ *    from (1) is never consulted, so a guessed name runs.
+ * 3. Writing `channel.sock` directly. It is a 0600 socket in the instance
+ *    directory and the backend CLI runs as the same user with a shell, so an
+ *    agent that can open a file can send `fleet_outbound` without mcp-server
+ *    existing at all.
+ * 4. `POST /agent` with `agent.token`, which every instance gets on every spawn
+ *    — not only the ones in cli mode.
+ *
+ * Which is why keeping a tool out of the schema is a way to spend fewer tokens
+ * and get a clearer error, and is not a control. The control is this module,
+ * called at the points where those four paths converge: the fleet's IPC
+ * dispatch and the agent endpoint. See
+ * `docs/design/coordinator-tool-perms.zh-TW.md`.
+ *
+ * Stage 1 wires the callers and records what they would have decided. Nothing
+ * here denies anything yet.
+ */
+import { TOOLS } from "./channel/mcp-tools.js";
+/** Everything an agent that is doing the work needs, and nothing that runs the fleet. */
+const WORKER = [
+    // Talking to people.
+    "reply", "react", "edit_message", "download_attachment",
+    // Talking to peers. `report_result` is why `standard` was never usable as a
+    // worker profile: without it the delegate → work → report protocol has no
+    // last step. `delegate_task` is here because it creates nothing and needs a
+    // target that already exists — it is `send_to_instance` with a correlation
+    // id, and a month of real traffic showed 572 of its 574 calls coming from
+    // instances this would otherwise have silenced.
+    "send_to_instance", "report_result", "request_information", "broadcast", "delegate_task",
+    // Knowing where it is and who is next to it. All read-only.
+    "list_instances", "describe_instance", "list_teams", "list_models",
+    "get_fleet_status", "get_fleet_config", "get_usage", "get_effort", "get_instance_logs",
+    "list_decisions", "list_schedules", "list_deployments", "validate_config",
+    // Its own things.
+    "task", "post_decision", "set_display_name", "set_description",
+    // Its own schedules. Present here, but not a free hand: scheduleOpRefusal
+    // limits a non-coordinator to schedules that target itself and that it
+    // created (#895). The target is the control, not whether the tool is listed.
+    "create_schedule", "update_schedule", "delete_schedule",
+    // The repo it works in: a lease on the work itself, not a way to run the fleet.
+    "checkout_repo", "release_repo",
+];
+/**
+ * The verbs that run the fleet rather than do the work.
+ *
+ * Every one of them either creates, destroys, silences or reconfigures
+ * something that belongs to somebody else.
+ */
+const ORCHESTRATION = [
+    "create_instance", "delete_instance", "replace_instance",
+    "start_instance", "stop_instance", "pause_instance", "wake_instance", "restart_instance",
+    "deploy_template", "teardown_deployment",
+    "create_team", "delete_team", "update_team",
+    "update_fleet_defaults", "update_instance_config",
+    // Changing a decision somebody else recorded; `post_decision` adds, and stays.
+    "update_decision",
+];
+const ALL_TOOLS = TOOLS.map(t => t.name);
+/**
+ * Three tiers plus the three that already existed.
+ *
+ * `general` is not `coordinator` plus channel I/O — it is deliberately smaller:
+ * a dispatcher has no business deleting instances or rewriting fleet defaults.
+ */
+export const TOOL_PROFILES = {
+    full: ALL_TOOLS,
+    worker: WORKER,
+    coordinator: [...WORKER, ...ORCHESTRATION],
+    general: [
+        "reply", "react", "edit_message", "download_attachment",
+        "list_teams", "list_instances", "describe_instance", "get_fleet_status", "get_usage", "get_effort", "list_models",
+        "send_to_instance", "delegate_task", "request_information", "report_result", "broadcast",
+        "create_instance", "start_instance", "restart_instance", "wake_instance",
+        "task", "list_decisions", "post_decision",
+        "create_schedule", "list_schedules", "update_schedule", "delete_schedule",
+    ],
+    standard: [
+        "reply", "react", "edit_message",
+        "send_to_instance", "broadcast", "list_instances", "describe_instance",
+        "list_decisions", "post_decision", "task", "set_display_name", "set_description",
+        "validate_config", "get_fleet_status", "get_usage", "get_effort", "get_instance_logs", "get_fleet_config",
+        // Self-scheduling, same scope as worker (#895).
+        "create_schedule", "list_schedules", "update_schedule", "delete_schedule",
+    ],
+    // No schedules: an explicit `minimal` is a deliberate narrowing, and three
+    // more schemas would cost the one profile whose point is having few.
+    minimal: ["reply", "send_to_instance", "list_decisions", "download_attachment"],
+};
+const PROFILE_SETS = Object.fromEntries(Object.entries(TOOL_PROFILES).map(([name, tools]) => [name, new Set(tools)]));
+/**
+ * `Object.hasOwn`, not `in`.
+ *
+ * `"constructor" in PROFILE_SETS` is true — every object inherits it — so an
+ * instance whose `tool_set` was written as `constructor` or `__proto__` used to
+ * pass this check and then reach `PROFILE_SETS[...].has(...)` on a function,
+ * which throws inside the sink. A name that is not a profile has to answer no,
+ * whatever Object.prototype happens to carry.
+ */
+export function isToolSetName(value) {
+    return typeof value === "string" && Object.hasOwn(PROFILE_SETS, value);
+}
+export function toolsFor(profile) {
+    return PROFILE_SETS[profile];
+}
+export function mayUseTool(profile, tool) {
+    return PROFILE_SETS[profile].has(tool);
+}
+/**
+ * Which profile an instance runs under.
+ *
+ * An explicit `tool_set` always wins, including `full`: a general that has been
+ * deliberately narrowed must stay narrowed, and a worker that has been
+ * deliberately widened must stay wide. Only when nothing was written does the
+ * role decide.
+ *
+ * `unsetDefault` is the answer for an ordinary instance that said nothing, and
+ * it is `"worker"`. It used to be every tool there is, which is what #804
+ * actually was: nobody chose to give a worker `create_instance`, it arrived by
+ * saying nothing. An instance that needs more says so.
+ *
+ * A value that is not a profile is not an explicit choice, and falls to the
+ * role rather than to the toolbox. Before, an unrecognised `AGEND_TOOL_SET`
+ * fell back to all 47 tools — a typo was the shortest path to maximum
+ * privilege, which is the wrong direction for a mistake to travel.
+ */
+export function resolveToolSet(config, name, unsetDefault = "worker") {
+    const explicit = config?.tool_set;
+    if (isToolSetName(explicit))
+        return explicit;
+    if (config?.general_topic === true || name === "general")
+        return "general";
+    return unsetDefault;
+}
+/**
+ * The profile for a process that only has the environment variable.
+ *
+ * mcp-server runs on the other side of a spawn and never sees fleet.yaml, so it
+ * resolves from `AGEND_TOOL_SET` alone. Same rules, same fallback, one function
+ * — the alternative is two copies of "what does an unknown name mean" that
+ * drift the first time one of them is edited.
+ */
+export function resolveToolSetFromEnv(value) {
+    if (!value)
+        return "full";
+    if (isToolSetName(value))
+        return value;
+    return "worker";
+}
+/**
+ * The IPC message types that reach a handler of their own.
+ *
+ * `fleet_outbound` carries its tool name in the body; everything below is a
+ * type that IS a tool, dispatched at `fleet-manager`'s IPC switch without ever
+ * passing through the outbound handler. They were invisible to the permission
+ * question until this table existed, which is how `update_decision` — a tool on
+ * the coordinator-only list — kept a way through.
+ */
+/**
+ * The tool an IPC message type means, or null if it is not one.
+ *
+ * Own-property only, for the same reason as `isToolSetName`: a message with
+ * `type: "constructor"` would otherwise pass the gate and hand a function to
+ * the permission check.
+ */
+export function toolForIpcType(type) {
+    return typeof type === "string" && Object.hasOwn(IPC_TYPE_TOOLS, type) ? IPC_TYPE_TOOLS[type] : null;
+}
+export const IPC_TYPE_TOOLS = {
+    fleet_schedule_create: "create_schedule",
+    fleet_schedule_list: "list_schedules",
+    fleet_schedule_update: "update_schedule",
+    fleet_schedule_delete: "delete_schedule",
+    fleet_decision_create: "post_decision",
+    fleet_decision_list: "list_decisions",
+    fleet_decision_update: "update_decision",
+    fleet_task: "task",
+    fleet_set_display_name: "set_display_name",
+    fleet_set_description: "set_description",
+};
+/**
+ * Agent-endpoint ops that never reach its `OP_MAP`.
+ *
+ * `dispatchAgentOperation` answers these before the map is consulted, so a
+ * table built from the map alone would have six gaps in it.
+ */
+export const EARLY_AGENT_OP_TOOLS = {
+    "schedule-create": "create_schedule",
+    "schedule-list": "list_schedules",
+    "schedule-update": "update_schedule",
+    "schedule-delete": "delete_schedule",
+    // `decision-post` is what agent-cli sends; the endpoint only looks at the
+    // prefix, so both spellings reach the same handler and both need a name.
+    "decision-post": "post_decision",
+    "decision-create": "post_decision",
+    "decision-list": "list_decisions",
+    "decision-update": "update_decision",
+    task: "task",
+    usage: "get_usage",
+    rename: "set_display_name",
+    "set-description": "set_description",
+};
+/**
+ * What to say to an agent that was refused.
+ *
+ * It will read this as an instruction, so it says what to do instead rather
+ * than only what went wrong. Naming the profile matters too: "not allowed" with
+ * no reason invites retrying.
+ */
+export function toolRefusedMessage(profile, tool) {
+    return `${tool} is not available to this instance: it runs with the "${profile}" tool set, and ${tool} belongs to a coordinator. `
+        + "Report what you need with report_result and let the coordinator do it, "
+        + 'or ask an administrator to set `tool_set: coordinator` for this instance.';
+}
+/**
+ * The profiles that may schedule work for, or manage the schedules of, OTHER
+ * instances. Everyone else may still schedule — for itself only.
+ */
+const SCHEDULES_OTHERS = new Set(["full", "coordinator", "general"]);
+/**
+ * Whether a schedule write is allowed, decided on its TARGET (#895).
+ *
+ * Having the tool is not the control: a worker holds create/update/delete so it
+ * can schedule its own heartbeats and follow-ups. The control is here, and it
+ * is pure so every case can be enumerated in a test.
+ *
+ * - `caller` is the instance the SERVER resolved for the request — the IPC
+ *   connection or the agent token. Never a field of the request.
+ * - create: the target is `requestedTarget`, or the caller when omitted.
+ * - update: the existing schedule, AND `requestedTarget` when present. Checking
+ *   only the existing one would let a worker create a schedule for itself and
+ *   then `update {target: other}` — a bypass in two calls.
+ * - update/delete: a non-coordinator may only touch a schedule it OWNS, meaning
+ *   it targets the caller AND the caller created it. A heartbeat a coordinator
+ *   put on a worker stays the coordinator's to change.
+ *
+ * Returns null when allowed, or the refusal to hand back to the agent.
+ */
+export function scheduleOpRefusal(profile, caller, op, subject) {
+    if (SCHEDULES_OTHERS.has(profile))
+        return null;
+    const tool = `${op}_schedule`;
+    const requested = subject.requestedTarget?.trim() || null;
+    if (op === "create") {
+        const target = requested ?? caller;
+        return target === caller ? null : scheduleRefusedMessage(profile, tool, caller, `schedule work for "${target}"`);
+    }
+    const existing = subject.existing;
+    // A schedule that does not exist is the scheduler's error to report; there
+    // is nothing here to own or not own.
+    if (!existing)
+        return null;
+    if (existing.target !== caller || existing.source !== caller) {
+        return scheduleRefusedMessage(profile, tool, caller, existing.target !== caller
+            ? `change a schedule that targets "${existing.target}"`
+            : `change a schedule "${existing.source}" set for you`);
+    }
+    if (op === "update" && requested && requested !== caller) {
+        return scheduleRefusedMessage(profile, tool, caller, `move a schedule onto "${requested}"`);
+    }
+    return null;
+}
+/** A schedule refusal the agent can act on, in the #884 shape: why, and what to do instead. */
+function scheduleRefusedMessage(profile, tool, caller, attempted) {
+    return `${tool} refused: under the "${profile}" tool set an instance may only manage its own schedules — `
+        + `ones that target it ("${caller}") and that it created — so it cannot ${attempted}. `
+        + "To schedule work for another instance, or change one set for you, ask a coordinator "
+        + "with report_result or send_to_instance.";
+}
+//# sourceMappingURL=tool-permissions.js.map

package/dist/tool-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-permissions.js","sourceRoot":"","sources":["../src/tool-permissions.ts"],"names":[],"mappings":"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"}

package/dist/topic-commands.js

@@ -98,6 +98,7 @@ export function clearCommandForBackend(backend) {
         case "kiro-cli":
         case "antigravity":
         case "opencode":
+        case "muse":
         case "mock":
             return "/clear";
         case "grok":