comisai 1.0.34 → 1.0.37

package/node_modules/@comis/skills/dist/builtin/sandbox/detect-provider.js

@@ -10,7 +10,7 @@
  */
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { BwrapProvider } from "./bwrap-provider.js";
+import { BwrapProvider, SYSTEM_RO_PATHS } from "./bwrap-provider.js";
 import { SandboxExecProvider } from "./sandbox-exec-provider.js";
 /**
  * True when the daemon is running inside a Linux container. Docker writes
@@ -21,26 +21,42 @@ function isContainer() {
     return existsSync("/.dockerenv") || existsSync("/run/.containerenv");
 }
 /**
- * Smoke-test the bwrap binary against the isolation flags BwrapProvider
- * actually uses (--unshare-pid + --proc /proc). On Docker Desktop's linuxkit
- * kernel and similar restricted environments this combo EPERMs at the
- * procfs mount step, even with apparmor/seccomp unconfined — every later
- * exec call would silently fail. `available()` only checks if `bwrap` is on
- * PATH, so without this probe the daemon would log "provider: bwrap" even
- * when bwrap is non-functional. ~50ms one-shot at startup.
+ * Smoke-test bwrap against the same SYSTEM_RO_PATHS BwrapProvider.buildArgs()
+ * uses, plus --unshare-pid + --proc /proc — the kernel-feature combo we
+ * actually need to detect. Reusing the production bind list prevents drift
+ * (e.g. /lib64 must be present on usrmerge x86-64 hosts where /bin/true's
+ * dynamic linker lives there; without it the smoke spawn EPERMs at execvp
+ * even though the production sandbox itself runs fine).
+ *
+ * On Docker Desktop's linuxkit kernel and similar restricted environments
+ * --unshare-pid + --proc /proc EPERMs at the procfs mount step, even with
+ * apparmor/seccomp unconfined — every later exec call would silently fail.
+ * `available()` only checks if `bwrap` is on PATH, so without this probe the
+ * daemon would log "provider: bwrap" even when bwrap is non-functional.
+ * ~50ms one-shot at startup.
+ *
+ * Returns the raw `stderr` and `signal` from bwrap so the caller can include
+ * them in the warn payload — operators reading the log see the actual bwrap
+ * error message (e.g. "Creating new namespace failed: Operation not
+ * permitted") without having to enable DEBUG logging.
  */
 function bwrapSmokeTest() {
+    const sysBinds = SYSTEM_RO_PATHS
+        .filter((p) => existsSync(p))
+        .flatMap((p) => ["--ro-bind", p, p]);
     const r = spawnSync("bwrap", [
         "--unshare-user",
         "--unshare-pid",
         "--proc", "/proc",
-        "--ro-bind", "/usr", "/usr",
-        "--ro-bind", "/bin", "/bin",
-        "--ro-bind", "/lib", "/lib",
+        ...sysBinds,
         "--tmpfs", "/tmp",
         "/bin/true",
     ], { encoding: "utf8", timeout: 5000 });
-    return r.status === 0;
+    return {
+        ok: r.status === 0,
+        stderr: (r.stderr ?? "").trim(),
+        signal: r.signal ?? null,
+    };
 }
 /**
  * Detect and return the best available sandbox provider for this platform.
@@ -51,7 +67,8 @@ export function detectSandboxProvider(logger) {
     if (process.platform === "linux") {
         const bwrap = new BwrapProvider();
         if (bwrap.available()) {
-            if (!bwrapSmokeTest()) {
+            const smoke = bwrapSmokeTest();
+            if (!smoke.ok) {
                 // bwrap is on PATH but the kernel rejects the isolation flags
                 // (typically Docker Desktop's linuxkit on macOS/Windows). Behaviour
                 // diverges by environment:
@@ -69,17 +86,25 @@ export function detectSandboxProvider(logger) {
                 //    (rare on stock Linux). Surface it loudly and return the
                 //    provider so exec fails via bwrap's stderr until the operator
                 //    fixes the kernel/userns config — never silently degrade
-                //    sandboxing on a bare-metal host.
+                //    sandboxing on a bare-metal host. The warn payload now includes
+                //    `stderr` (the actual bwrap error) and `signal` so operators
+                //    don't have to enable DEBUG logging to diagnose; the hint
+                //    points at stderr first and demotes kernel sysctls to a
+                //    secondary fallback.
                 if (isContainer()) {
                     logger?.warn({
                         hint: "Kernel rejected --unshare-pid + --proc /proc (typically Docker Desktop linuxkit on macOS/Windows). Sandbox auto-disabled so agent exec is functional for development. PRODUCTION DEPLOYMENTS MUST USE A REAL LINUX HOST — see docs/operations/docker.mdx → Platform Support.",
                         errorKind: "config",
+                        stderr: smoke.stderr,
+                        signal: smoke.signal,
                     }, "Exec sandbox DISABLED (kernel limitation; container host) -- shell commands will run UNSANDBOXED. Dev/testing only.");
                     return undefined;
                 }
                 logger?.warn({
-                    hint: "Kernel rejected --unshare-pid + --proc /proc on a bare-metal host. Check `kernel.unprivileged_userns_clone` and AppArmor's `apparmor_restrict_unprivileged_userns`. Exec calls will fail until bwrap can run.",
+                    hint: "Check the `stderr` field above for the actual bwrap error — that's the primary signal. If stderr mentions namespaces or 'Operation not permitted' on a bare-metal host, then as a secondary diagnostic verify `sysctl kernel.unprivileged_userns_clone=1` and AppArmor's `apparmor_restrict_unprivileged_userns=0` (Ubuntu 23.10+). Exec calls will fail until bwrap can run.",
                     errorKind: "config",
+                    stderr: smoke.stderr,
+                    signal: smoke.signal,
                 }, "bwrap installed but smoke test failed -- exec sandbox is non-functional on this kernel");
             }
             return bwrap;

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

@@ -17,6 +17,8 @@ export { createExecTool } from "./builtin/exec-tool.js";
 export { createProcessTool } from "./builtin/process-tool.js";
 export { createProcessRegistry } from "./builtin/process-registry.js";
 export type { ProcessRegistry } from "./builtin/process-registry.js";
+export type { InstallDetourDecision, DetourOverlap } from "./builtin/install-detour.js";
+export { parseInstallDetour } from "./builtin/install-detour.js";
 export type { SandboxProvider, SandboxOptions, ExecSandboxConfig } from "./builtin/sandbox/types.js";
 export { detectSandboxProvider } from "./builtin/sandbox/detect-provider.js";
 export type { DetectLogger } from "./builtin/sandbox/detect-provider.js";
@@ -44,7 +46,8 @@ export { createLinkRunner } from "./integrations/link/link-runner.js";
 export type { LinkRunner } from "./integrations/link/link-runner.js";
 export { createMcpClientManager, qualifyToolName, parseQualifiedName } from "./integrations/mcp-client.js";
 export type { McpClientManager, McpClientManagerDeps, McpServerConfig, McpConnection, McpConnectionStatus, McpToolDefinition, McpToolCallResult, McpToolCallContent, } from "./integrations/mcp-client.js";
-export { mcpToolsToAgentTools, jsonSchemaToTypeBox, sanitizeMcpToolName, extractMcpServerName, classifyMcpErrorType } from "./bridge/mcp-tool-bridge.js";
+export { mcpToolsToAgentTools, jsonSchemaToTypeBox, sanitizeMcpToolName, classifyMcpErrorType } from "./bridge/mcp-tool-bridge.js";
+export { extractMcpServerName } from "@comis/shared";
 export { createVisionProviderRegistry, selectVisionProvider } from "./integrations/vision/vision-provider-registry.js";
 export { resolveVisionScope } from "./integrations/vision/scope-resolver.js";
 export { detectFfmpeg, createAudioConverter, createMediaTempManager, createMediaSemaphore, createSsrfGuardedFetcher, createCompositeResolver, createMediaPersistenceService, } from "./media/index.js";

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

@@ -22,6 +22,7 @@ export { createApplyPatchTool } from "./builtin/file/apply-patch-tool.js";
 export { createExecTool } from "./builtin/exec-tool.js";
 export { createProcessTool } from "./builtin/process-tool.js";
 export { createProcessRegistry } from "./builtin/process-registry.js";
+export { parseInstallDetour } from "./builtin/install-detour.js";
 // Built-in tools -- Exec sandbox detection
 export { detectSandboxProvider } from "./builtin/sandbox/detect-provider.js";
 // Registry
@@ -89,7 +90,8 @@ export { createLinkRunner } from "./integrations/link/link-runner.js";
 // Integrations -- MCP client manager
 export { createMcpClientManager, qualifyToolName, parseQualifiedName } from "./integrations/mcp-client.js";
 // Bridge -- MCP tool bridge
-export { mcpToolsToAgentTools, jsonSchemaToTypeBox, sanitizeMcpToolName, extractMcpServerName, classifyMcpErrorType } from "./bridge/mcp-tool-bridge.js";
+export { mcpToolsToAgentTools, jsonSchemaToTypeBox, sanitizeMcpToolName, classifyMcpErrorType } from "./bridge/mcp-tool-bridge.js";
+export { extractMcpServerName } from "@comis/shared";
 // Integrations -- Vision
 export { createVisionProviderRegistry, selectVisionProvider } from "./integrations/vision/vision-provider-registry.js";
 export { resolveVisionScope } from "./integrations/vision/scope-resolver.js";

package/node_modules/@comis/skills/dist/manifest/capability-parser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Defensive parser for `comis.capability` skill manifest blocks.
+ *
+ * The outer `ComisNamespaceSchema` is z.strictObject -- a typo'd nested
+ * capability key (`replacePackages` missing `s`) would normally cause the
+ * whole `comis:` block to fail parse and the skill to become invisible.
+ * This function parses the capability sub-block separately with try/recover
+ * semantics: on any validation failure (typo, type mismatch, empty string),
+ * log a Pino WARN with `errorKind: "config"` and return undefined. The skill
+ * renders under the fallback `prompt-skills` cluster.
+ *
+ * Capability metadata is enrichment, not a gate. The skill itself is NEVER
+ * hidden solely because optional capability metadata is invalid.
+ *
+ * Caller pattern:
+ *   const ns = (typeof obj["comis"] === "object" && ...) ? ... : undefined;
+ *   const capability = parseComisCapabilityDefensively(ns?.["capability"], skillName, logger);
+ *   // ... include `capability` in SkillMetadata; downstream filters tolerate undefined.
+ *
+ * @module
+ */
+import type { ToolCapabilityMetadata } from "@comis/core";
+export type { ToolCapabilityMetadata };
+/** Pino-compatible logger interface. The skills package already uses this shape; reuse here. */
+interface DiscoveryLogger {
+    warn(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Defensively parse a `comis.capability` block.
+ *
+ * On success: returns the parsed shape (with defaults applied).
+ * On failure: logs a Pino WARN with `errorKind: "config"`, the skillName,
+ * the Zod issue paths, and an operator-actionable hint, then returns
+ * undefined. NEVER throws.
+ *
+ * @param raw - The raw `capability` value from `manifest.comis.capability`
+ *              (may be undefined or null).
+ * @param skillName - Used in the WARN log payload for operator context.
+ * @param logger - Optional Pino logger. When omitted, parse failures fall
+ *                 through silently (the function still returns undefined;
+ *                 the caller may emit its own log).
+ * @returns Parsed capability metadata, or undefined if absent / malformed.
+ */
+export declare function parseComisCapabilityDefensively(raw: unknown, skillName: string, logger: DiscoveryLogger | undefined): ToolCapabilityMetadata | undefined;

package/node_modules/@comis/skills/dist/manifest/capability-parser.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Defensive parser for `comis.capability` skill manifest blocks.
+ *
+ * The outer `ComisNamespaceSchema` is z.strictObject -- a typo'd nested
+ * capability key (`replacePackages` missing `s`) would normally cause the
+ * whole `comis:` block to fail parse and the skill to become invisible.
+ * This function parses the capability sub-block separately with try/recover
+ * semantics: on any validation failure (typo, type mismatch, empty string),
+ * log a Pino WARN with `errorKind: "config"` and return undefined. The skill
+ * renders under the fallback `prompt-skills` cluster.
+ *
+ * Capability metadata is enrichment, not a gate. The skill itself is NEVER
+ * hidden solely because optional capability metadata is invalid.
+ *
+ * Caller pattern:
+ *   const ns = (typeof obj["comis"] === "object" && ...) ? ... : undefined;
+ *   const capability = parseComisCapabilityDefensively(ns?.["capability"], skillName, logger);
+ *   // ... include `capability` in SkillMetadata; downstream filters tolerate undefined.
+ *
+ * @module
+ */
+import { ComisCapabilityBlockSchema } from "./schema.js";
+/**
+ * Defensively parse a `comis.capability` block.
+ *
+ * On success: returns the parsed shape (with defaults applied).
+ * On failure: logs a Pino WARN with `errorKind: "config"`, the skillName,
+ * the Zod issue paths, and an operator-actionable hint, then returns
+ * undefined. NEVER throws.
+ *
+ * @param raw - The raw `capability` value from `manifest.comis.capability`
+ *              (may be undefined or null).
+ * @param skillName - Used in the WARN log payload for operator context.
+ * @param logger - Optional Pino logger. When omitted, parse failures fall
+ *                 through silently (the function still returns undefined;
+ *                 the caller may emit its own log).
+ * @returns Parsed capability metadata, or undefined if absent / malformed.
+ */
+export function parseComisCapabilityDefensively(raw, skillName, logger) {
+    // Fast path: no capability block declared -> no log, no work.
+    if (raw === undefined)
+        return undefined;
+    const result = ComisCapabilityBlockSchema.safeParse(raw);
+    if (result.success) {
+        // Coerce the Zod-inferred shape into ToolCapabilityMetadata
+        // (compatible by structure).
+        return {
+            cluster: result.data.cluster,
+            summary: result.data.summary,
+            replacesPackages: result.data.replacesPackages,
+        };
+    }
+    // Malformed -- log WARN and fall back. This path NEVER raises an exception.
+    const issues = result.error.issues.map((issue) => ({
+        path: issue.path.join("."),
+        code: issue.code,
+        message: issue.message,
+    }));
+    logger?.warn({
+        errorKind: "config",
+        skillName,
+        issues,
+        hint: "Fix the comis.capability block in the skill manifest, or remove it. " +
+            "The skill will render under the fallback 'prompt-skills' cluster until corrected.",
+    }, "Malformed comis.capability metadata; skill renders under fallback cluster.");
+    return undefined;
+}

package/node_modules/@comis/skills/dist/manifest/schema.d.ts

@@ -10,13 +10,9 @@ export declare const SkillNameSchema: z.ZodString;
  * All fields default to empty arrays (no permissions).
  */
 export declare const SkillPermissionsSchema: z.ZodObject<{
-    /** Filesystem read access paths (e.g. ["/tmp/skill-data"]) */
     fsRead: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    /** Filesystem write access paths */
     fsWrite: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    /** Network access domains (e.g. ["api.example.com"]) */
     net: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    /** Environment variable access (read-only, specific keys) */
     env: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 /**
@@ -24,7 +20,7 @@ export declare const SkillPermissionsSchema: z.ZodObject<{
  * Accepts a single string (wraps in array, lowercases) or an array of strings (lowercases each).
  * No enum restriction -- any OS string is valid (e.g., "playstation").
  */
-export declare const OsFieldSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodArray<z.ZodString>>>;
+export declare const OsFieldSchema: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
 /**
  * Skill prerequisites schema (strict: only bins and env keys accepted).
  * Undefined means no prerequisites; present means the skill declares external dependencies.
@@ -37,7 +33,35 @@ export declare const SkillRequiresSchema: z.ZodObject<{
  * Skill key schema with preprocess coercion to slug format.
  * Lowercases, replaces spaces with hyphens, strips non-alphanumeric-hyphen chars.
  */
-export declare const SkillKeySchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodString>>;
+export declare const SkillKeySchema: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+/**
+ * Capability metadata block for v1.1 capability layer.
+ *
+ * Optional sub-block of `comis:` namespace. All inner fields optional. The
+ * block is z.strictObject -- unknown nested keys (typos like
+ * `replacePackages` missing `s`) are rejected when used in a strict-parse
+ * context.
+ *
+ * IMPORTANT -- defensive parse at registry-side:
+ * The outer ComisNamespaceSchema is strict, so a malformed `capability` block
+ * would normally cause the whole `comis:` block to fail parse and the skill
+ * to become invisible. The registry's discovery enrichment extracts
+ * `comis.capability` SEPARATELY via `parseComisCapabilityDefensively`, which
+ * logs a WARN and returns undefined on failure -- letting the skill render
+ * under the fallback `prompt-skills` cluster. The strict schema here is the
+ * declaration of the contract; the defensive parser is the recovery
+ * mechanism.
+ *
+ * The skill itself is never hidden solely because optional capability
+ * metadata is invalid.
+ */
+export declare const ComisCapabilityBlockSchema: z.ZodObject<{
+    cluster: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    replacesPackages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** Parsed `comis.capability` block (Zod-inferred, defaults applied). */
+export type ComisCapabilityBlockParsed = z.infer<typeof ComisCapabilityBlockSchema>;
 /**
  * Comis-specific namespace schema for fields that only apply within the
  * Comis platform. Other pi-coding-agent hosts will simply ignore this block.
@@ -45,19 +69,19 @@ export declare const SkillKeySchema: z.ZodPipe<z.ZodTransform<unknown, unknown>,
  * Skills place these fields under `comis:` in frontmatter.
  */
 export declare const ComisNamespaceSchema: z.ZodOptional<z.ZodObject<{
-    /** Target operating systems (coerced: string -> [string], lowercased) */
-    os: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodArray<z.ZodString>>>;
-    /** External prerequisites: binary executables and environment variables */
+    os: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     requires: z.ZodOptional<z.ZodObject<{
         bins: z.ZodDefault<z.ZodArray<z.ZodString>>;
         env: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
-    /** Explicit skill key override (coerced to slug format) */
-    "skill-key": z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodString>>;
-    /** Display/grouping hint for primary environment (e.g., "discord", "telegram") */
+    "skill-key": z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
     "primary-env": z.ZodOptional<z.ZodString>;
-    /** Metadata-only dispatch tag for command routing */
     "command-dispatch": z.ZodOptional<z.ZodString>;
+    capability: z.ZodOptional<z.ZodObject<{
+        cluster: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        replacesPackages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>>;
 /** Parsed Comis namespace block type. */
 export type ComisNamespaceParsed = z.infer<typeof ComisNamespaceSchema>;
@@ -69,54 +93,37 @@ export type ComisNamespaceParsed = z.infer<typeof ComisNamespaceSchema>;
  * exclusively under the `comis:` namespace block.
  */
 export declare const SkillManifestSchema: z.ZodObject<{
-    /** Unique skill name (lowercase alphanumeric with hyphens) */
     name: z.ZodString;
-    /** Human-readable description (1-1024 chars) */
     description: z.ZodString;
-    /** Skill type: always "prompt" for Markdown instruction skills. */
     type: z.ZodDefault<z.ZodLiteral<"prompt">>;
-    /** Semver version string */
     version: z.ZodOptional<z.ZodString>;
-    /** SPDX license identifier */
     license: z.ZodOptional<z.ZodString>;
-    /** Whether users can invoke this skill via /skill:name (default true) */
     userInvocable: z.ZodDefault<z.ZodBoolean>;
-    /** When true, skill is hidden from model's available skills listing (default false) */
     disableModelInvocation: z.ZodDefault<z.ZodBoolean>;
-    /** Tool restrictions when skill is active; empty array means no restriction (default []) */
     allowedTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    /** Optional hint text shown to users (e.g., "[name]") */
     argumentHint: z.ZodOptional<z.ZodString>;
-    /** Required permissions */
     permissions: z.ZodDefault<z.ZodObject<{
-        /** Filesystem read access paths (e.g. ["/tmp/skill-data"]) */
         fsRead: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        /** Filesystem write access paths */
         fsWrite: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        /** Network access domains (e.g. ["api.example.com"]) */
         net: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        /** Environment variable access (read-only, specific keys) */
         env: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
-    /** JSON Schema describing the skill's input parameters */
     inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    /** Arbitrary key-value metadata */
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    /** Comis-specific namespace block for platform-only fields */
     comis: z.ZodOptional<z.ZodObject<{
-        /** Target operating systems (coerced: string -> [string], lowercased) */
-        os: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodArray<z.ZodString>>>;
-        /** External prerequisites: binary executables and environment variables */
+        os: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>>;
         requires: z.ZodOptional<z.ZodObject<{
             bins: z.ZodDefault<z.ZodArray<z.ZodString>>;
             env: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
-        /** Explicit skill key override (coerced to slug format) */
-        "skill-key": z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodString>>;
-        /** Display/grouping hint for primary environment (e.g., "discord", "telegram") */
+        "skill-key": z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
         "primary-env": z.ZodOptional<z.ZodString>;
-        /** Metadata-only dispatch tag for command routing */
         "command-dispatch": z.ZodOptional<z.ZodString>;
+        capability: z.ZodOptional<z.ZodObject<{
+            cluster: z.ZodOptional<z.ZodString>;
+            summary: z.ZodOptional<z.ZodString>;
+            replacesPackages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** Parsed and validated skill manifest. */

package/node_modules/@comis/skills/dist/manifest/schema.js

@@ -58,6 +58,35 @@ export const SkillKeySchema = z.preprocess((val) => {
     }
     return val;
 }, z.string().regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "skill-key must be a valid slug").optional());
+/**
+ * Capability metadata block for v1.1 capability layer.
+ *
+ * Optional sub-block of `comis:` namespace. All inner fields optional. The
+ * block is z.strictObject -- unknown nested keys (typos like
+ * `replacePackages` missing `s`) are rejected when used in a strict-parse
+ * context.
+ *
+ * IMPORTANT -- defensive parse at registry-side:
+ * The outer ComisNamespaceSchema is strict, so a malformed `capability` block
+ * would normally cause the whole `comis:` block to fail parse and the skill
+ * to become invisible. The registry's discovery enrichment extracts
+ * `comis.capability` SEPARATELY via `parseComisCapabilityDefensively`, which
+ * logs a WARN and returns undefined on failure -- letting the skill render
+ * under the fallback `prompt-skills` cluster. The strict schema here is the
+ * declaration of the contract; the defensive parser is the recovery
+ * mechanism.
+ *
+ * The skill itself is never hidden solely because optional capability
+ * metadata is invalid.
+ */
+export const ComisCapabilityBlockSchema = z.strictObject({
+    /** Cluster ID this skill belongs to (operator may override via tooling.skills.capabilityHints). */
+    cluster: z.string().min(1).optional(),
+    /** Operator-tunable display summary; falls back to skill description if absent. */
+    summary: z.string().min(1).optional(),
+    /** Package names this skill replaces (for install-detour overlap detection). */
+    replacesPackages: z.array(z.string().min(1)).default([]),
+});
 /**
  * Comis-specific namespace schema for fields that only apply within the
  * Comis platform. Other pi-coding-agent hosts will simply ignore this block.
@@ -75,6 +104,12 @@ export const ComisNamespaceSchema = z.strictObject({
     "primary-env": z.string().optional(),
     /** Metadata-only dispatch tag for command routing */
     "command-dispatch": z.string().optional(),
+    /**
+     * v1.1 capability layer -- optional metadata for cluster, summary,
+     * package aliases. Defensively parsed at registry-side; a typo here will
+     * NOT hide the skill.
+     */
+    capability: ComisCapabilityBlockSchema.optional(),
 }).optional();
 /**
  * Full SKILL.md manifest schema.

package/node_modules/@comis/skills/dist/media/ssrf-fetcher.d.ts

@@ -9,6 +9,13 @@
  * URL** (preserving TLS SNI). This maintains SSRF protection while keeping
  * TLS certificate validation working correctly.
  *
+ * Both `fetch` and `Agent` are imported from undici directly (NOT
+ * `globalThis.fetch`): Node's bundled fetch ships an older undici whose
+ * request-handler lifecycle is incompatible with the v8 `Agent` we use for
+ * DNS pinning. Mixing the two throws `InvalidArgumentError: invalid
+ * onRequestStart method` and breaks every channel's inbound media path. Do
+ * not swap this back to `globalThis.fetch`.
+ *
  * Every outbound media fetch MUST go through this utility.
  *
  * @module

package/node_modules/@comis/skills/dist/media/ssrf-fetcher.js

@@ -10,13 +10,20 @@
  * URL** (preserving TLS SNI). This maintains SSRF protection while keeping
  * TLS certificate validation working correctly.
  *
+ * Both `fetch` and `Agent` are imported from undici directly (NOT
+ * `globalThis.fetch`): Node's bundled fetch ships an older undici whose
+ * request-handler lifecycle is incompatible with the v8 `Agent` we use for
+ * DNS pinning. Mixing the two throws `InvalidArgumentError: invalid
+ * onRequestStart method` and breaks every channel's inbound media path. Do
+ * not swap this back to `globalThis.fetch`.
+ *
  * Every outbound media fetch MUST go through this utility.
  *
  * @module
  */
 import { validateUrl } from "@comis/core";
 import { fromPromise, suppressError } from "@comis/shared";
-import { Agent } from "undici";
+import { Agent, fetch } from "undici";
 /**
  * Classify a fetch error into an actionable errorKind + hint for structured logging.
  */
@@ -121,7 +128,7 @@ export function createSsrfGuardedFetcher(config, logger) {
                 //    because the original hostname stays in the URL.
                 const agent = createPinnedAgent(ip);
                 try {
-                    const response = await globalThis.fetch(url, {
+                    const response = await fetch(url, {
                         signal: AbortSignal.timeout(30_000),
                         redirect: "error", // Do not follow redirects — they could point to internal IPs
                         dispatcher: agent,

package/node_modules/@comis/skills/dist/registry/discovery.d.ts

@@ -17,6 +17,7 @@
  *
  * @module
  */
+import type { ToolCapabilityMetadata } from "@comis/core";
 import type { ResourceDiagnostic } from "./diagnostics.js";
 /** Minimal pino-compatible logger for discovery warnings. */
 export interface DiscoveryLogger {
@@ -63,6 +64,13 @@ export interface SkillMetadata {
     readonly primaryEnv?: string;
     /** Dispatch mode tag (metadata-only in this phase). */
     readonly commandDispatch?: string;
+    /**
+     * Capability layer -- extracted from `comis.capability` via defensive
+     * parse. Malformed metadata -> undefined + WARN log. The skill still
+     * renders under the fallback `prompt-skills` cluster when this is
+     * undefined; metadata absence never hides the skill.
+     */
+    readonly capability?: ToolCapabilityMetadata;
 }
 /** Result of skill discovery: skills found plus any diagnostics (collisions, warnings). */
 export interface DiscoveryResult {

package/node_modules/@comis/skills/dist/registry/discovery.js

@@ -22,6 +22,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import ignore from "ignore";
 import { parseFrontmatter } from "../manifest/parser.js";
+import { parseComisCapabilityDefensively } from "../manifest/capability-parser.js";
 // ---------------------------------------------------------------------------
 // Ignore helpers
 // ---------------------------------------------------------------------------
@@ -108,7 +109,7 @@ function resolveSource(pathIndex, totalPaths) {
  * Only parses the frontmatter block -- does not validate the full manifest schema.
  * This keeps discovery fast and lightweight (Level 1 progressive disclosure).
  */
-function extractMetadataFromSkillMd(skillMdPath) {
+function extractMetadataFromSkillMd(skillMdPath, logger) {
     let content;
     try {
         content = fs.readFileSync(skillMdPath, "utf-8");
@@ -163,7 +164,12 @@ function extractMetadataFromSkillMd(skillMdPath) {
     // command-dispatch field
     const rawCommandDispatch = ns?.["command-dispatch"];
     const commandDispatch = typeof rawCommandDispatch === "string" ? rawCommandDispatch : undefined;
-    return { name: obj["name"], description: obj["description"], type, userInvocable, disableModelInvocation, argumentHint, os, requires, skillKey, primaryEnv, commandDispatch };
+    // Capability layer -- defensive parse. A typo or type mismatch in
+    // `comis.capability` returns undefined + emits a WARN; the skill itself
+    // remains visible (renders under the fallback "prompt-skills" cluster
+    // downstream).
+    const capability = parseComisCapabilityDefensively(ns?.["capability"], obj["name"], logger);
+    return { name: obj["name"], description: obj["description"], type, userInvocable, disableModelInvocation, argumentHint, os, requires, skillKey, primaryEnv, commandDispatch, capability };
 }
 /**
  * Recursive internal helper for discovering skills within a directory tree.
@@ -237,7 +243,7 @@ function discoverSkillsFromDir(dir, source, includeRootFiles, skillMap, diagnost
         // Silent skip if same real file already loaded (same file via different symlink)
         if (realPathSet.has(realPath))
             continue;
-        const metadata = extractMetadataFromSkillMd(fullPath);
+        const metadata = extractMetadataFromSkillMd(fullPath, logger);
         if (metadata === null) {
             logger?.warn({ skillPath: fullPath, hint: "Check skill file has valid YAML frontmatter with name and description fields", errorKind: "validation" }, "Skipping malformed skill file");
             continue;
@@ -278,6 +284,7 @@ function discoverSkillsFromDir(dir, source, includeRootFiles, skillMap, diagnost
                 skillKey: metadata.skillKey,
                 primaryEnv: metadata.primaryEnv,
                 commandDispatch: metadata.commandDispatch,
+                capability: metadata.capability,
             };
             skillMap.set(metadata.name, skillMeta);
             realPathSet.add(realPath);

package/node_modules/@comis/skills/dist/registry/skill-registry.d.ts

@@ -10,12 +10,25 @@
  *
  * @module
  */
-import type { SkillsConfig, TypedEventBus } from "@comis/core";
+import type { PromptSkillCapability, SkillsConfig, TypedEventBus } from "@comis/core";
 import type { Result } from "@comis/shared";
 import { type PromptSkillDescription } from "../prompt/processor.js";
 import { type SkillMetadata, type SkillSource } from "./discovery.js";
 import { type RuntimeEligibilityContext } from "./eligibility.js";
 import { type SkillWatcherHandle } from "./skill-watcher.js";
+/**
+ * Operator hint shape consumed by `getPromptSkillCapabilities`.
+ *
+ * Mirrors the return shape of `ToolCapabilityPort.getSkillHint` in
+ * `@comis/core/ports/tool-capability.ts`. The registry stays decoupled from
+ * the port itself -- daemon-side wiring passes the port's `getSkillHint`
+ * method as the callback.
+ */
+type OperatorSkillHint = {
+    readonly cluster: string;
+    readonly description?: string;
+    readonly replacesPackages: readonly string[];
+};
 /** Minimal pino-compatible logger interface for skills subsystem logging. */
 interface SkillsLogger {
     info(obj: Record<string, unknown>, msg: string): void;
@@ -101,6 +114,37 @@ export interface SkillRegistry {
      * Acts as the Comis eligibility gate for SDK discovery.
      */
     getEligibleSkillNames(): Set<string>;
+    /**
+     * Return all visible eligible prompt skills with merged capability metadata.
+     *
+     * Applies the same `allowedSkills`/`deniedSkills` and runtime-eligibility
+     * filters as `getPromptSkillDescriptions`, PLUS an extra
+     * `disableModelInvocation !== true` filter -- skills hidden from the model
+     * are not surfaced as capability index entries.
+     *
+     * Capability merge precedence:
+     *   1. operator hint by `skillKey` (when the skill declares one)
+     *   2. operator hint by skill name (always available as fallback)
+     *   3. `comis.capability` from the skill manifest (already in
+     *      `metadata.capability`)
+     *   4. Fallback: `cluster` undefined (renderer falls back to the literal
+     *      `"prompt-skills"` cluster); `summary` = `description`;
+     *      `replacesPackages` = `[]`.
+     *
+     * The `getOperatorHint` callback keeps the registry decoupled from
+     * `ToolCapabilityPort` -- daemon-side adapters pass the port's
+     * `getSkillHint` method here.
+     *
+     * Fresh-per-call (no memoization). Returns a frozen array of frozen entries.
+     *
+     * IMPORTANT -- cache fence:
+     * This method MUST NOT be consumed by `assembleRichSystemPrompt`'s
+     * `assemblerParams` in `packages/agent/src/executor/prompt-assembly.ts`.
+     * If a skill discovery sweep runs between turns, the cached system-prompt
+     * prefix MUST stay byte-identical. An architecture-grep test enforces this
+     * invariant.
+     */
+    getPromptSkillCapabilities(getOperatorHint: (skillName: string, skillKey?: string) => OperatorSkillHint | undefined): readonly PromptSkillCapability[];
     /**
      * Populate the registry from SDK-discovered skills instead of filesystem discovery.
      * Clears existing metadata, maps SDK Skill fields to Comis SkillMetadata,