comisai 1.0.25 → 1.0.26

package/node_modules/@comis/shared/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/shared",
   "private": true,
-  "version": "1.0.25",
+  "version": "1.0.26",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Shared types and utilities for the Comis platform",

package/node_modules/@comis/skills/dist/bridge/tool-metadata-registry.js

@@ -49,7 +49,6 @@ export function registerAllToolMetadata() {
     registerToolMetadata("sessions_list", { isReadOnly: true });
     registerToolMetadata("session_status", { isReadOnly: true });
     registerToolMetadata("sessions_history", { isReadOnly: true });
-    registerToolMetadata("agents_list", { isReadOnly: true });
     registerToolMetadata("ctx_search", { isReadOnly: true });
     registerToolMetadata("ctx_inspect", { isReadOnly: true });
     registerToolMetadata("ctx_expand", { isReadOnly: true });
@@ -324,7 +323,6 @@ export function registerAllToolMetadata() {
     registerToolMetadata("pipeline", { searchHint: "workflow dag graph orchestrate chain multi-step sequential" });
     registerToolMetadata("session_status", { searchHint: "session state alive running progress heartbeat check" });
     registerToolMetadata("session_search", { searchHint: "find session lookup filter match query user channel" });
-    registerToolMetadata("agents_list", { searchHint: "bots agents roster fleet inventory configured available" });
     // --- Platform tools ---
     registerToolMetadata("cron", { searchHint: "schedule timer reminder recurring job automation crontab interval" });
     registerToolMetadata("gateway", { searchHint: "config restart patch status settings yaml update system admin" });
@@ -346,7 +344,7 @@ export function registerAllToolMetadata() {
     registerToolMetadata("slack_action", { searchHint: "pin react thread channel topic archive bookmark slack" });
     registerToolMetadata("whatsapp_action", { searchHint: "status group admin label broadcast forward whatsapp" });
     // --- Privileged management tools ---
-    registerToolMetadata("agents_manage", { searchHint: "fleet create delete suspend resume agent configure workspace" });
+    registerToolMetadata("agents_manage", { searchHint: "fleet list create delete suspend resume agent configure roster inventory" });
     registerToolMetadata("obs_query", { searchHint: "diagnostics monitoring metrics billing traces logs health" });
     registerToolMetadata("sessions_manage", { searchHint: "delete reset export compact session lifecycle cleanup admin" });
     registerToolMetadata("memory_manage", { searchHint: "delete flush export browse stats storage cleanup purge" });

package/node_modules/@comis/skills/dist/builtin/platform/admin-manage-factory.js

@@ -12,6 +12,26 @@
 import { tryGetContext } from "@comis/core";
 import { jsonResult, readEnumParam, throwToolError, createTrustGuard, } from "./tool-helpers.js";
 // ---------------------------------------------------------------------------
+// AgentToolResult pass-through guard
+// ---------------------------------------------------------------------------
+/**
+ * Detect when an actionOverride has already produced a fully-formed
+ * `AgentToolResult` (multi-block content + typed `details`), so the factory
+ * passes it through verbatim instead of re-wrapping via `jsonResult`.
+ *
+ * Used by `agents_manage.create` (260428-sw2 Layer 1) to emit a 2-text-block
+ * tool_result: a high-attention next-step contract first, the JSON-rendered
+ * RPC fields second. The 7 sibling admin manage tools (cron/heartbeat/
+ * sessions/tokens/etc.) keep returning plain objects from their overrides --
+ * they hit the `jsonResult` branch unchanged. Additive, zero-impact change.
+ */
+function isAgentToolResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Array.isArray(value.content) &&
+        "details" in value);
+}
+// ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
 /**
@@ -70,7 +90,10 @@ export function createAdminManageTool(descriptor, rpcCall, approvalGate, callbac
                 if (descriptor.actionOverrides?.[action]) {
                     const result = await descriptor.actionOverrides[action](p, rpcCall, { agentId: ctx?.userId, trustLevel: _trustLevel });
                     if (result !== undefined) {
-                        return jsonResult(result);
+                        // Pass through pre-built AgentToolResult shapes (e.g. the
+                        // multi-text-block contract emitted by agents_manage.create);
+                        // wrap plain values via jsonResult as before.
+                        return isAgentToolResult(result) ? result : jsonResult(result);
                     }
                     // Fall through to default dispatch if override returns undefined
                 }

package/node_modules/@comis/skills/dist/builtin/platform/agents-manage-tool.d.ts

@@ -1,7 +1,7 @@
 /**
  * Agent management tool: multi-action tool for fleet management.
  *
- * Supports 6 actions: create, get, update, delete, suspend, resume.
+ * Supports 7 actions: create, get, update, delete, suspend, resume, list.
  * Destructive actions (create, delete) require approval via the ApprovalGate.
  * All actions enforce admin trust level via createTrustGuard.
  * Delegates to agents.* RPC handlers via rpcCall.
@@ -10,16 +10,22 @@
  */
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import type { ApprovalGate } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
 import type { RpcCall } from "./cron-tool.js";
-declare const AgentsManageToolParams: import("@sinclair/typebox").TObject<{
-    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"get">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"delete">, import("@sinclair/typebox").TLiteral<"suspend">, import("@sinclair/typebox").TLiteral<"resume">]>;
-    agent_id: import("@sinclair/typebox").TString;
+export declare const AgentsManageToolParams: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"get">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"delete">, import("@sinclair/typebox").TLiteral<"suspend">, import("@sinclair/typebox").TLiteral<"resume">, import("@sinclair/typebox").TLiteral<"list">]>;
+    agent_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     config: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
         name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         provider: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         maxSteps: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
         workspace_profile: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"full">, import("@sinclair/typebox").TLiteral<"specialist">]>>;
+        workspace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            profile: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"full">, import("@sinclair/typebox").TLiteral<"specialist">]>;
+            role: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            identity: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>;
         skills: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
             builtinTools: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
                 read: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -37,8 +43,44 @@ declare const AgentsManageToolParams: import("@sinclair/typebox").TObject<{
         }>>;
     }>, import("@sinclair/typebox").TString]>>;
 }>;
+export interface AgentInlineWritesValue {
+    roleWritten: boolean;
+    identityWritten: boolean;
+    bytesWritten: number;
+}
+export interface AgentInlineWritesError {
+    ok: false;
+    error: {
+        kind: "oversize" | "path_traversal" | "io";
+        file: "ROLE.md" | "IDENTITY.md";
+        [k: string]: unknown;
+    };
+}
+/**
+ * Build the post-create next-step contract emitted as the FIRST text block
+ * of the `agents_manage.create` tool_result. The freshest, uncached surface
+ * the LLM reads on every turn -- pinned here to fix the silent-termination
+ * bug where TOOL_GUIDE prescriptive text gets crowded out under high
+ * parallel-tool-call load (production session 1a8b0d91 turn 13: 9 sub-agents
+ * created in parallel, then a 0-text 0-thinking 0-tool turn).
+ *
+ * Pure string composition. No I/O, no Result<T,E> needed (per AGENTS.md
+ * §2.1: Result is for fallible paths only; this is infallible).
+ *
+ * Three branches keyed on `inlineWritesResult` (260428-vyf):
+ *  - BOTH written → SHORT contract: "No further setup needed — agent is
+ *    operationally ready". Skips the post-create write() roundtrip.
+ *  - PARTIAL (only one of role/identity written) → mixed contract pointing
+ *    only at the still-template file with a single "Next required action".
+ *  - NEITHER (or write failure / undefined) → existing 260428-sw2 2-step
+ *    contract verbatim, telling the LLM to call write() for ROLE.md.
+ *
+ * Case B (workspaceDir absent — defensive fallback): shorter form pinning
+ * "Customize {agentId}'s workspace ROLE.md and IDENTITY.md before using."
+ */
+export declare function buildCreateContract(agentId: string, workspaceDir: string | undefined, inlineWritesResult?: AgentInlineWritesValue | AgentInlineWritesError): string;
 /**
- * Create an agent management tool with 6 actions.
+ * Create an agent management tool with 7 actions.
  *
  * Actions:
  * - **create** -- Create a new agent (requires approval)
@@ -47,12 +89,17 @@ declare const AgentsManageToolParams: import("@sinclair/typebox").TObject<{
  * - **delete** -- Delete an agent (requires approval)
  * - **suspend** -- Suspend agent execution
  * - **resume** -- Resume a suspended agent
+ * - **list** -- List all available agent IDs
  *
  * @param rpcCall - RPC call function for delegating to the daemon backend
+ * @param logger - Required structured logger. Used to emit a per-create
+ *   INFO log pinning the next-step contract emission (260428-sw2 Layer 1).
+ *   Mirrors the gateway-tool required-logger position; no overload-with-
+ *   default-logger compat shim (per `feedback_no_backward_compat.md`).
  * @param approvalGate - Optional approval gate for create/delete actions
  * @returns AgentTool implementing the agent management interface
  */
-export declare function createAgentsManageTool(rpcCall: RpcCall, approvalGate?: ApprovalGate, callbacks?: {
+export declare function createAgentsManageTool(rpcCall: RpcCall, logger: ComisLogger, approvalGate?: ApprovalGate, callbacks?: {
     onMutationStart?: () => void;
     onMutationEnd?: () => void;
     /**
@@ -66,4 +113,3 @@ export declare function createAgentsManageTool(rpcCall: RpcCall, approvalGate?:
         workspaceDir?: string;
     }) => Promise<void> | void;
 }): AgentTool<typeof AgentsManageToolParams>;
-export {};

package/node_modules/@comis/skills/dist/builtin/platform/agents-manage-tool.js

@@ -2,7 +2,7 @@
 /**
  * Agent management tool: multi-action tool for fleet management.
  *
- * Supports 6 actions: create, get, update, delete, suspend, resume.
+ * Supports 7 actions: create, get, update, delete, suspend, resume, list.
  * Destructive actions (create, delete) require approval via the ApprovalGate.
  * All actions enforce admin trust level via createTrustGuard.
  * Delegates to agents.* RPC handlers via rpcCall.
@@ -15,7 +15,7 @@ import { createAdminManageTool } from "./admin-manage-factory.js";
 // ---------------------------------------------------------------------------
 // Parameter schema
 // ---------------------------------------------------------------------------
-const AgentsManageToolParams = Type.Object({
+export const AgentsManageToolParams = Type.Object({
     action: Type.Union([
         Type.Literal("create"),
         Type.Literal("get"),
@@ -23,10 +23,11 @@ const AgentsManageToolParams = Type.Object({
         Type.Literal("delete"),
         Type.Literal("suspend"),
         Type.Literal("resume"),
-    ], { description: "Agent management action. Valid values: create (new agent), get (read config/status), update (modify config), delete (remove agent), suspend (pause execution), resume (restart execution)" }),
-    agent_id: Type.String({
-        description: "The agent identifier (required for all actions)",
-    }),
+        Type.Literal("list"),
+    ], { description: "Agent management action. Valid values: create (new agent), get (read config/status), update (modify config), delete (remove agent), suspend (pause execution), resume (restart execution), list (all agent IDs)" }),
+    agent_id: Type.Optional(Type.String({
+        description: "The agent identifier (required for all actions except list)",
+    })),
     config: Type.Optional(
     // Accept EITHER a structured object OR a JSON string. Anthropic's LLM
     // sometimes emits nested free-form objects as stringified JSON; coerceConfig()
@@ -43,8 +44,41 @@ const AgentsManageToolParams = Type.Object({
             workspace_profile: Type.Optional(Type.Union([Type.Literal("full"), Type.Literal("specialist")], {
                 description: "Workspace profile controlling platform instruction verbosity. " +
                     "Valid values: full (~9K tokens, user-facing agents on channels), " +
-                    "specialist (~800 tokens, task workers and fleet sub-agents). " +
-                    "Default: full. Can be changed later via update action.",
+                    "specialist (~800 tokens, task workers and fleet sub-agents) ONLY. NO other values accepted. " +
+                    "Default: full. Can be changed later via update action. " +
+                    "Alternative shape: nested workspace.profile (see `workspace` field).",
+            })),
+            // 260428-oyc: declare nested workspace shape explicitly. The LLM
+            // sometimes emits `workspace: {profile: "specialist"}` directly
+            // (mirroring the downstream Zod schema-agent.ts:733-738 shape).
+            // Without this declaration, the unknown nested object slipped past
+            // TypeBox structurally but the enum was never validated -- invalid
+            // values would only be caught later at the Zod layer with a less
+            // actionable error path. Declaring it here makes both shapes
+            // first-class and gates the enum at the tool-validation boundary.
+            workspace: Type.Optional(Type.Object({
+                profile: Type.Union([Type.Literal("full"), Type.Literal("specialist")], {
+                    description: "Workspace profile (alternative to flat workspace_profile). Valid: full | specialist ONLY. NO other values accepted.",
+                }),
+                // 260428-vyf L2: inline ROLE.md / IDENTITY.md content. The tool
+                // handler strips these from the config payload BEFORE the RPC
+                // and forwards them as a separate top-level `inlineContent`
+                // param. The daemon writes them as files (write-once side-
+                // effect); they are NEVER persisted to config.yaml. When
+                // omitted, the seed templates remain in place and the LLM is
+                // instructed via the next-step contract to call write()
+                // afterward (the FALLBACK 2-step flow).
+                role: Type.Optional(Type.String({
+                    description: "Inline ROLE.md content. Written to <workspaceDir>/ROLE.md immediately on create. Should describe the agent's purpose, behavioral guidelines, domain conventions. Max 16384 chars. When omitted, ROLE.md is the unmodified seed template — call write() afterward to customize.",
+                    maxLength: 16384,
+                })),
+                identity: Type.Optional(Type.String({
+                    description: "Inline IDENTITY.md content. Written to <workspaceDir>/IDENTITY.md immediately on create. Should set name/creature/vibe/emoji/avatar/ethos for the agent. Max 4096 chars. When omitted, IDENTITY.md is the unmodified seed template.",
+                    maxLength: 4096,
+                })),
+            }, {
+                description: "Nested workspace configuration. Use this OR the flat workspace_profile field, not both. Optionally inline ROLE.md / IDENTITY.md via role/identity for single-call creation (PREFERRED for batch fleet creation).",
+                additionalProperties: false,
             })),
             skills: Type.Optional(Type.Object({
                 builtinTools: Type.Optional(Type.Object({
@@ -68,24 +102,95 @@ const AgentsManageToolParams = Type.Object({
         }),
     ])),
 });
-const VALID_ACTIONS = ["create", "get", "update", "delete", "suspend", "resume"];
+const VALID_ACTIONS = ["create", "get", "update", "delete", "suspend", "resume", "list"];
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 /**
  * Map flat workspace_profile param to nested workspace.profile config.
  * Mutates config in place.
+ *
+ * 260428-oyc: precedence is "flat wins" -- when both flat workspace_profile
+ * and nested workspace.profile are present, the flat field overwrites the
+ * nested one. This matches the existing spread semantics
+ * (`{...existing, profile}`) and keeps a single deterministic rule. When only
+ * nested is present (no `workspace_profile` key), this is a no-op and the
+ * nested shape flows through unchanged to the downstream Zod validator.
  */
 function mapWorkspaceProfile(config) {
-    if (config && "workspace_profile" in config) {
-        const wp = config;
-        const profile = wp.workspace_profile;
-        delete wp.workspace_profile;
-        if (typeof profile === "string") {
-            wp.workspace = { ...(wp.workspace ?? {}), profile };
-        }
+    if (!config)
+        return;
+    if (!("workspace_profile" in config)) {
+        // Nested-only or no workspace fields -- nothing to map. Downstream Zod
+        // (PerAgentConfigSchema.workspace) validates the nested shape directly.
+        return;
+    }
+    const profile = config.workspace_profile;
+    delete config.workspace_profile;
+    if (typeof profile === "string") {
+        config.workspace = {
+            ...(config.workspace ?? {}),
+            profile,
+        };
     }
 }
+/**
+ * Build the post-create next-step contract emitted as the FIRST text block
+ * of the `agents_manage.create` tool_result. The freshest, uncached surface
+ * the LLM reads on every turn -- pinned here to fix the silent-termination
+ * bug where TOOL_GUIDE prescriptive text gets crowded out under high
+ * parallel-tool-call load (production session 1a8b0d91 turn 13: 9 sub-agents
+ * created in parallel, then a 0-text 0-thinking 0-tool turn).
+ *
+ * Pure string composition. No I/O, no Result<T,E> needed (per AGENTS.md
+ * §2.1: Result is for fallible paths only; this is infallible).
+ *
+ * Three branches keyed on `inlineWritesResult` (260428-vyf):
+ *  - BOTH written → SHORT contract: "No further setup needed — agent is
+ *    operationally ready". Skips the post-create write() roundtrip.
+ *  - PARTIAL (only one of role/identity written) → mixed contract pointing
+ *    only at the still-template file with a single "Next required action".
+ *  - NEITHER (or write failure / undefined) → existing 260428-sw2 2-step
+ *    contract verbatim, telling the LLM to call write() for ROLE.md.
+ *
+ * Case B (workspaceDir absent — defensive fallback): shorter form pinning
+ * "Customize {agentId}'s workspace ROLE.md and IDENTITY.md before using."
+ */
+export function buildCreateContract(agentId, workspaceDir, inlineWritesResult) {
+    // BOTH written → SHORT operationally-ready contract.
+    if (workspaceDir !== undefined
+        && inlineWritesResult !== undefined
+        && "roleWritten" in inlineWritesResult
+        && inlineWritesResult.roleWritten
+        && inlineWritesResult.identityWritten) {
+        return `✓ Agent ${agentId} created at ${workspaceDir} with inline ROLE.md and IDENTITY.md (${inlineWritesResult.bytesWritten} bytes total). No further setup needed — agent is operationally ready.`;
+    }
+    // PARTIAL (exactly one of role/identity written).
+    if (workspaceDir !== undefined
+        && inlineWritesResult !== undefined
+        && "roleWritten" in inlineWritesResult
+        && (inlineWritesResult.roleWritten || inlineWritesResult.identityWritten)) {
+        const written = inlineWritesResult.roleWritten ? "ROLE.md" : "IDENTITY.md";
+        const remaining = inlineWritesResult.roleWritten ? "IDENTITY.md" : "ROLE.md";
+        return [
+            `✓ Agent ${agentId} created at ${workspaceDir} with inline ${written} (${inlineWritesResult.bytesWritten} bytes).`,
+            `⚠ ${remaining} is still the unmodified template.`,
+            `Next required action for this agent: call write({path: "${workspaceDir}/${remaining}", content: "..."}). This agent is NOT ready until ${remaining} is customized.`,
+        ].join("\n");
+    }
+    // NEITHER (no inlineContent supplied, write failure, or undefined): fall
+    // through to the existing 260428-sw2 2-step contract verbatim.
+    if (workspaceDir !== undefined) {
+        return [
+            `✓ Agent ${agentId} created at ${workspaceDir}.`,
+            `⚠ Workspace files are TEMPLATES — not yet operationally configured. Customize before use:`,
+            `  • ${workspaceDir}/ROLE.md      — purpose, behavioral guidelines, domain conventions`,
+            `  • ${workspaceDir}/IDENTITY.md  — name, creature, vibe, emoji`,
+            `Next required action for this agent: call write({path: "${workspaceDir}/ROLE.md", content: "..."}). This agent is NOT ready until ROLE.md is customized.`,
+        ].join("\n");
+    }
+    return `✓ Agent ${agentId} created. Customize ${agentId}'s workspace ROLE.md and IDENTITY.md before using.`;
+}
 /** Coerce config from JSON string to object if LLM double-encoded it. */
 function coerceConfig(p) {
     const raw = p.config;
@@ -104,7 +209,7 @@ function coerceConfig(p) {
 // Factory
 // ---------------------------------------------------------------------------
 /**
- * Create an agent management tool with 6 actions.
+ * Create an agent management tool with 7 actions.
  *
  * Actions:
  * - **create** -- Create a new agent (requires approval)
@@ -113,16 +218,21 @@ function coerceConfig(p) {
  * - **delete** -- Delete an agent (requires approval)
  * - **suspend** -- Suspend agent execution
  * - **resume** -- Resume a suspended agent
+ * - **list** -- List all available agent IDs
  *
  * @param rpcCall - RPC call function for delegating to the daemon backend
+ * @param logger - Required structured logger. Used to emit a per-create
+ *   INFO log pinning the next-step contract emission (260428-sw2 Layer 1).
+ *   Mirrors the gateway-tool required-logger position; no overload-with-
+ *   default-logger compat shim (per `feedback_no_backward_compat.md`).
  * @param approvalGate - Optional approval gate for create/delete actions
  * @returns AgentTool implementing the agent management interface
  */
-export function createAgentsManageTool(rpcCall, approvalGate, callbacks) {
+export function createAgentsManageTool(rpcCall, logger, approvalGate, callbacks) {
     return createAdminManageTool({
         name: "agents_manage",
         label: "Agent Management",
-        description: "Manage agent fleet: create, get, update, delete, suspend, resume. " +
+        description: "Manage agent fleet: create, get, update, delete, suspend, resume, list. " +
             "Use update to switch an agent's LLM provider or model (e.g. switch to Gemini, change model). " +
             "Create/delete require approval.",
         parameters: AgentsManageToolParams,
@@ -134,24 +244,105 @@ export function createAgentsManageTool(rpcCall, approvalGate, callbacks) {
                 const agentId = readStringParam(p, "agent_id");
                 const config = coerceConfig(p);
                 mapWorkspaceProfile(config);
+                // Map common LLM-hallucinated "system prompt" field names to
+                // workspace.role — the correct inline ROLE.md path. Runs after
+                // coerceConfig (catches string-form) and before L2 stripping.
+                if (config && typeof config === "object") {
+                    const ROLE_ALIASES = ["systemPrompt", "system", "prompt", "instructions", "systemMessage", "description"];
+                    const c = config;
+                    for (const alias of ROLE_ALIASES) {
+                        if (typeof c[alias] === "string") {
+                            const ws = (c.workspace ??= {});
+                            if (typeof ws.role !== "string")
+                                ws.role = c[alias];
+                            delete c[alias];
+                            break;
+                        }
+                    }
+                }
+                // 260428-vyf L2 (Path A): strip workspace.role / workspace.identity
+                // from the config payload BEFORE the RPC and forward them as a
+                // separate top-level `inlineContent` parameter. Rationale: the
+                // downstream Zod schema (PerAgentConfigSchema.workspace at
+                // packages/core/src/config/schema-agent.ts) is z.strictObject —
+                // unknown keys would trigger Zod `unrecognized_keys` rejection.
+                // role/identity are write-once side-effects (ROLE.md / IDENTITY.md
+                // file writes), NOT durable state — they MUST NOT leak into
+                // config.yaml. Path B (extending Zod schema-agent.ts) was
+                // rejected because it would persist them.
+                let inlineContent;
+                if (config && typeof config === "object") {
+                    const ws = config.workspace;
+                    if (ws && (typeof ws.role === "string" || typeof ws.identity === "string")) {
+                        inlineContent = {};
+                        if (typeof ws.role === "string") {
+                            inlineContent.role = ws.role;
+                            delete ws.role;
+                        }
+                        if (typeof ws.identity === "string") {
+                            inlineContent.identity = ws.identity;
+                            delete ws.identity;
+                        }
+                    }
+                }
                 callbacks?.onMutationStart?.();
                 try {
-                    const result = await rpcCall("agents.create", { agentId, config, _trustLevel: ctx.trustLevel });
+                    const rpcParams = { agentId, config, _trustLevel: ctx.trustLevel };
+                    if (inlineContent !== undefined)
+                        rpcParams.inlineContent = inlineContent;
+                    const result = await rpcCall("agents.create", rpcParams);
+                    // agentId is guaranteed non-undefined by readStringParam(required=true) above.
+                    const aid = agentId;
+                    const workspaceDir = result?.workspaceDir;
+                    const inlineWritesResult = result?.inlineWritesResult;
+                    // 260428-sw2 Layer 1 + 260428-vyf Layer 2: emit the next-step
+                    // contract on the freshest, uncached surface the LLM reads each
+                    // turn (the tool_result text). The contract has 3 branches keyed
+                    // on inlineWritesResult (see buildCreateContract). One structured
+                    // INFO log pins this happened.
+                    const contractText = buildCreateContract(aid, workspaceDir, inlineWritesResult);
+                    // Distinguish the 3 inline-write outcomes for observability.
+                    // "none"    — caller did not supply inlineContent
+                    // "written" — helper succeeded (full or partial)
+                    // "failed"  — helper returned err shape (oversize|path_traversal|io)
+                    const inlineWritesOutcome = inlineWritesResult === undefined
+                        ? "none"
+                        : "roleWritten" in inlineWritesResult
+                            ? "written"
+                            : "failed";
+                    logger.info({
+                        module: "skill.agents-manage",
+                        action: "create",
+                        agentId: aid,
+                        workspaceDir: workspaceDir ?? null,
+                        contractEmitted: true,
+                        inlineWritesOutcome,
+                    }, "agents_manage.create succeeded — next-step contract emitted");
                     // Best-effort seed registration hook. Fires only on successful
                     // RPC return. Callback failures are swallowed — the agent was
                     // created; tracker registration is an optimization, not a gate.
                     if (callbacks?.onAgentCreated) {
                         try {
-                            const workspaceDir = result?.workspaceDir;
-                            // agentId is guaranteed non-undefined by readStringParam(required=true) above.
-                            const aid = agentId;
                             await callbacks.onAgentCreated(workspaceDir !== undefined ? { agentId: aid, workspaceDir } : { agentId: aid });
                         }
                         catch {
                             /* non-fatal */
                         }
                     }
-                    return result;
+                    // Return a 2-text-block AgentToolResult passed through verbatim
+                    // by admin-manage-factory's isAgentToolResult guard:
+                    //  - block 0: the next-step contract (high-attention text)
+                    //  - block 1: the JSON-rendered RPC fields (preserves the
+                    //    structured view existing pin/regression tests assert)
+                    // `details` is the raw RPC return so result.details assertions
+                    // continue to pass unchanged.
+                    return {
+                        content: [
+                            { type: "text", text: contractText },
+                            { type: "text", text: JSON.stringify(result, null, 2) },
+                        ],
+                        details: result,
+                    };
                 }
                 finally {
                     callbacks?.onMutationEnd?.();
@@ -191,6 +382,9 @@ export function createAgentsManageTool(rpcCall, approvalGate, callbacks) {
                 const agentId = readStringParam(p, "agent_id");
                 return rpcCall("agents.resume", { agentId, _trustLevel: ctx.trustLevel });
             },
+            async list(_p, rpcCall, ctx) {
+                return rpcCall("agents.list", { _trustLevel: ctx.trustLevel });
+            },
         },
     }, rpcCall, approvalGate, callbacks);
 }

package/node_modules/@comis/skills/dist/builtin/platform/gateway-tool.d.ts

@@ -10,6 +10,7 @@
  */
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import type { RpcCall } from "./cron-tool.js";
+import type { ComisLogger } from "@comis/infra";
 /**
  * Canonical list of gateway tool actions. Single source of truth --
  * the Typebox `action` Union below and the bridge's pre-flight
@@ -49,7 +50,9 @@ declare const GatewayToolParams: import("@sinclair/typebox").TObject<{
  * - **env_list** -- List configured secret NAMES (admin-only, read-only). Use before asking the user for a key to check whether it is already configured. Values are never returned.
  *
  * @param rpcCall - RPC call function for delegating to the daemon backend
+ * @param logger - Structured logger for surfacing operator-relevant events
+ *   (e.g., the Docker restart-policy WARN on the `restart` action)
  * @returns AgentTool implementing the gateway control interface
  */
-export declare function createGatewayTool(rpcCall: RpcCall): AgentTool<typeof GatewayToolParams>;
+export declare function createGatewayTool(rpcCall: RpcCall, logger: ComisLogger): AgentTool<typeof GatewayToolParams>;
 export {};

package/node_modules/@comis/skills/dist/builtin/platform/gateway-tool.js

@@ -13,6 +13,7 @@ import { Type } from "@sinclair/typebox";
 import { tryGetContext, isImmutableConfigPath, MUTABLE_CONFIG_OVERRIDES, matchesOverridePattern, getMutableOverridesForSection, getManagedSectionRedirect, formatRedirectHint, } from "@comis/core";
 import { readStringParam, throwToolError, createActionGate, } from "./tool-helpers.js";
 import { createMultiActionDispatchTool } from "./messaging-factory.js";
+import { isDocker } from "@comis/infra";
 // ---------------------------------------------------------------------------
 // Canonical action list -- single source of truth
 // ---------------------------------------------------------------------------
@@ -98,9 +99,11 @@ const GatewayToolParams = Type.Object({
  * - **env_list** -- List configured secret NAMES (admin-only, read-only). Use before asking the user for a key to check whether it is already configured. Values are never returned.
  *
  * @param rpcCall - RPC call function for delegating to the daemon backend
+ * @param logger - Structured logger for surfacing operator-relevant events
+ *   (e.g., the Docker restart-policy WARN on the `restart` action)
  * @returns AgentTool implementing the gateway control interface
  */
-export function createGatewayTool(rpcCall) {
+export function createGatewayTool(rpcCall, logger) {
     const restartGate = createActionGate("gateway.restart");
     const patchGate = createActionGate("config.patch");
     const applyGate = createActionGate("config.apply");
@@ -162,6 +165,18 @@ export function createGatewayTool(rpcCall) {
                             hint: "Ask the user to confirm this restart, then call again with _confirmed: true.",
                         };
                     }
+                    // 260428-qrn: Inside Docker the restart relies entirely on the
+                    // container's restart policy to bring the daemon back. Surface
+                    // a structured WARN so the operator gets a breadcrumb in
+                    // `docker logs` pointing at `--restart unless-stopped`. Tool
+                    // result schema unchanged (Pino-only -- no extra content blocks).
+                    if (isDocker()) {
+                        logger.warn({
+                            hint: "Container must have --restart unless-stopped (or compose restart: unless-stopped) for the restart to bring it back. Otherwise run 'docker restart <name>' from your host after the daemon exits.",
+                            errorKind: "config",
+                            module: "skill.gateway",
+                        }, "Daemon restart requested inside Docker container — relies on container restart policy");
+                    }
                     return rpcCall("gateway.restart", { _trustLevel });
                 }
                 case "schema": {

package/node_modules/@comis/skills/dist/builtin/platform/index.d.ts

@@ -16,7 +16,6 @@ export { createSessionsHistoryTool } from "./sessions-history-tool.js";
 export { createSessionsSendTool } from "./sessions-send-tool.js";
 export { createSessionsSpawnTool } from "./sessions-spawn-tool.js";
 export { createSessionSearchTool } from "./session-search-tool.js";
-export { createAgentsListTool } from "./agents-list-tool.js";
 export { createSubagentsTool } from "./subagents-tool.js";
 export { createPipelineTool } from "./pipeline-tool.js";
 export { createRpcDispatchTool, createMultiActionDispatchTool } from "./messaging-factory.js";
@@ -53,6 +52,7 @@ export { createObsQueryTool } from "./obs-query-tool.js";
 export { createMemoryManageTool } from "./memory-manage-tool.js";
 export { createSessionsManageTool } from "./sessions-manage-tool.js";
 export { createModelsManageTool } from "./models-manage-tool.js";
+export { createProvidersManageTool } from "./providers-manage-tool.js";
 export { createTokensManageTool } from "./tokens-manage-tool.js";
 export { createChannelsManageTool } from "./channels-manage-tool.js";
 export { createSkillsManageTool } from "./skills-manage-tool.js";

package/node_modules/@comis/skills/dist/builtin/platform/index.js

@@ -19,7 +19,6 @@ export { createSessionsSendTool } from "./sessions-send-tool.js";
 export { createSessionsSpawnTool } from "./sessions-spawn-tool.js";
 export { createSessionSearchTool } from "./session-search-tool.js";
 // Agent tools
-export { createAgentsListTool } from "./agents-list-tool.js";
 export { createSubagentsTool } from "./subagents-tool.js";
 export { createPipelineTool } from "./pipeline-tool.js";
 // Messaging factory
@@ -66,6 +65,7 @@ export { createObsQueryTool } from "./obs-query-tool.js";
 export { createMemoryManageTool } from "./memory-manage-tool.js";
 export { createSessionsManageTool } from "./sessions-manage-tool.js";
 export { createModelsManageTool } from "./models-manage-tool.js";
+export { createProvidersManageTool } from "./providers-manage-tool.js";
 export { createTokensManageTool } from "./tokens-manage-tool.js";
 export { createChannelsManageTool } from "./channels-manage-tool.js";
 export { createSkillsManageTool } from "./skills-manage-tool.js";