@tea-agent/loop-agent 0.38.1 → 0.38.3

package/dist/shared/operator/capabilities.js

@@ -13,13 +13,45 @@ const CONTROLLER_PROTOCOL_CAPABILITIES = [
     "worker-attempt-revision-v1",
     "recovery-decision-v2",
 ];
-function officialModelCallable(coverage, kind) {
+function officialModelCallable(coverage, _kind) {
     if (coverage === "human-gated-required")
         return "prepare-only";
-    if (coverage === "advanced" && kind !== "read")
+    // 2026-08-18: advanced actions (read or mutation) stay OUT of the model
+    // tool surface — low-frequency/forensic commands with generic args[] params
+    // diluted model attention. They remain dispatchable via UI capabilities.
+    if (coverage === "advanced")
         return "never";
     return "always";
 }
+const OFFICIAL_ACTION_DESCRIPTIONS = {
+    dagDecisionInspect: "Inspect a pending DAG decision envelope (inputs, options, chosen branch). Use before advising the operator on approve/reject; read-only.",
+    dagDecisionValidate: "Validate a DAG decision envelope against its schema. Use when a decision payload looks malformed or a writer emitted a suspect envelope; read-only.",
+    dagCloseoutDraft: "Draft the closeout handoff document for a finished DAG run. Use when the run is FINISHED and you need the handoff text; read-only.",
+    planList: "List execution plans in the repository. Use to discover plan ids before plan create/complete/check.",
+    planCreate: "Create an execution plan from a summary. Use to record the next work block before starting it.",
+    planComplete: "Mark an execution plan complete with a summary of what was delivered. Use after a work block is done and verified.",
+    planCheck: "Check execution-plan health and drift. Use to audit plan state without mutating anything.",
+    docsAudit: "Audit docs freshness and links (document catalog policy). Use when asked whether docs are stale or need review.",
+    handoffCheck: "Check handoff document completeness against the verification matrix. Use before claiming a task is fully handed off.",
+    handoffCoverage: "Show verification coverage across tests/docs/links for the repo. Use when asked what is verified and what is not.",
+    coverageReport: "Produce the verification coverage report. Use for a structured view of tests vs requirements.",
+    stats: "Repository workflow statistics (tasks, runs, durations). Use for quantitative status questions.",
+    promoteRun: "Task advance alias; passes a task id and flags through to task advance to promote a run. Does not pre-verify run state here — confirm with dagReport that the run is FINISHED before calling.",
+    closeoutTask: "Task advance alias; passes a task id and flags through to task advance to close out a task. Confirm the task's work is delivered and verified before calling.",
+    knowledgeCurate: "Generate knowledge-base curation proposals (may write a proposal file when --output is passed). Write-capable; use via the operator CLI, not as a model tool.",
+    knowledgeQuery: "Query the repository knowledge base. Use instead of re-reading files when a curated answer may exist.",
+    workerFeatureReview: "Review worker feature status and checkpoints (agent-worker). Use to see where a feature line stands.",
+    workerFeatureDoctor: "Diagnose worker feature health (agent-worker). Use when a feature line looks stuck or inconsistent.",
+    workerTaskValidate: "Validate a worker task spec (agent-worker). Use before queuing or when a task looks malformed.",
+    workerBatchPlanReady: "Show which batch tasks are ready to run (agent-worker). Use for queue triage before workerBatchRunReady.",
+    workerReportMorning: "Morning report for overnight worker activity (agent-worker). Use at the start of a session to catch overnight failures.",
+    workerReportMetrics: "Worker throughput and failure metrics (agent-worker). Use for quantitative worker questions.",
+    workerAdmissionShow: "Show night admission queue state (agent-worker). Use before night-scheduler mutations.",
+    workerSchedulerList: "List night-scheduler schedules (agent-worker). Use to discover schedule ids.",
+    workerSchedulerStatus: "Night-scheduler status overview (agent-worker). Use to check whether overnight jobs are healthy.",
+    workerSchedulerLedger: "Night-scheduler harvest ledger (agent-worker). Use to audit what overnight runs produced.",
+    workerSchedulerDoctor: "Diagnose night-scheduler health (agent-worker). Use when overnight jobs fail to fire or harvest.",
+};
 const officialAction = (action, cli, kind, coverage) => ({
     action,
     cli,
@@ -38,7 +70,8 @@ const officialAction = (action, cli, kind, coverage) => ({
             "TRANSACTION_INCOMPLETE",
             "NOT_FOUND",
         ],
-    description: `Official CLI action coverage for ${cli}.`,
+    description: OFFICIAL_ACTION_DESCRIPTIONS[action] ??
+        `Official CLI action coverage for ${cli}.`,
     inputParams: [
         {
             name: "args",
@@ -158,8 +191,8 @@ const OFFICIAL_ACTIONS = [
         [
             "knowledgeCurate",
             "loop-agent knowledge curate",
-            "read",
-            "model-callable",
+            "mutation",
+            "advanced",
         ],
         ["knowledgeQuery", "loop-agent knowledge query", "read", "model-callable"],
         [
@@ -334,6 +367,12 @@ const OFFICIAL_ACTIONS = [
         ],
     ],
 ].map(([action, cli, kind, coverage]) => officialAction(action, cli, kind, coverage));
+/**
+ * Action ids produced by the officialAction() factory (the generic CLI
+ * coverage tail). Derived from the same tuple table so dispatcher / gate
+ * checks do not string-match descriptions.
+ */
+export const OFFICIAL_TAIL_ACTION_IDS = new Set(OFFICIAL_ACTIONS.map((entry) => entry.action));
 /** Shared constants so dag + dagSpecVersions cannot diverge. */
 const DAG_SPEC_SUPPORTED_PARSE = [1, 2, 3, 4];
 const DAG_SPEC_NEW_WRITER_DEFAULT = 4;
@@ -609,7 +648,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: [...COMMON_MUTATION_ERRORS],
-            description: "Create or advance a task via the single lifecycle mutation entry.",
+            description: "Create a new task (lifecycle entry). Prefer taskAdvance for the standard flow (PRD import, taskKind, boundaries, DAG generation); newTask only bootstraps a task id + title.",
             inputParams: [
                 {
                     name: "taskId",
@@ -685,7 +724,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
-            description: "Read source instruction contract for a task.",
+            description: "Read the task's source instruction contract (需求.md/执行约束.md projection: requirements, constraints, allowed/forbidden paths). Use before drafting or revising a contract to stay aligned with the source.",
             inputParams: [
                 {
                     name: "taskId",
@@ -835,8 +874,33 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
-            description: "Build Observe deep link from stable object identity.",
-            inputParams: [],
+            description: "Build Observe deep link from stable object identity. Pass exactly one of dagRunId (preferred), taskId (resolves to latest run), featureId, or workerRunId; omit all for the Console home link.",
+            inputParams: [
+                {
+                    name: "dagRunId",
+                    type: "string",
+                    required: false,
+                    description: "dag run id; deep-links to #/dag/<runId> (preferred when known)",
+                },
+                {
+                    name: "taskId",
+                    type: "string",
+                    required: false,
+                    description: "task id; resolves to the latest dag run when one exists, else #/task/<taskId>",
+                },
+                {
+                    name: "featureId",
+                    type: "string",
+                    required: false,
+                    description: "feature line id; deep-links to the feature view",
+                },
+                {
+                    name: "workerRunId",
+                    type: "string",
+                    required: false,
+                    description: "worker run id; deep-links to the worker run view",
+                },
+            ],
             modelCallable: "always",
             humanConfirmation: "none",
         },
@@ -848,7 +912,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT"],
-            description: "Repo preflight (registry entry; envelope migration follow-up).",
+            description: "Preflight a repository for loop-agent: checks harness presence, task-pool layout, and reports what the Console can operate on. Use at session start on an unfamiliar repo, before init/upgrade decisions.",
             inputParams: [],
             modelCallable: "always",
             humanConfirmation: "none",
@@ -907,7 +971,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
-            description: "Task lifecycle status (read-only).",
+            description: "Read one task's lifecycle status: state, blockers, gates, contract revision, run associations. Use for task-level questions; use dagStatus for a specific DAG run's live node/liveness.",
             inputParams: [
                 {
                     name: "taskId",
@@ -927,7 +991,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["NOT_FOUND", "INVALID_INPUT"],
-            description: "Spine audit (registry entry).",
+            description: "Audit a task's minimal spec spine: source docs, path ownership, requirement ids, final verification coverage. Use before closing out a task to confirm every AC is verified.",
             inputParams: [
                 {
                     name: "taskId",
@@ -1020,7 +1084,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "EXTERNALLY_MODIFIED",
                 "INVALID_INPUT",
             ],
-            description: "Generate + strict-validate DAG via task advance (stops at writeSet gate).",
+            description: "Generate + strict-validate a task's DAG (via task advance, stops at the writeSet gate). Legacy entry; the standard flow is taskAdvance then prepareDagExecution + runDag.",
             inputParams: [
                 {
                     name: "taskId",
@@ -1099,7 +1163,7 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "NOT_FOUND"],
-            description: "Read-only check: can this failed run continue from fromNode? Call after dagReport; pass primaryFailure.nodeId. Does not execute. eligible=true returns planHash for dagRerun. eligible=false: Worker/Task Pool Failed → workerTaskRetry; standalone Console run → standaloneTaskRerun after any required contract adopt. Do not call dagRerun or invent a new task.",
+            description: "Read-only check for failed-node recovery; it does not execute. Call after dagReport with primaryFailure.nodeId. eligible=true returns the exact planHash required by dagRerun. eligible=false covers writer/decision/fingerprint, unsafe shell, Worker ownership, or workspace/controller drift: use workerTaskRetry for Worker/Task Pool failures, or standaloneTaskRerun after any required contract adopt for standalone runs. Do not force dagRerun or invent a new task.",
             inputParams: [
                 {
                     name: "runId",
@@ -1129,7 +1193,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "BINDING_DRIFT",
                 "INVALID_INPUT",
             ],
-            description: "Continue the same DAG from fromNode. Requires a fresh dagRerunPlan with eligible=true and that exact planHash. Prefer this for provider flake / safe downstream failures. Not a full task regenerate (that is standaloneTaskRerun). Server rejects stale planHash or binding drift.",
+            description: "Continue the same DAG from the effective failed node by creating a continuation run. Requires a fresh eligible dagRerunPlan and its exact planHash. Prefer this for provider, network, rate-limit, timeout, and other safe downstream failures. Not a full task regenerate: use standaloneTaskRerun for that. Server rejects stale planHash, binding, or fingerprint drift.",
             inputParams: [
                 {
                     name: "runId",
@@ -1495,7 +1559,7 @@ export function buildOperatorCapabilitiesDocument() {
                 "INVALID_INPUT",
                 "HUMAN_CONFIRMATION_REQUIRED",
             ],
-            description: "Regenerate the whole standalone DAG from the CURRENT contract, then validate and execute a new run (parent lineage kept). This is NOT continue-from-failed-node — that is dagRerun. Server rejects the call when dagRerunPlan is eligible, when primaryRecovery.humanRequired=true, or when run facts do not recommend rerun-task. Adopt contract changes before calling or the new DAG repeats the same failure.",
+            description: "Regenerate the whole standalone DAG from the CURRENT contract, then validate and execute a new run with parent lineage and the latest unresolved verify/review feedback when available. This is NOT continue-from-failed-node (use dagRerun for that). Server rejects the call when dagRerunPlan is eligible, primaryRecovery.humanRequired=true, or run facts do not recommend rerun-task. Feedback is recovery context, not a contract rewrite; adopt required contract changes before calling or the new DAG repeats the same failure.",
             inputParams: [
                 {
                     name: "runId",
@@ -2004,12 +2068,12 @@ export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
     },
     {
         command: "loop-agent knowledge curate",
-        coverage: "model-callable",
+        coverage: "advanced",
         action: "knowledgeCurate",
         source: "loop-agent",
+        note: "Writes knowledge proposals (conditional on --output); not model-callable.",
     },
-    {
-        command: "loop-agent knowledge query",
+    { command: "loop-agent knowledge query",
         coverage: "model-callable",
         action: "knowledgeQuery",
         source: "loop-agent",
@@ -2584,9 +2648,10 @@ export function assertCoverageManifestConsistent() {
                 capability.humanConfirmation !== "required"))
             throw new Error(`invalid required gate classification: ${entry.action}`);
         if (entry.coverage === "advanced") {
-            const expected = capability.kind === "read" ? "always" : "never";
-            if (capability.modelCallable !== expected) {
-                throw new Error(`invalid advanced classification: ${entry.action} (expected modelCallable=${expected} for kind=${capability.kind})`);
+            // 2026-08-18: advanced actions are never model-callable (read or
+            // mutation) — see officialModelCallable. UI dispatch stays available.
+            if (capability.modelCallable !== "never") {
+                throw new Error(`invalid advanced classification: ${entry.action} (expected modelCallable=never)`);
             }
         }
     }

package/dist/task/config-types.js

@@ -124,6 +124,26 @@ export const frontendTestConfigSchema = z.object({
         .strict()
         .optional(),
 });
+/** Backend-test artifact layout and pipeline mode configuration (plan A/B/D). */
+export const backendTestConfigSchema = z
+    .object({
+    /** Repository-relative test root. Default "testcase". */
+    testRoot: z.string().min(1).optional(),
+    /** Markdown subdirectory relative to testRoot. Default "md". */
+    markdownRel: z.string().min(1).optional(),
+    /** Pytest script subdirectory relative to testRoot. Default "." (testRoot itself). */
+    scriptRel: z.string().min(1).optional(),
+    /** User-provided shared setup document (plan B). Read-only bound source. */
+    sharedSetupDoc: z.string().min(1).optional(),
+    /** Pipeline mode: full 16-node chain (default) or gap-fill incremental DAG (plan D). */
+    mode: z.enum(["full", "gap-fill"]).optional(),
+    /** Required for mode=gap-fill: user missing-scenario document path. */
+    gapDoc: z.string().min(1).optional(),
+    /** gap-fill pytest execution scope: only affected items (default) or all eligible. */
+    executeScope: z.enum(["affected", "all"]).optional(),
+})
+    .strict()
+    .optional();
 export const convergenceConfigSchema = z.object({
     enabled: z.boolean().optional().default(false),
     maxPasses: z.number().int().positive().optional().default(3),
@@ -196,6 +216,8 @@ const taskConfigObjectSchema = z.object({
     frontendTest: frontendTestConfigSchema.optional(),
     /** Frontend OpenSpec gate policy and contract-declared required read paths. */
     frontendOpenspec: frontendOpenspecConfigSchema.optional(),
+    /** Backend-test layout / shared-setup / gap-fill configuration. */
+    backendTest: backendTestConfigSchema,
     notes: z.string().optional().default(""),
 });
 export const taskConfigSchema = z.preprocess((raw) => {

package/dist/task/contract/constants.js

@@ -17,6 +17,7 @@ export const MANAGED_TASK_CONFIG_FIELDS = [
     "forbiddenPaths",
     "hardConstraints",
     "verifyCommands",
+    "backendTest",
 ];
 export const CONTRACT_FILE_NAME = "contract.json";
 export const TRANSACTIONS_DIR_NAME = ".transactions";

package/dist/task/contract/diff.js

@@ -1,3 +1,4 @@
+import { canonicalizeJsonValue } from "./canonicalize.js";
 import { MANAGED_TASK_CONFIG_FIELDS } from "./constants.js";
 function maxRisk(a, b) {
     const order = ["routine", "elevated", "blocking"];
@@ -139,6 +140,31 @@ export function diffDraftAgainstCurrent(input) {
                 path: "task.json#featureId",
             });
         }
+        // backendTest is managed whole-object: an absent draft value means
+        // "keep existing" and never diffs; declared values compare canonically.
+        if (input.draft.backendTest !== undefined) {
+            const before = cfg.backendTest ?? {};
+            const after = input.draft.backendTest;
+            if (canonicalizeJsonValue(before) !== canonicalizeJsonValue(after)) {
+                changedManagedFields.push("backendTest");
+                risks.push({
+                    code: "BACKEND_TEST_CONFIG_CHANGED",
+                    level: "routine",
+                    message: "backendTest configuration changed",
+                    path: "task.json#backendTest",
+                });
+                const afterKeys = new Set(Object.keys(after));
+                const droppedKeys = Object.keys(before).filter((key) => !afterKeys.has(key));
+                if (droppedKeys.length > 0) {
+                    risks.push({
+                        code: "BACKEND_TEST_CONFIG_WEAKENED",
+                        level: "elevated",
+                        message: `drop backendTest keys: ${droppedKeys.sort().join(", ")}`,
+                        path: "task.json#backendTest",
+                    });
+                }
+            }
+        }
     }
     else {
         for (const field of MANAGED_TASK_CONFIG_FIELDS) {

package/dist/task/contract/project.js

@@ -174,6 +174,11 @@ export function mergeManagedTaskConfigFields(existing, draft) {
     if (draft.featureId !== undefined) {
         next.featureId = draft.featureId;
     }
+    // backendTest is whole-object replace when the draft declares it (`{}` is a
+    // legal explicit clear back to the default layout); absent keeps existing.
+    if (draft.backendTest !== undefined) {
+        next.backendTest = draft.backendTest;
+    }
     return next;
 }
 /**

package/dist/task/contract/schema.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { taskKindSchema, taskVerifyCommandSchema } from "../config-types.js";
+import { backendTestConfigSchema, taskKindSchema, taskVerifyCommandSchema, } from "../config-types.js";
 import { TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_CANONICALIZER_VERSION, TASK_CONTRACT_DRAFT_SCHEMA_VERSION, TASK_CONTRACT_PROJECTION_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
 const sha256Schema = z
     .string()
@@ -62,6 +62,11 @@ export const taskContractDraftSchema = z
     requirement: taskContractDraftRequirementSchema,
     constraints: taskContractDraftConstraintsSchema,
     verification: taskContractDraftVerificationSchema,
+    /**
+     * Managed backend-test layout / pipeline configuration projected into
+     * task.json#backendTest. Optional: absent means "keep existing".
+     */
+    backendTest: backendTestConfigSchema,
     references: z.array(taskContractDraftReferenceSchema).optional(),
     sourceResolutions: z
         .array(taskContractDraftSourceResolutionSchema)

package/dist/task/source-prepare/build-draft.js

@@ -22,6 +22,18 @@ function resolveTaskKindExplicit(flags, baseDraft) {
         return flags.taskKindExplicit;
     return baseDraft?.taskKindExplicit ?? false;
 }
+/**
+ * Resolve managed backend-test layout config.
+ * Precedence: explicit CLI flags > --from-draft base > existing task.json
+ * (the last tier self-heals tasks whose backendTest was hand-written).
+ */
+function resolveBackendTest(flags, baseDraft, existing) {
+    if (flags.backendTest !== undefined)
+        return flags.backendTest;
+    if (baseDraft?.backendTest !== undefined)
+        return baseDraft.backendTest;
+    return existing?.backendTest ?? undefined;
+}
 function resolveTitle(taskId, flags, facts, baseDraft, existing) {
     return (trimNonEmpty(flags.title) ??
         trimNonEmpty(baseDraft?.title) ??
@@ -205,6 +217,9 @@ export function buildPrepareDraft(input) {
     };
     if (featureId)
         draft.featureId = featureId;
+    const backendTest = resolveBackendTest(flags, baseDraft, existingTaskConfig);
+    if (backendTest !== undefined)
+        draft.backendTest = backendTest;
     if (references && references.length > 0) {
         draft.references = references.map((ref) => ({
             role: ref.role,

package/dist/worker/console/chat/deferred-turn.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+const IMAGE_MIME_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+export function hashDeferredTurnPayload(input) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        text: input.text,
+        images: input.images.map(({ type, mimeType, data }) => ({
+            type,
+            mimeType,
+            data,
+        })),
+    }))
+        .digest("hex");
+}
+export function parseDeferredTurn(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const item = value;
+    if (item.schemaVersion !== 1 ||
+        !Number.isSafeInteger(item.revision) ||
+        (item.revision ?? 0) < 1 ||
+        typeof item.clientRequestId !== "string" ||
+        !item.clientRequestId.trim() ||
+        typeof item.payloadHash !== "string" ||
+        !/^[a-f0-9]{64}$/.test(item.payloadHash) ||
+        typeof item.blockedByTurnId !== "string" ||
+        !item.blockedByTurnId.trim() ||
+        typeof item.text !== "string" ||
+        !Array.isArray(item.images) ||
+        !["queued", "dispatching", "accepted", "failed"].includes(item.state) ||
+        typeof item.createdAt !== "string" ||
+        typeof item.updatedAt !== "string") {
+        return undefined;
+    }
+    const images = [];
+    for (const image of item.images) {
+        if (!image || typeof image !== "object")
+            return undefined;
+        const candidate = image;
+        if (typeof candidate.name !== "string" ||
+            candidate.type !== "image" ||
+            typeof candidate.mimeType !== "string" ||
+            !IMAGE_MIME_TYPES.has(candidate.mimeType) ||
+            typeof candidate.data !== "string") {
+            return undefined;
+        }
+        images.push(candidate);
+    }
+    return {
+        schemaVersion: 1,
+        revision: item.revision,
+        clientRequestId: item.clientRequestId.trim(),
+        payloadHash: item.payloadHash,
+        blockedByTurnId: item.blockedByTurnId.trim(),
+        text: item.text,
+        images,
+        state: item.state,
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+        ...(typeof item.acceptedTurnId === "string" && item.acceptedTurnId
+            ? { acceptedTurnId: item.acceptedTurnId }
+            : {}),
+        ...(item.lastError &&
+            typeof item.lastError.code === "string" &&
+            typeof item.lastError.message === "string"
+            ? { lastError: { code: item.lastError.code, message: item.lastError.message } }
+            : {}),
+    };
+}
+export function projectDeferredTurnSummary(deferredTurn) {
+    if (!deferredTurn)
+        return null;
+    return {
+        revision: deferredTurn.revision,
+        clientRequestId: deferredTurn.clientRequestId,
+        blockedByTurnId: deferredTurn.blockedByTurnId,
+        state: deferredTurn.state,
+        updatedAt: deferredTurn.updatedAt,
+        textPreview: deferredTurn.text.replace(/\s+/g, " ").trim().slice(0, 120),
+        imageCount: deferredTurn.images.length,
+        ...(deferredTurn.acceptedTurnId
+            ? { acceptedTurnId: deferredTurn.acceptedTurnId }
+            : {}),
+        ...(deferredTurn.lastError ? { lastError: deferredTurn.lastError } : {}),
+    };
+}

package/dist/worker/console/chat/pi-runtime.js

@@ -228,19 +228,24 @@ async function buildCustomOperatorTools(options) {
         // TypeBox schema is built dynamically; cast through unknown to the builder
         // since Static<TParams> is structural and cannot be statically inferred here.
         const parameters = Type.Object(schema.inputParams.reduce((acc, param) => {
+            // Carry the registry's param description into the tool schema so
+            // the model sees parameter semantics, not just names/types.
+            const desc = param.description?.trim()
+                ? { description: param.description }
+                : {};
             let t;
             switch (param.type) {
                 case "string":
-                    t = Type.String();
+                    t = Type.String(desc);
                     break;
                 case "boolean":
-                    t = Type.Boolean();
+                    t = Type.Boolean(desc);
                     break;
                 case "number":
-                    t = Type.Number();
+                    t = Type.Number(desc);
                     break;
                 case "array":
-                    t = Type.Array(Type.String());
+                    t = Type.Array(Type.String({}), Object.keys(desc).length ? desc : {});
                     break;
                 default:
                     t = Type.Object({}, { additionalProperties: true });
@@ -252,7 +257,7 @@ async function buildCustomOperatorTools(options) {
             name: schema.toolId,
             label: schema.toolId,
             description: `${schema.description} (kind=${schema.kind}; cli: ${schema.cli})`,
-            promptSnippet: `${schema.toolId}: ${schema.description}`,
+            promptSnippet: schema.description,
             parameters: parameters,
             async execute(toolCallId, params) {
                 const decision = authorizeOperatorChatTool(schema.toolId);