comisai 1.0.36 → 1.0.37

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

@@ -14,6 +14,10 @@
  */
 import { Type } from "typebox";
 import { jsonResult, throwToolError, readEnumParam, readStringParam, readNumberParam, } from "./platform/tool-helpers.js";
+import { buildInstallDetourHint } from "./exec-tool.js";
+// `InstallDetourDecision` is imported transitively via
+// ProcessSession.installDetourDecision (process-registry.ts type-only import);
+// no direct import here — never re-derive at status-query time.
 // ---------------------------------------------------------------------------
 // Parameter schema
 // ---------------------------------------------------------------------------
@@ -30,17 +34,19 @@ const ProcessParams = Type.Object({
     offset: Type.Optional(Type.Integer({ description: "Line offset for log pagination (0-indexed)" })),
     limit: Type.Optional(Type.Integer({ description: "Max lines to return for log (default 200)" })),
 });
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
 /**
  * Create a process management tool that delegates to a ProcessRegistry.
  *
- * @param registry - ProcessRegistry for session CRUD operations
- * @param logger - Optional structured logger for DEBUG-level operation logging
- * @returns AgentTool implementing the process management interface
+ * Uses a deps-object signature; backward compat with the prior positional
+ * `(registry, logger?)` shape is NOT preserved.
+ *
+ * @param deps - Dependencies bundle. See `ProcessToolDeps` for field semantics.
+ * @returns AgentTool implementing the process management interface.
  */
-export function createProcessTool(registry, logger) {
+export function createProcessTool(deps) {
+    const { registry, logger,
+    // toolCapabilityPort is read inside execute(...) below
+     } = deps;
     return {
         name: "process",
         label: "Process",
@@ -76,6 +82,18 @@ export function createProcessTool(registry, logger) {
                         if (!details) {
                             throwToolError("not_found", `Process session not found: ${sessionId}`);
                         }
+                        // Retroactive advise-mode hint augmentation. Read the spawn-time
+                        // decision back from the session rather than re-deriving from current
+                        // connected-server state (the connected set may have drifted since
+                        // spawn, producing an inconsistent hint vs the spawn-time event).
+                        // No current-mode check — operators can switch modes mid-session via
+                        // daemon restart; advise-spawned sessions keep their hint.
+                        const session = registry.get(sessionId);
+                        if (session?.installDetourDecision &&
+                            session.installDetourDecision.overlaps.length > 0) {
+                            const hint = buildInstallDetourHint(session.installDetourDecision);
+                            return jsonResult({ ...details, installDetourHint: hint.installDetourHint });
+                        }
                         return jsonResult(details);
                     }
                     case "log": {

package/node_modules/@comis/skills/dist/builtin/sandbox/bwrap-provider.d.ts

@@ -17,7 +17,7 @@ import type { SandboxOptions, SandboxProvider } from "./types.js";
  * → /bin/true's dynamic linker unreachable → smoke EPERMs while the
  * production sandbox actually works fine).
  */
-export declare const SYSTEM_RO_PATHS: readonly ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/lib32", "/etc/resolv.conf", "/etc/hosts", "/etc/hostname", "/etc/ssl", "/etc/ca-certificates", "/etc/pki", "/etc/ld.so.cache", "/etc/ld.so.conf", "/etc/ld.so.conf.d", "/etc/alternatives", "/etc/localtime", "/etc/passwd", "/etc/group", "/etc/nsswitch.conf"];
+export declare const SYSTEM_RO_PATHS: readonly ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/lib32", "/etc/resolv.conf", "/etc/hosts", "/etc/hostname", "/etc/ssl", "/etc/ca-certificates", "/etc/pki", "/etc/ld.so.cache", "/etc/ld.so.conf", "/etc/ld.so.conf.d", "/etc/alternatives", "/etc/localtime", "/etc/passwd", "/etc/group", "/etc/nsswitch.conf", "/etc/fonts"];
 export declare class BwrapProvider implements SandboxProvider {
     readonly name = "bwrap";
     private bwrapPath;

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

@@ -42,6 +42,15 @@ export const SYSTEM_RO_PATHS = [
     "/etc/passwd",
     "/etc/group",
     "/etc/nsswitch.conf",
+    // fontconfig config (font.conf, conf.d/). Without this, libfontconfig prints
+    // "Cannot load default config file" to stderr on every text-rendering call
+    // (matplotlib, Pango, Pillow TTF, ImageMagick, headless Chromium, weasyprint,
+    // ffmpeg drawtext, LibreOffice headless) and falls back to a minimal compiled-in
+    // config — which silently breaks the substitution chain for non-Latin scripts
+    // (CJK/Arabic/devanagari render as Tofu boxes even when the fonts are present
+    // under /usr/share/fonts). Per-user cache lives in XDG_CACHE_HOME/fontconfig,
+    // which is already RW via the workspace .cache bind in wrapEnv().
+    "/etc/fonts",
 ];
 /**
  * Per-user config paths to bind read-only. Resolved against the daemon

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/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,