@comma-agents/core 2.0.0-rc.0

package/dist/model/providers/providers.types.d.ts

@@ -0,0 +1,157 @@
+import type { Credential } from "../../credentials/credentials.types";
+import type { ProviderFactory } from "../model.types";
+/**
+ * Provenance of a resolved model list.
+ *
+ * - `"catalog"` — models.dev baseline (bundled snapshot or refreshed copy).
+ * - `"live"` — returned only from a provider's listModels callback (no catalog overlap).
+ * - `"merged"` — catalog baseline overlaid with live results.
+ * - `"error"` — live discovery failed; falling back to catalog or empty.
+ */
+export type ModelsSource = "catalog" | "live" | "merged" | "error";
+/** Supported input/output modality identifiers used by the catalog. */
+export type Modality = "text" | "image" | "audio" | "video" | "pdf";
+/** Release/availability status of a model, when known. */
+export type ModelStatus = "alpha" | "beta" | "deprecated";
+/** Coarse-grained capability flags derived from the catalog or live responses. */
+export interface ModelCapabilities {
+    /** Supports tool/function calling. */
+    readonly tools?: boolean;
+    /** Supports reasoning / chain-of-thought. */
+    readonly reasoning?: boolean;
+    /** Accepts image inputs. */
+    readonly vision?: boolean;
+    /** Accepts file attachments (images, PDFs, audio). */
+    readonly attachment?: boolean;
+    /** Supports a dedicated structured-output feature. */
+    readonly structuredOutput?: boolean;
+}
+/**
+ * Expected credential type for a provider.
+ *
+ * - `"api"` — simple API key (OpenAI, Anthropic, etc.)
+ * - `"oauth"` — OAuth 2.0 flow (GitHub Copilot)
+ * - `"custom"` — provider-specific opaque data
+ * - `"none"` — local runtime with no credential needed (Ollama)
+ */
+export type CredentialType = "api" | "oauth" | "custom" | "none";
+/** Per-million-token prices in USD. */
+export interface ModelCost {
+    /** Cost per 1M input tokens. */
+    readonly input?: number;
+    /** Cost per 1M output tokens. */
+    readonly output?: number;
+    /** Cost per 1M reasoning tokens. */
+    readonly reasoning?: number;
+    /** Cost per 1M cache-read tokens. */
+    readonly cacheRead?: number;
+    /** Cost per 1M cache-write tokens. */
+    readonly cacheWrite?: number;
+}
+/** Supported modalities. */
+export interface ModelModalities {
+    readonly input?: readonly Modality[];
+    readonly output?: readonly Modality[];
+}
+/**
+ * Normalized metadata for a single model. Populated from the catalog,
+ * a provider's live response, or a merge of the two.
+ */
+export interface ModelInfo {
+    /** Model identifier as used in model strings (e.g., `"gpt-4o"`). */
+    readonly id: string;
+    /** Human-friendly display name. */
+    readonly name?: string;
+    /** Grouping label (e.g., `"claude-sonnet"`, `"gpt"`). */
+    readonly family?: string;
+    /** Maximum total context window in tokens. */
+    readonly contextWindow?: number;
+    /** Maximum input tokens allowed in a single request. */
+    readonly maxInputTokens?: number;
+    /** Maximum output tokens per response. */
+    readonly maxOutputTokens?: number;
+    /** Training knowledge cutoff, `YYYY-MM` or `YYYY-MM-DD`. */
+    readonly knowledgeCutoff?: string;
+    /** First public release date. */
+    readonly releaseDate?: string;
+    /** Last metadata update date. */
+    readonly lastUpdated?: string;
+    /** Release status (alpha/beta/deprecated). */
+    readonly status?: ModelStatus;
+    /** Supported input/output modalities. */
+    readonly modalities?: ModelModalities;
+    /** Capability flags. */
+    readonly capabilities?: ModelCapabilities;
+    /** Pricing information. */
+    readonly cost?: ModelCost;
+}
+/** Arguments provided to a provider's live `listModels` callback. */
+export interface ListModelsContext {
+    /** Resolved credential for the provider, if any. */
+    readonly credential?: Credential;
+    /** Provider-specific base URL override (e.g., Ollama host, Copilot enterprise domain). */
+    readonly baseURL?: string;
+    /** Optional abort signal; callers typically attach a timeout. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Live model-listing callback supplied by a provider definition.
+ *
+ * Implementations should return the raw list from the provider's API.
+ * Merge with the catalog baseline is handled by the registry, not here.
+ */
+export type ListModelsFn = (context: ListModelsContext) => Promise<readonly ModelInfo[]>;
+/**
+ * Full result of resolving the model list for a single provider.
+ *
+ * Returned by `listProviderModels()` to consumers (the daemon, tests).
+ * `source` describes where the models came from; `error` is populated
+ * when live discovery failed and we fell back to catalog or empty.
+ */
+export interface ListModelsResult {
+    readonly models: readonly ModelInfo[];
+    readonly source: ModelsSource;
+    /** ISO timestamp when live data was fetched, if any. */
+    readonly fetchedAt?: string;
+    /** Error message when `source === "error"` or live fetch partially failed. */
+    readonly error?: string;
+}
+/**
+ * Everything the runtime knows about a provider: metadata from the
+ * catalog plus optional runtime resolution/listing callbacks.
+ */
+export interface ProviderDefinition {
+    /** Canonical provider id (matches models.dev keys, e.g., `"github-copilot"`). */
+    readonly id: string;
+    /** Human-friendly display name. */
+    readonly name: string;
+    /**
+     * Expected credential type for this provider.
+     * Defaults to `"api"` for catalog-derived providers when not explicitly set.
+     */
+    readonly credentialType?: CredentialType;
+    /**
+     * Live model-listing callback. When present, `listProviderModels()` will
+     * call it and merge the response with the catalog.
+     */
+    readonly listModels?: ListModelsFn;
+    /**
+     * Direct factory for the provider's `LanguageModel` instances. When set,
+     * takes precedence over `packageName`/`factoryName`.
+     */
+    readonly factory?: ProviderFactory;
+    /**
+     * npm package name used by the resolver to dynamically import the AI SDK
+     * integration. Defaults to `@ai-sdk/<id>` when omitted.
+     */
+    readonly packageName?: string;
+    /**
+     * Export name on the imported module. Defaults to `create<ProviderId>`.
+     */
+    readonly factoryName?: string;
+    /**
+     * `true` when the definition was added via `registerProvider()` rather
+     * than derived from the bundled catalog. Set automatically by the registry.
+     */
+    readonly isCustom?: boolean;
+}

package/dist/model/providers/providers.utils.d.ts

@@ -0,0 +1,16 @@
+import type { ModelInfo } from "./providers.types";
+/**
+ * Merge a catalog baseline with a provider's live model list.
+ *
+ * Strategy (follows opencode's layering approach):
+ * - Only models present in the live list survive (live is authoritative for membership).
+ * - Each surviving model starts from the catalog entry (rich metadata) and is
+ *   overlaid with the live entry's fields — live wins for runtime-relevant
+ *   capabilities and limits, catalog fills in missing cost / release dates / names.
+ * - Models present live but not in the catalog are included as-is.
+ */
+export declare function mergeCatalogWithLive(catalogModels: readonly ModelInfo[], liveModels: readonly ModelInfo[]): readonly ModelInfo[];
+/** Merge two `ModelInfo` entries, preferring `overlay` fields when present. */
+export declare function mergeModelInfo(base: ModelInfo, overlay: ModelInfo): ModelInfo;
+/** Sort models by id for stable output. */
+export declare function sortModels(models: readonly ModelInfo[]): readonly ModelInfo[];

package/dist/prompts/index.d.ts

@@ -0,0 +1,4 @@
+export type { BuildMessagesOptions, SystemPromptOptions, } from "./message-builder";
+export { buildMessages, resolveSystemPrompt } from "./message-builder";
+export type { PromptTemplate, PromptTemplateConfig, TemplateValue, TemplateVariables, } from "./prompts.types";
+export { createPromptTemplate } from "./template/prompt-template";

package/dist/prompts/message-builder.d.ts

@@ -0,0 +1,89 @@
+import type { ModelMessage } from "ai";
+import type { ConversationContext } from "../conversation-context";
+import type { PromptTemplate } from "./prompts.types";
+/**
+ * Options for building a message array.
+ */
+export interface BuildMessagesOptions {
+    /** The current user message to append. */
+    readonly message: string;
+    /**
+     * Conversation context to prepend.
+     * If not provided, only the current message is included.
+     */
+    readonly context?: ConversationContext;
+    /**
+     * Additional context messages to prepend before conversation context.
+     * Useful for injecting few-shot examples or other context.
+     */
+    readonly prefix?: readonly ModelMessage[];
+}
+/**
+ * Options for resolving a system prompt, supporting both static strings
+ * and dynamic prompt templates.
+ */
+export interface SystemPromptOptions {
+    /**
+     * System prompt — a static string or a `PromptTemplate` for dynamic interpolation.
+     * When a `PromptTemplate` is provided, it is rendered with its baked-in variables.
+     */
+    readonly systemPrompt?: string | PromptTemplate;
+}
+/**
+ * Build a message array for the Vercel AI SDK.
+ *
+ * Composes messages in this order:
+ * 1. `prefix` messages (e.g., few-shot examples)
+ * 2. Conversation context (from `ConversationContext`)
+ * 3. Current user message
+ *
+ * Returns native AI SDK `ModelMessage[]` that can be passed directly to
+ * `generateText()` / `streamText()`. Preserves tool calls, tool results,
+ * reasoning, and multi-modal content from the conversation context.
+ *
+ * Note: The system prompt is NOT included in the message array — it should
+ * be passed via the `system` parameter of `generateText`/`streamText`.
+ *
+ * @example
+ * ```ts
+ * const messages = buildMessages({
+ *   message: "How do I use generics?",
+ *   context,
+ *   prefix: [
+ *     { role: "user", content: "What is TypeScript?" },
+ *     { role: "assistant", content: "TypeScript is a typed superset of JavaScript." },
+ *   ],
+ * });
+ *
+ * const result = await generateText({
+ *   model: openai("gpt-4o"),
+ *   system: "You are a helpful assistant.",
+ *   messages,
+ * });
+ * ```
+ */
+export declare function buildMessages(options: BuildMessagesOptions): readonly ModelMessage[];
+/**
+ * Resolve a system prompt from either a static string or a dynamic template.
+ *
+ * If `systemPrompt` is a `PromptTemplate`, it is rendered with its baked-in
+ * variables. If it is a plain string, it is returned as-is.
+ *
+ * @returns The resolved system prompt string, or `undefined` if none configured.
+ *
+ * @example
+ * ```ts
+ * // Static
+ * const prompt = await resolveSystemPrompt({ systemPrompt: "You are helpful." });
+ * // => "You are helpful."
+ *
+ * // Dynamic template
+ * const template = createPromptTemplate({
+ *   template: "You are {{ role }}, an expert in {{ language }}.",
+ *   variables: { role: "a reviewer", language: "TypeScript" },
+ * });
+ * const prompt = await resolveSystemPrompt({ systemPrompt: template });
+ * // => "You are a reviewer, an expert in TypeScript."
+ * ```
+ */
+export declare function resolveSystemPrompt(options: SystemPromptOptions): Promise<string | undefined>;

package/dist/prompts/prompts.types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A value that can be used to fill a prompt template variable.
+ *
+ * - Primitives (`string`, `number`, `boolean`, `null`) are passed directly to Liquid.
+ * - Arrays and objects enable `{% for %}` loops and dot-access in templates.
+ * - Functions (`() => string | Promise<string>`) are resolved to strings before
+ *   the Liquid render pass — this preserves the async-first design.
+ */
+export type TemplateValue = string | number | boolean | null | undefined | readonly TemplateValue[] | {
+    readonly [key: string]: TemplateValue;
+} | (() => string | Promise<string>);
+/**
+ * A map of variable names to their values for prompt template interpolation.
+ *
+ * Values can be primitives, arrays, objects, or async functions.
+ * Functions are resolved to strings before the Liquid render pass.
+ *
+ * @example
+ * ```ts
+ * const vars: TemplateVariables = {
+ *   role: "code reviewer",
+ *   language: "TypeScript",
+ *   tools: ["bash", "read", "write"],
+ *   style: () => loadStyleGuide(), // async function → resolved to string
+ * };
+ * ```
+ */
+export type TemplateVariables = Readonly<Record<string, TemplateValue>>;
+/**
+ * Configuration for creating a prompt template.
+ */
+export interface PromptTemplateConfig {
+    /**
+     * The template string using Liquid syntax.
+     *
+     * Supports the full LiquidJS template language:
+     * - `{{ name }}` — variable interpolation
+     * - `{{ "VAR" | env }}` — environment variable via custom filter
+     * - `{{ "/path" | file }}` — file contents (first line) via custom filter
+     * - `{{ "command" | exec }}` — shell command output via custom filter
+     * - `{% if condition %}...{% endif %}` — conditionals
+     * - `{% for item in items %}...{% endfor %}` — loops
+     * - `{{ text | upcase }}` — built-in Liquid filters
+     *
+     * @example
+     * ```ts
+     * "You are {{ role }}, an expert in {{ language }}."
+     * ```
+     */
+    readonly template: string;
+    /**
+     * Default variable values. Can be overridden at render time.
+     */
+    readonly variables?: TemplateVariables;
+}
+/**
+ * A compiled prompt template backed by LiquidJS.
+ */
+export interface PromptTemplate {
+    /** The original template string. */
+    readonly template: string;
+    /** The default variables provided at creation time. */
+    readonly defaults: TemplateVariables;
+    /**
+     * Render the prompt by resolving all variables through LiquidJS.
+     * Override variables take precedence over defaults.
+     *
+     * @throws {Error} if a required variable is missing or a filter fails
+     */
+    render(overrides?: TemplateVariables): Promise<string>;
+    /**
+     * Update the default variables used during rendering.
+     * New values overwrite matching keys; keys not in the input are left as-is.
+     *
+     * @example
+     * ```ts
+     * const tpl = createPromptTemplate({
+     *   template: "You are {{ role }}, reviewing {{ language }} code.",
+     *   variables: { role: "a reviewer" },
+     * });
+     * tpl.updatePromptVariables({ language: "TypeScript" });
+     * await tpl.render(); // "You are a reviewer, reviewing TypeScript code."
+     * ```
+     */
+    updatePromptVariables(variables: TemplateVariables): void;
+}

package/dist/prompts/template/prompt-template.d.ts

@@ -0,0 +1,22 @@
+import type { PromptTemplate, PromptTemplateConfig } from "../prompts.types";
+/**
+ * Create a prompt template backed by LiquidJS.
+ *
+ * Templates use the full Liquid syntax — `{{ variable }}` interpolation,
+ * `{% if %}` / `{% for %}` control flow, filters, and the custom
+ * `env`, `file`, `exec` filters.
+ *
+ * Function-typed variable values are resolved to strings before the
+ * Liquid render pass, so `() => string | Promise<string>` still works.
+ *
+ * @example
+ * ```ts
+ * const tpl = createPromptTemplate({
+ *   template: "You are {{ role }}, an expert in {{ language }}.",
+ *   variables: { role: "a code reviewer", language: "TypeScript" },
+ * });
+ * await tpl.render();               // "You are a code reviewer, an expert in TypeScript."
+ * await tpl.render({ language: "Rust" }); // "You are a code reviewer, an expert in Rust."
+ * ```
+ */
+export declare function createPromptTemplate(config: PromptTemplateConfig): PromptTemplate;

package/dist/sandbox/in-sandbox.d.ts

@@ -0,0 +1,31 @@
+import type { Agent } from "../agents/agent/agent.types";
+import type { GuardCallbacks } from "../guard/guard.types";
+import type { Sandbox, SandboxConfig } from "./sandbox.types";
+/**
+ * Apply sandbox enforcement to a strategy or agent.
+ *
+ * Creates a `Sandbox` from the config, which lazily creates per-tool `Guard`
+ * instances. Tools access their guard directly via `ToolContext.guard` and
+ * call `guard.authorize()` for path resolution, jail enforcement, policy
+ * evaluation, and interactive "ask" dispatch.
+ *
+ * @param boxed - The strategy or agent to sandbox.
+ * @param config - Partial sandbox configuration. Defaults are taken from
+ *   `DEFAULT_SANDBOX_CONFIG` (jailed to process.cwd(), default forbidden globs).
+ * @param callbacks - onAsk / onPolicyChange handlers shared across all guards.
+ * @returns The same entity (mutated in-place).
+ */
+export declare function inSandbox(boxed: Agent, config?: Partial<SandboxConfig>, callbacks?: GuardCallbacks): Agent;
+export declare function inSandbox(boxed: {
+    agents: Readonly<Record<string, Agent>>;
+    flow: Agent;
+}, config?: Partial<SandboxConfig>, callbacks?: GuardCallbacks): typeof boxed;
+/**
+ * Retrieve the `Sandbox` instance from a previously sandboxed entity.
+ *
+ * Returns `undefined` if `inSandbox` was never called on this entity.
+ * Useful for the daemon to access `sandbox.guardFor(tool)` for policy management.
+ */
+export declare function getSandbox(boxed: Agent | {
+    agents: Readonly<Record<string, Agent>>;
+}): Sandbox | undefined;

package/dist/sandbox/index.d.ts

@@ -0,0 +1,4 @@
+export { getSandbox, inSandbox } from "./in-sandbox";
+export { createSandbox } from "./sandbox";
+export { DEFAULT_DAEMON_SANDBOX_CONFIG, DEFAULT_FORBIDDEN_GLOBS, DEFAULT_SANDBOX_CONFIG, PERMISSIVE_SANDBOX_CONFIG, } from "./sandbox.constants";
+export type { AccessMode, AuthorizationContext, PathPolicy, PermissionDecision, PermissionOperation, PermissionRequest, PermissionRequester, PolicyPatch, Sandbox, SandboxConfig, } from "./sandbox.types";

package/dist/sandbox/sandbox.constants.d.ts

@@ -0,0 +1,31 @@
+import type { SandboxConfig } from "./sandbox.types";
+/**
+ * Cwd-relative glob patterns that are always denied for read and write
+ * unless the caller explicitly overrides `forbiddenGlobs` on `SandboxConfig`.
+ *
+ * Covers VCS metadata, dotenv files, common private keys/certs, and
+ * package-manager auth files. Patterns are evaluated by Bun.Glob.
+ */
+export declare const DEFAULT_FORBIDDEN_GLOBS: readonly string[];
+/**
+ * Permissive config — unjailed, absolute paths allowed, no forbidden globs,
+ * all reads and writes allowed.
+ *
+ * Applied as fallback in `buildAgentToolSet` when no sandbox is configured.
+ */
+export declare const PERMISSIVE_SANDBOX_CONFIG: SandboxConfig;
+/**
+ * Recommended default config — jailed to cwd, absolute paths rejected,
+ * default forbidden globs enforced, all operations allowed within the boundary.
+ * `.comma/**` and `.` are explicitly allowlisted for reading so skills and
+ * configuration are always accessible without triggering permission prompts.
+ */
+export declare const DEFAULT_SANDBOX_CONFIG: SandboxConfig;
+/**
+ * Daemon default config — jailed to cwd, absolute paths allowed (daemon
+ * passes absolute paths), in-cwd paths auto-allowed, anything outside
+ * cwd triggers "ask" via the permission bridge. `.comma/**` and `.`
+ * are explicitly allowlisted for reading so skills and configuration are
+ * always accessible without prompting.
+ */
+export declare const DEFAULT_DAEMON_SANDBOX_CONFIG: Omit<SandboxConfig, "cwd">;

package/dist/sandbox/sandbox.d.ts

@@ -0,0 +1,11 @@
+import type { GuardCallbacks } from "../guard/guard.types";
+import type { Sandbox, SandboxConfig } from "./sandbox.types";
+/**
+ * Create a Sandbox — a thin registry that lazily creates per-tool Guard
+ * instances. Each guard handles path resolution, jail enforcement, policy
+ * chain evaluation, and "ask" dispatch.
+ *
+ * @param config - Sandbox configuration. Missing fields use sensible defaults.
+ * @param callbacks - onAsk / onPolicyChange handlers shared across all guards.
+ */
+export declare function createSandbox(config?: Partial<SandboxConfig>, callbacks?: GuardCallbacks): Sandbox;

package/dist/sandbox/sandbox.types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Decision mode for a path or operation.
+ * - `"allow"` — permit immediately.
+ * - `"deny"`  — reject immediately with a SandboxViolationError.
+ * - `"ask"`   — delegate to the PermissionRequester; throws if none is configured.
+ */
+export type AccessMode = "allow" | "deny" | "ask";
+/**
+ * Policy applied to a class of file-system operations (read or write).
+ *
+ * Evaluation order: deny patterns → allow patterns → default.
+ * Patterns are Bun.Glob expressions relative to the sandbox `cwd`.
+ */
+export interface PathPolicy {
+    /** Decision when no pattern matches. */
+    readonly default: AccessMode;
+    /** Glob patterns (relative to cwd) that are explicitly allowed. */
+    readonly allow?: readonly string[];
+    /** Glob patterns (relative to cwd) that are explicitly denied. Deny wins over allow when both match. */
+    readonly deny?: readonly string[];
+}
+/**
+ * Static configuration for a Sandbox instance.
+ */
+export interface SandboxConfig {
+    /** Absolute path used as the root for relative-path resolution and jail boundary. */
+    readonly cwd: string;
+    /**
+     * When `true`, any path that resolves outside `cwd` throws a
+     * SandboxViolationError with `reason: "jail"`.
+     */
+    readonly jail: boolean;
+    /**
+     * When `false`, tools that pass an absolute path receive a
+     * SandboxViolationError with `reason: "absolute-path"`.
+     */
+    readonly allowAbsolutePaths: boolean;
+    /**
+     * Cwd-relative glob patterns that are unconditionally denied for both
+     * read and write operations. Evaluated before `read` / `write` policies;
+     * cannot be overridden by `allow` patterns or session decisions.
+     */
+    readonly forbiddenGlobs: readonly string[];
+    /** Read-access policy applied to every FS read operation. */
+    readonly read: PathPolicy;
+    /** Write-access policy applied to every FS write operation. */
+    readonly write: PathPolicy;
+    /** Metadata for trash archive identification (runId, sessionId). Injected by the daemon executor. */
+    readonly trashMetadata?: SandboxTrashMetadata;
+}
+/**
+ * File-system operation categories used in permission requests.
+ * `"fs.exec"` is reserved for future bash sandboxing.
+ */
+export type PermissionOperation = "fs.read" | "fs.write" | "fs.exec";
+/**
+ * The decision returned by a PermissionRequester.
+ * - `"allow"` / `"deny"` — one-shot for this invocation only.
+ * - `"allow-session"` / `"deny-session"` — remembered for the lifetime
+ *   of this guard's session memory (stored in-memory, not persisted to disk).
+ */
+export type PermissionDecision = "allow" | "deny" | "allow-session" | "deny-session";
+/**
+ * Data passed to a PermissionRequester when policy resolves to `"ask"`.
+ */
+export interface PermissionRequest {
+    readonly agentName: string;
+    readonly toolName?: string;
+    readonly operation: PermissionOperation;
+    readonly resource: string;
+    readonly reason: "policy-ask" | "policy-deny-override";
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Async function that presents a permission request to a human (or policy
+ * engine) and returns the decision.
+ *
+ * If the function throws or rejects, the guard treats it as `"deny"`.
+ */
+export type PermissionRequester = (request: PermissionRequest) => Promise<PermissionDecision>;
+/**
+ * A partial update to a guard's in-memory policy.
+ * Applied by the daemon's `update_policy` message.
+ */
+export interface PolicyPatch {
+    readonly mode: "read" | "write";
+    readonly allow?: readonly string[];
+    readonly deny?: readonly string[];
+    readonly default?: AccessMode;
+}
+import type { Guard, Policy } from "../guard/guard.types";
+import type { SandboxTrashMetadata } from "../tools/io/trash";
+/**
+ * Thin guard registry. Creates per-tool Guard instances lazily.
+ * Tools access their guard directly via `ToolContext.guard`.
+ */
+export interface Sandbox {
+    /** The resolved absolute working directory. */
+    readonly cwd: string;
+    /** Map of tool name → Guard (lazily populated). */
+    readonly guards: ReadonlyMap<string, Guard>;
+    /** Get or lazily create a guard for the given tool. Accepts optional tool-level policies. */
+    guardFor(toolName: string, toolPolicies?: readonly Policy[]): Guard;
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,4 @@
+export type { SkillLoadResult, SkillLoadWarning } from "./skills.loader";
+export { buildSkillsPromptHeader, loadSkills } from "./skills.loader";
+export { createSkillRegistry } from "./skills.registry";
+export type { LoadSkillsOptions, Skill, SkillMetadata, SkillRegistry, } from "./skills.types";

package/dist/skills/skills.constants.d.ts

@@ -0,0 +1,10 @@
+/** Subdirectory under the OS config root holding global skills. */
+export declare const GLOBAL_SKILLS_SUBDIR = "comma-agents/skills";
+/** Subdirectory under the project workspace holding project-local skills. */
+export declare const PROJECT_SKILLS_SUBDIR = ".comma/skills";
+/** Filename inside each skill directory. */
+export declare const SKILL_FILENAME = "SKILL.md";
+/** Maximum size of a `SKILL.md` file in bytes (256 KiB). Prevents runaway loads. */
+export declare const SKILL_MAX_BYTES: number;
+/** Regular expression that valid skill names must match (kebab-case, 1–64 chars). */
+export declare const SKILL_NAME_PATTERN: RegExp;

package/dist/skills/skills.loader.d.ts

@@ -0,0 +1,46 @@
+import type { LoadSkillsOptions, SkillRegistry } from "./skills.types";
+/**
+ * A non-fatal warning produced while scanning a skills directory. Surfaced
+ * so callers can log malformed or oversized skills without aborting the
+ * whole scan.
+ */
+export interface SkillLoadWarning {
+    readonly sourcePath: string;
+    readonly message: string;
+}
+/** Result returned by {@link loadSkills}. */
+export interface SkillLoadResult {
+    readonly registry: SkillRegistry;
+    readonly warnings: readonly SkillLoadWarning[];
+}
+/**
+ * Scan the global and project skill directories and return a populated
+ * registry. Missing directories are silently ignored (not an error —
+ * users may have neither). Project skills override global skills with
+ * the same `name`.
+ *
+ * Each direct subdirectory containing a `SKILL.md` becomes a skill;
+ * deeper nesting is ignored to keep discovery predictable. Files larger
+ * than {@link SKILL_MAX_BYTES} or with malformed frontmatter are
+ * skipped and reported as `warnings`.
+ *
+ * @param workspaceRoot - Used to resolve the default project skills directory.
+ * @param options       - Override or disable either discovery root.
+ */
+export declare function loadSkills(workspaceRoot: string, options?: LoadSkillsOptions): Promise<SkillLoadResult>;
+/**
+ * Build the system-prompt header block advertising available skills.
+ * Returns an empty string when the registry is empty so callers can
+ * concatenate unconditionally.
+ *
+ * The block format is deliberately compact — `name: description` per
+ * line — so that even dozens of skills cost little context:
+ *
+ * ```
+ * ## Available Skills
+ * Call the `load_skill` tool with one of these names to load its full instructions:
+ * - ts-patterns: TypeScript conventions for new modules.
+ * - react-practices: React component and hook patterns.
+ * ```
+ */
+export declare function buildSkillsPromptHeader(registry: SkillRegistry): string;

package/dist/skills/skills.registry.d.ts

@@ -0,0 +1,18 @@
+import type { SkillRegistry } from "./skills.types";
+/**
+ * Create an in-memory skill registry.
+ *
+ * Project skills always override global skills with the same name; the
+ * registry enforces this regardless of registration order. Calling
+ * `register` with a global skill whose name is already taken by a
+ * project skill is a no-op.
+ *
+ * @example
+ * ```ts
+ * const registry = createSkillRegistry();
+ * registry.register(projectSkill);
+ * registry.register(globalSkill); // ignored if names collide
+ * registry.get("ts-patterns");
+ * ```
+ */
+export declare function createSkillRegistry(): SkillRegistry;