comisai 1.0.24 → 1.0.26

package/node_modules/@comis/daemon/dist/rpc/agent-handlers.js

@@ -16,6 +16,8 @@
 import { PerAgentConfigSchema } from "@comis/core";
 import { resolveWorkspaceDir, resolveOperationModel, resolveProviderFamily, OPERATION_TIER_MAP, DEFAULT_PROVIDER_KEYS, } from "@comis/agent";
 import { persistToConfig } from "./persist-to-config.js";
+import { writeInlineWorkspaceFiles, } from "./agent-inline-workspace.js";
+import { probeProviderAuth } from "./probe-provider-auth.js";
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -36,6 +38,16 @@ export function createAgentHandlers(deps) {
             if (deps.agents[agentId] !== undefined) {
                 throw new Error(`Agent already exists: ${agentId}`);
             }
+            // 260428-vyf L2: extract inlineContent BEFORE config processing.
+            // role/identity are write-once side-effects (ROLE.md / IDENTITY.md
+            // file writes), NOT durable state — they NEVER enter the persisted
+            // config patch. The L1 tool boundary is responsible for stripping
+            // them from `config.workspace` before this RPC is called; this
+            // handler only consumes the dedicated top-level `inlineContent`
+            // field. If a (mis)caller leaves them inside config.workspace, the
+            // downstream Zod strict-object will reject them — that's an
+            // explicit failure mode, not a silent drop.
+            const inlineContent = params.inlineContent ?? undefined;
             const config = params.config ?? {};
             // Strip workspacePath so new agents always get the auto-computed
             // isolated workspace (~/.comis/workspace-{agentId}) instead of
@@ -83,7 +95,46 @@ export function createAgentHandlers(deps) {
                         errorKind: "internal" }, "Agent hot-add failed");
                 }
             }
-            return { agentId, config: parsedConfig, created: true, workspaceDir: resolveWorkspaceDir(parsedConfig, agentId) };
+            const workspaceDir = resolveWorkspaceDir(parsedConfig, agentId);
+            // 260428-vyf L2: best-effort inline ROLE.md / IDENTITY.md write.
+            // Only invoke when inlineContent has at least one populated field
+            // AND the persistDeps logger is available (the helper requires a
+            // structured logger; the in-memory-only test path skips it).
+            let inlineWritesResult;
+            if (deps.persistDeps?.logger
+                && inlineContent
+                && (inlineContent.role !== undefined || inlineContent.identity !== undefined)) {
+                const writeResult = await writeInlineWorkspaceFiles({ logger: deps.persistDeps.logger }, { workspaceDir, agentId, role: inlineContent.role, identity: inlineContent.identity });
+                if (writeResult.ok) {
+                    inlineWritesResult = writeResult.value;
+                }
+                else {
+                    // Best-effort: don't fail the create. The helper has already
+                    // emitted a structured WARN for io / path_traversal. For the
+                    // oversize branch the helper does NOT log (the schema layer
+                    // is the canonical gate) — emit a defensive WARN here so the
+                    // daemon-side surface is not silent.
+                    if (writeResult.error.kind === "oversize") {
+                        deps.persistDeps.logger.warn({
+                            method: "agents.create",
+                            agentId,
+                            file: writeResult.error.file,
+                            limit: writeResult.error.limit,
+                            actual: writeResult.error.actual,
+                            hint: "Inline content exceeded size limit at helper layer (schema should have caught this); agent exists with template files.",
+                            errorKind: "validation",
+                        }, "Inline workspace content oversize");
+                    }
+                    inlineWritesResult = { ok: false, error: writeResult.error };
+                }
+            }
+            return {
+                agentId,
+                config: parsedConfig,
+                created: true,
+                workspaceDir,
+                ...(inlineWritesResult !== undefined ? { inlineWritesResult } : {}),
+            };
         },
         "agents.get": async (params) => {
             const agentId = params.agentId;
@@ -142,8 +193,36 @@ export function createAgentHandlers(deps) {
                         : existing.scheduler.heartbeat,
                 };
             }
+            // Preserve scalar fields on partial modelFailover updates. fallbackModels,
+            // authProfiles, and allowedModels are arrays -- they are replaced wholesale
+            // by the spread (no element-wise merge), which matches the documented
+            // "user provides the complete desired list" semantic. Scalar fields
+            // (cooldownInitialMs, cooldownMultiplier, cooldownCapMs, maxAttempts) are
+            // preserved when omitted from the patch.
+            if (config.modelFailover && existing.modelFailover) {
+                config.modelFailover = {
+                    ...existing.modelFailover,
+                    ...config.modelFailover,
+                };
+            }
             const merged = { ...existing, ...config };
             const parsedConfig = PerAgentConfigSchema.parse(merged);
+            // Probe provider API key when provider or model changes
+            const providerChanging = config.provider !== undefined && config.provider !== existing.provider;
+            const modelChanging = config.model !== undefined && config.model !== existing.model;
+            if ((providerChanging || modelChanging) && deps.providerEntries) {
+                const targetProvider = parsedConfig.provider;
+                const providerEntry = deps.providerEntries[targetProvider];
+                if (providerEntry?.apiKeyName && deps.secretManager) {
+                    const apiKey = deps.secretManager.get(providerEntry.apiKeyName);
+                    if (apiKey) {
+                        const probeResult = await probeProviderAuth(providerEntry.baseUrl, apiKey, parsedConfig.model);
+                        if (!probeResult.ok) {
+                            throw new Error(`Cannot switch agent "${agentId}" to provider "${targetProvider}": ${probeResult.error}`);
+                        }
+                    }
+                }
+            }
             deps.agents[agentId] = parsedConfig;
             // Best-effort persistence to config.yaml
             if (deps.persistDeps) {

package/node_modules/@comis/daemon/dist/rpc/agent-inline-workspace.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Best-effort writer for inline ROLE.md / IDENTITY.md content supplied via
+ * the L2 single-call agents.create path (260428-vyf).
+ *
+ * Collapses the previous 3-call agent-creation workflow
+ * (`agents_manage.create` -> `write(ROLE.md)` -> `write(IDENTITY.md)`)
+ * into a single RPC by writing both files atomically as a side-effect of
+ * the `agents.create` RPC. role/identity are write-once side-effects, NOT
+ * durable state — they never enter the persisted config.yaml.
+ *
+ * Defense-in-depth posture:
+ *  - Size limits enforced both at the TypeBox tool-param boundary
+ *    (maxLength 16384/4096) AND here, so a caller bypassing the tool layer
+ *    cannot push oversize content past the daemon.
+ *  - safePath(workspaceDir, "ROLE.md"|"IDENTITY.md") guards against any
+ *    workspaceDir whose computation could be poisoned upstream. The
+ *    filename is HARDCODED, not derived from input — defense in depth.
+ *  - Returns Result<T,E> on every code path (no thrown exceptions).
+ *
+ * @module
+ */
+import { type Result } from "@comis/shared";
+import type { ComisLogger } from "@comis/infra";
+export interface AgentInlineWorkspaceParams {
+    /** Already-resolved workspace directory (via resolveWorkspaceDir). */
+    workspaceDir: string;
+    /** Agent identifier — used for structured logging. */
+    agentId: string;
+    /** Optional inline ROLE.md content. */
+    role?: string;
+    /** Optional inline IDENTITY.md content. */
+    identity?: string;
+}
+export interface AgentInlineWorkspaceResult {
+    roleWritten: boolean;
+    identityWritten: boolean;
+    bytesWritten: number;
+}
+export type AgentInlineWorkspaceError = {
+    kind: "oversize";
+    file: "ROLE.md" | "IDENTITY.md";
+    limit: number;
+    actual: number;
+} | {
+    kind: "path_traversal";
+    file: "ROLE.md" | "IDENTITY.md";
+    message: string;
+} | {
+    kind: "io";
+    file: "ROLE.md" | "IDENTITY.md";
+    message: string;
+};
+export interface AgentInlineWorkspaceDeps {
+    logger: ComisLogger;
+}
+/**
+ * Write inline ROLE.md / IDENTITY.md content to the agent's workspace
+ * directory. Best-effort — the caller (`agents.create`) will surface a
+ * Result-shaped outcome on the RPC return so the L1 tool can build the
+ * appropriate next-step contract for the LLM.
+ *
+ * @param deps - Required structured logger.
+ * @param params - workspaceDir + agentId + optional role/identity content.
+ * @returns Result with per-file written flags + total byte count, or one
+ *          of three structured error kinds (oversize | path_traversal | io).
+ */
+export declare function writeInlineWorkspaceFiles(deps: AgentInlineWorkspaceDeps, params: AgentInlineWorkspaceParams): Promise<Result<AgentInlineWorkspaceResult, AgentInlineWorkspaceError>>;

package/node_modules/@comis/daemon/dist/rpc/agent-inline-workspace.js

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Best-effort writer for inline ROLE.md / IDENTITY.md content supplied via
+ * the L2 single-call agents.create path (260428-vyf).
+ *
+ * Collapses the previous 3-call agent-creation workflow
+ * (`agents_manage.create` -> `write(ROLE.md)` -> `write(IDENTITY.md)`)
+ * into a single RPC by writing both files atomically as a side-effect of
+ * the `agents.create` RPC. role/identity are write-once side-effects, NOT
+ * durable state — they never enter the persisted config.yaml.
+ *
+ * Defense-in-depth posture:
+ *  - Size limits enforced both at the TypeBox tool-param boundary
+ *    (maxLength 16384/4096) AND here, so a caller bypassing the tool layer
+ *    cannot push oversize content past the daemon.
+ *  - safePath(workspaceDir, "ROLE.md"|"IDENTITY.md") guards against any
+ *    workspaceDir whose computation could be poisoned upstream. The
+ *    filename is HARDCODED, not derived from input — defense in depth.
+ *  - Returns Result<T,E> on every code path (no thrown exceptions).
+ *
+ * @module
+ */
+import { writeFile } from "node:fs/promises";
+import { safePath, PathTraversalError } from "@comis/core";
+import { ok, err } from "@comis/shared";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Max ROLE.md inline content size (chars). Mirrored at the TypeBox layer. */
+const ROLE_MAX = 16384;
+/** Max IDENTITY.md inline content size (chars). Mirrored at the TypeBox layer. */
+const IDENTITY_MAX = 4096;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve target path via safePath, catching PathTraversalError.
+ * Returns Result so the caller can branch without try/catch on its own.
+ */
+function resolveTarget(workspaceDir, filename) {
+    try {
+        return ok(safePath(workspaceDir, filename));
+    }
+    catch (e) {
+        if (e instanceof PathTraversalError) {
+            return err({ kind: "path_traversal", file: filename, message: e.message });
+        }
+        // Unexpected non-traversal error from safePath — treat as IO surface;
+        // the caller will WARN-log and the create RPC will still succeed.
+        const message = e instanceof Error ? e.message : String(e);
+        return err({ kind: "io", file: filename, message });
+    }
+}
+/**
+ * Attempt a single file write. fs.writeFile rejection -> structured WARN +
+ * `{kind:"io"}` Result. Never throws.
+ */
+async function attemptWrite(deps, agentId, filename, targetPath, content) {
+    try {
+        await writeFile(targetPath, content, { encoding: "utf8" });
+        return ok(undefined);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        deps.logger.warn({
+            module: "daemon.rpc.agent-handlers",
+            agentId,
+            file: filename,
+            err: e,
+            hint: "Inline ROLE.md/IDENTITY.md write failed; agent exists with template files. User can call write() to customize.",
+            errorKind: "resource",
+        }, "Inline workspace file write failed");
+        return err({ kind: "io", file: filename, message });
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Write inline ROLE.md / IDENTITY.md content to the agent's workspace
+ * directory. Best-effort — the caller (`agents.create`) will surface a
+ * Result-shaped outcome on the RPC return so the L1 tool can build the
+ * appropriate next-step contract for the LLM.
+ *
+ * @param deps - Required structured logger.
+ * @param params - workspaceDir + agentId + optional role/identity content.
+ * @returns Result with per-file written flags + total byte count, or one
+ *          of three structured error kinds (oversize | path_traversal | io).
+ */
+export async function writeInlineWorkspaceFiles(deps, params) {
+    // Belt-and-braces size limits. Schema layer already enforces these, but
+    // a caller that bypasses the tool (e.g. direct RPC) must still be gated.
+    if (params.role !== undefined && params.role.length > ROLE_MAX) {
+        return err({ kind: "oversize", file: "ROLE.md", limit: ROLE_MAX, actual: params.role.length });
+    }
+    if (params.identity !== undefined && params.identity.length > IDENTITY_MAX) {
+        return err({
+            kind: "oversize",
+            file: "IDENTITY.md",
+            limit: IDENTITY_MAX,
+            actual: params.identity.length,
+        });
+    }
+    let roleWritten = false;
+    let identityWritten = false;
+    let bytesWritten = 0;
+    if (params.role !== undefined) {
+        const targetResult = resolveTarget(params.workspaceDir, "ROLE.md");
+        if (!targetResult.ok)
+            return targetResult;
+        const writeResult = await attemptWrite(deps, params.agentId, "ROLE.md", targetResult.value, params.role);
+        if (!writeResult.ok)
+            return writeResult;
+        roleWritten = true;
+        bytesWritten += params.role.length;
+    }
+    if (params.identity !== undefined) {
+        const targetResult = resolveTarget(params.workspaceDir, "IDENTITY.md");
+        if (!targetResult.ok)
+            return targetResult;
+        const writeResult = await attemptWrite(deps, params.agentId, "IDENTITY.md", targetResult.value, params.identity);
+        if (!writeResult.ok)
+            return writeResult;
+        identityWritten = true;
+        bytesWritten += params.identity.length;
+    }
+    // Emit canonical INFO log only when at least one file was written.
+    // Pure no-op invocations (both fields absent) stay silent.
+    if (roleWritten || identityWritten) {
+        deps.logger.info({
+            module: "daemon.rpc.agent-handlers",
+            agentId: params.agentId,
+            roleBytes: roleWritten ? params.role.length : 0,
+            identityBytes: identityWritten ? params.identity.length : 0,
+            hint: "customized inline workspace ROLE.md+IDENTITY.md skips the post-create write() roundtrip",
+        }, "Wrote inline workspace files (ROLE.md + IDENTITY.md) on agents.create");
+    }
+    return ok({ roleWritten, identityWritten, bytesWritten });
+}

package/node_modules/@comis/daemon/dist/rpc/model-handlers.d.ts

@@ -7,6 +7,7 @@
  * @module
  */
 import type { ModelCatalog } from "@comis/agent";
+import type { ProviderEntry } from "@comis/core";
 import type { RpcHandler } from "./types.js";
 /** Dependencies required by model management RPC handlers. */
 export interface ModelHandlerDeps {
@@ -17,6 +18,8 @@ export interface ModelHandlerDeps {
         provider: string;
         model: string;
     }>;
+    /** Custom provider entries from config.yaml for fallback when catalog is empty. */
+    providerEntries?: Record<string, ProviderEntry>;
 }
 /**
  * Create a record of model management RPC handlers bound to the given deps.

package/node_modules/@comis/daemon/dist/rpc/model-handlers.js

@@ -72,14 +72,15 @@ export function createModelHandlers(deps) {
             // Find all agents that use this provider
             const matchingAgents = Object.entries(deps.agents).filter(([, a]) => a.provider === provider);
             if (matchingAgents.length === 0) {
-                // Include catalog info so the LLM knows models exist even when
-                // no agent is wired to this provider yet.
                 const modelsInCatalog = deps.modelCatalog.getByProvider(provider);
+                const providerEntry = deps.providerEntries?.[provider];
+                const customModelCount = providerEntry?.enabled ? providerEntry.models.length : 0;
                 return {
                     provider,
                     status: "not_configured",
                     message: "No agents use this provider",
                     modelsInCatalog: modelsInCatalog.length,
+                    ...(customModelCount > 0 ? { customModels: customModelCount } : {}),
                     hint: "To switch to this provider, use agents_manage with action 'update' " +
                         "to set the agent's provider and model. " +
                         "Example: agents_manage({ action: 'update', agent_id: '<id>', " +
@@ -88,11 +89,34 @@ export function createModelHandlers(deps) {
             }
             // Check catalog availability for this provider
             const modelsInCatalog = deps.modelCatalog.getByProvider(provider);
+            if (modelsInCatalog.length > 0) {
+                return {
+                    provider,
+                    status: "available",
+                    modelsAvailable: modelsInCatalog.length,
+                    validatedModels: modelsInCatalog.filter((m) => m.validated).length,
+                    agentsUsing: matchingAgents.map(([id, a]) => ({ agentId: id, model: a.model })),
+                };
+            }
+            // Catalog empty — check custom provider entries (custom providers
+            // register with the pi ModelRegistry for routing but are not in the
+            // static ModelCatalog used by this management tool).
+            const providerEntry = deps.providerEntries?.[provider];
+            if (providerEntry && providerEntry.enabled && providerEntry.models.length > 0) {
+                return {
+                    provider,
+                    status: "available",
+                    source: "custom_provider",
+                    modelsAvailable: providerEntry.models.length,
+                    models: providerEntry.models.map((m) => m.id),
+                    agentsUsing: matchingAgents.map(([id, a]) => ({ agentId: id, model: a.model })),
+                };
+            }
             return {
                 provider,
-                status: modelsInCatalog.length > 0 ? "available" : "no_models",
-                modelsAvailable: modelsInCatalog.length,
-                validatedModels: modelsInCatalog.filter((m) => m.validated).length,
+                status: "no_models",
+                modelsAvailable: 0,
+                validatedModels: 0,
                 agentsUsing: matchingAgents.map(([id, a]) => ({ agentId: id, model: a.model })),
             };
         },

package/node_modules/@comis/daemon/dist/rpc/probe-provider-auth.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Lightweight HTTP probe to validate a provider API key before committing
+ * the provider config to config.yaml.
+ *
+ * Uses a minimal chat/completions request (max_tokens: 1) rather than
+ * GET /models because some providers (nvidia NIM) return 200 on /models
+ * but 403 on the completions endpoint — the only reliable auth check is
+ * hitting the endpoint that will actually be called.
+ *
+ * Design:
+ * - Only 401/403 are treated as definitive auth failures (block config commit).
+ * - 5xx, 4xx (other than auth), network errors, and timeouts return ok()
+ *   so they do NOT block config changes.
+ * - Empty baseUrl or apiKey short-circuits to ok() (nothing to probe).
+ * - Uses AbortSignal.timeout to cap probe duration (default 5 s).
+ *
+ * @module
+ */
+import { type Result } from "@comis/shared";
+/**
+ * Probe a provider endpoint to verify the API key is accepted.
+ *
+ * @param baseUrl  - Provider API base URL (e.g. "https://api.openai.com/v1")
+ * @param apiKey   - The secret API key value
+ * @param model    - Model ID to use in the probe request (e.g. "gpt-4o")
+ * @param timeoutMs - Maximum probe duration in milliseconds (default 5000)
+ * @returns ok(undefined) if the key appears valid or the check is inconclusive;
+ *          err(string) if the provider explicitly rejected the key (401/403).
+ */
+export declare function probeProviderAuth(baseUrl: string, apiKey: string, model?: string, timeoutMs?: number): Promise<Result<void, string>>;

package/node_modules/@comis/daemon/dist/rpc/probe-provider-auth.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Lightweight HTTP probe to validate a provider API key before committing
+ * the provider config to config.yaml.
+ *
+ * Uses a minimal chat/completions request (max_tokens: 1) rather than
+ * GET /models because some providers (nvidia NIM) return 200 on /models
+ * but 403 on the completions endpoint — the only reliable auth check is
+ * hitting the endpoint that will actually be called.
+ *
+ * Design:
+ * - Only 401/403 are treated as definitive auth failures (block config commit).
+ * - 5xx, 4xx (other than auth), network errors, and timeouts return ok()
+ *   so they do NOT block config changes.
+ * - Empty baseUrl or apiKey short-circuits to ok() (nothing to probe).
+ * - Uses AbortSignal.timeout to cap probe duration (default 5 s).
+ *
+ * @module
+ */
+import { ok, err } from "@comis/shared";
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Probe a provider endpoint to verify the API key is accepted.
+ *
+ * @param baseUrl  - Provider API base URL (e.g. "https://api.openai.com/v1")
+ * @param apiKey   - The secret API key value
+ * @param model    - Model ID to use in the probe request (e.g. "gpt-4o")
+ * @param timeoutMs - Maximum probe duration in milliseconds (default 5000)
+ * @returns ok(undefined) if the key appears valid or the check is inconclusive;
+ *          err(string) if the provider explicitly rejected the key (401/403).
+ */
+export async function probeProviderAuth(baseUrl, apiKey, model, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    if (!baseUrl || !apiKey)
+        return ok(undefined);
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: model ?? "test",
+                messages: [{ role: "user", content: "hi" }],
+                max_tokens: 1,
+            }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch {
+        return ok(undefined);
+    }
+    if (response.status === 401 || response.status === 403) {
+        return err(`API key rejected by provider (HTTP ${response.status}). ` +
+            `Verify the key is correct and has not expired.`);
+    }
+    return ok(undefined);
+}

package/node_modules/@comis/daemon/dist/rpc/provider-handlers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Provider management RPC handler module.
+ * Provides 7 handlers for runtime LLM provider management:
+ *   providers.list    - List all providers with summary and apiKeyConfigured state
+ *   providers.get     - Retrieve full provider config plus agentsUsing list
+ *   providers.create  - Register a new provider entry with validation
+ *   providers.update  - Patch an existing provider config with merge semantics
+ *   providers.delete  - Remove a provider (blocked if agents reference it)
+ *   providers.enable  - Set enabled:true on a disabled provider
+ *   providers.disable - Set enabled:false (warns but does not block on references)
+ *
+ * Follows the same factory pattern as agent-handlers.ts. Each handler validates
+ * input, operates on the runtime providerEntries map, and returns structured results.
+ * API key values are NEVER exposed -- only apiKeyName references and apiKeyConfigured state.
+ * @module
+ */
+import type { ProviderEntry, PerAgentConfig } from "@comis/core";
+import { type PersistToConfigDeps } from "./persist-to-config.js";
+import type { RpcHandler } from "./types.js";
+/** Dependencies required by provider management RPC handlers. */
+export interface ProviderHandlerDeps {
+    /** Live provider entries map (NOT a spread copy -- mutations are same-object visible). */
+    providerEntries: Record<string, ProviderEntry>;
+    /** Runtime agents map for reference checks. */
+    agents: Record<string, PerAgentConfig>;
+    /** Optional persistence deps for writing changes to config.yaml. */
+    persistDeps?: PersistToConfigDeps;
+    /** SecretManager for apiKeyConfigured three-state and probe key retrieval. */
+    secretManager?: {
+        has(key: string): boolean;
+        get(key: string): string | undefined;
+    };
+}
+/**
+ * Create a record of provider management RPC handlers bound to the given deps.
+ */
+export declare function createProviderHandlers(deps: ProviderHandlerDeps): Record<string, RpcHandler>;