comisai 1.0.25 → 1.0.27

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>;