@comma-agents/core 2.0.0-rc.0

package/dist/skills/skills.types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Frontmatter metadata for a single skill.
+ *
+ * Skills follow the Anthropic / opencode `SKILL.md` convention: a YAML
+ * frontmatter block at the top of the file declares the skill's identity
+ * and a short description, followed by the full instructional body.
+ */
+export interface SkillMetadata {
+    /** Unique skill identifier. Must be kebab-case. */
+    readonly name: string;
+    /**
+     * Short, action-oriented description shown to the LLM in the system
+     * prompt header. Used to decide whether to call `load_skill`. Should
+     * fit on one line and answer "when should I load this?".
+     */
+    readonly description: string;
+}
+/**
+ * A fully loaded skill — metadata plus the body of its `SKILL.md`.
+ */
+export interface Skill extends SkillMetadata {
+    /** Markdown body of the skill (frontmatter stripped). */
+    readonly content: string;
+    /** Absolute path to the source `SKILL.md` file. */
+    readonly sourcePath: string;
+    /**
+     * Origin of the skill. Project skills override global skills with the
+     * same `name`.
+     */
+    readonly origin: "global" | "project";
+}
+/**
+ * In-memory skill registry. Holds resolved skills keyed by name and
+ * exposes lookup / listing for the loader, the system-prompt header
+ * builder, and the `load_skill` tool.
+ */
+export interface SkillRegistry {
+    /** Register or replace a skill. Project skills override global ones by name. */
+    register(skill: Skill): void;
+    /** Look up a skill by name. */
+    get(name: string): Skill | undefined;
+    /** All registered skills, sorted by `name`. */
+    list(): readonly Skill[];
+    /** True when no skills are registered. */
+    isEmpty(): boolean;
+}
+/**
+ * Options for {@link loadSkills}.
+ */
+export interface LoadSkillsOptions {
+    /**
+     * Absolute path to the global skills directory. Each direct subdirectory
+     * containing a `SKILL.md` becomes a skill. Defaults to
+     * `<configRoot>/comma-agents/skills/`.
+     *
+     * Set to `null` to skip global discovery.
+     */
+    readonly globalSkillsDir?: string | null;
+    /**
+     * Absolute path to the project-local skills directory. Defaults to
+     * `<cwd>/.comma/skills/`. Skills here override global ones by name.
+     *
+     * Set to `null` to skip project discovery.
+     */
+    readonly projectSkillsDir?: string | null;
+}

package/dist/skills/skills.utils.d.ts

@@ -0,0 +1,37 @@
+import type { SkillMetadata } from "./skills.types";
+/**
+ * Resolve the platform-appropriate user config root. Mirrors the logic
+ * used by the TUI's `resolveConfigRoot` so that skills authored alongside
+ * the TUI config are discovered without extra configuration.
+ *
+ * - macOS: `~/Library/Application Support`
+ * - Windows: `%APPDATA%` (falls back to `~/AppData/Roaming`)
+ * - Linux/other: `$XDG_CONFIG_HOME` or `~/.config`
+ */
+export declare function resolveUserConfigRoot(): string;
+/** Absolute path to the default global skills directory for this user. */
+export declare function resolveDefaultGlobalSkillsDir(): string;
+/** Absolute path to the default project-local skills directory for the given workspace. */
+export declare function resolveDefaultProjectSkillsDir(workspaceRoot: string): string;
+/**
+ * Parse the YAML frontmatter of a `SKILL.md` file and return the metadata
+ * plus the remaining markdown body. The grammar is intentionally minimal
+ * — just enough to recognise:
+ *
+ * ```
+ * ---
+ * name: my-skill
+ * description: One-line summary.
+ * ---
+ *
+ * # Body
+ * ```
+ *
+ * Unknown frontmatter keys are ignored. Throws `SkillParseError`-style
+ * `Error` instances with a descriptive message when required fields are
+ * missing or malformed; the caller decides how to surface them.
+ */
+export declare function parseSkillFile(rawContent: string): {
+    metadata: SkillMetadata;
+    body: string;
+};

package/dist/strategy/discover/discover.d.ts

@@ -0,0 +1,16 @@
+import type { DiscoverStrategiesOptions, DiscoverStrategiesResult } from "./discover.types";
+/**
+ * Discover all available strategies on disk.
+ *
+ * Returns schema-validated strategies plus warnings for any candidate
+ * that failed to parse or validate. See the module header for the full
+ * list of sources scanned.
+ *
+ * @param options - Optional cwd / dataDir / includeBundled overrides.
+ * @example
+ * ```ts
+ * const { strategies, warnings } = await discoverStrategies();
+ * for (const s of strategies) console.log(s.label, "→", s.path);
+ * ```
+ */
+export declare function discoverStrategies(options?: DiscoverStrategiesOptions): Promise<DiscoverStrategiesResult>;

package/dist/strategy/discover/discover.types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Where a discovered strategy was found.
+ *
+ * - `bundled` — shipped with `@comma-agents/core` under `packages/core/strategies/`.
+ * - `cwd` — single strategy file under `<cwd>/.comma/strategies/`.
+ * - `cwd-project` — strategy referenced by a `comma-project.json`
+ *   inside `<cwd>/.comma/strategies/<project>/`.
+ * - `cwd-root-project` — strategy referenced by `<cwd>/.comma/comma-project.json`.
+ * - `data` — single strategy file under `<dataDir>/strategies/`.
+ * - `data-project` — strategy referenced by a `comma-project.json`
+ *   inside `<dataDir>/strategies/<project>/`.
+ */
+export type DiscoveredStrategyOrigin = "bundled" | "bundled-project" | "cwd" | "cwd-project" | "cwd-root-project" | "data" | "data-project";
+/** A successfully discovered and schema-validated strategy. */
+export interface DiscoveredStrategy {
+    /** Strategy `name` field from the file. */
+    readonly name: string;
+    /** Optional strategy `description` field. */
+    readonly description?: string;
+    /** Strategy `version` field. */
+    readonly version: string;
+    /** Absolute path to the strategy file on disk. */
+    readonly path: string;
+    /**
+     * When the strategy is part of a project, the absolute path to the
+     * project's `comma-project.json`. Used by the daemon to call
+     * `loadProject(manifestPath)` before loading the strategy.
+     */
+    readonly manifestPath?: string;
+    /** Where this strategy was found. */
+    readonly origin: DiscoveredStrategyOrigin;
+    /**
+     * Human-readable label. For project-scoped strategies this is
+     * `"<project> > <name>"`; otherwise just `<name>`.
+     */
+    readonly label: string;
+}
+/** A discovery candidate that could not be loaded or validated. */
+export interface DiscoveryWarning {
+    /** Absolute path to the candidate that failed. */
+    readonly path: string;
+    /** Reason the candidate was excluded (parse/validation error message). */
+    readonly reason: string;
+}
+/** Options for {@link discoverStrategies}. */
+export interface DiscoverStrategiesOptions {
+    /** Working directory to scan for `.comma/strategies/`. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /**
+     * Platform data directory to scan for `strategies/`.
+     * Defaults to `resolveDataDir()`.
+     */
+    readonly dataDir?: string;
+    /**
+     * Whether to include the strategies bundled with `@comma-agents/core`
+     * (under `packages/core/strategies/`). Defaults to `true`.
+     */
+    readonly includeBundled?: boolean;
+}
+/** Result of {@link discoverStrategies}. */
+export interface DiscoverStrategiesResult {
+    /**
+     * Schema-validated strategies, in source-priority order:
+     * bundled → cwd → cwd-project → cwd-root-project → data → data-project.
+     * Duplicates (by absolute path) are removed.
+     */
+    readonly strategies: readonly DiscoveredStrategy[];
+    /** Files that were skipped because they failed to parse or validate. */
+    readonly warnings: readonly DiscoveryWarning[];
+}

package/dist/strategy/discover/discover.utils.d.ts

@@ -0,0 +1,95 @@
+import type { DiscoveredStrategy, DiscoveredStrategyOrigin } from "./discover.types";
+/**
+ * Internal: parse outcome — either a validated strategy header, or a
+ * reason it was skipped. Helpers return these so the caller can collect
+ * warnings centrally.
+ */
+export type ParsedStrategyHeader = {
+    readonly ok: true;
+    readonly name: string;
+    readonly version: string;
+    readonly description: string | undefined;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Internal: parse outcome for a project manifest. */
+export type ParsedProjectManifest = {
+    readonly ok: true;
+    readonly name: string;
+    readonly description: string | undefined;
+    /** Absolute paths of every strategy file referenced by this manifest. */
+    readonly strategyPaths: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Return `true` when `filePath` ends with one of {@link STRATEGY_EXTENSIONS}. */
+export declare function hasStrategyExtension(filePath: string): boolean;
+/**
+ * Resolve a strategy file's parse format from its extension.
+ *
+ * `.json` / `.jsonc` parse as JSON (comments stripped); `.yaml` / `.yml`
+ * parse as YAML. Throws when the extension is unrecognized — callers
+ * should gate via {@link hasStrategyExtension} first.
+ */
+export declare function formatForExtension(filePath: string): "json" | "yaml";
+/**
+ * Read a strategy file from disk and return its raw text plus the
+ * detected parse format (based on extension).
+ *
+ * Exposed from core so the daemon executor can reuse the same logic
+ * without re-implementing JSON/YAML detection or comment stripping.
+ *
+ * @throws when the file does not exist or has an unsupported extension.
+ */
+export declare function readStrategyFile(filePath: string): Promise<{
+    readonly content: string;
+    readonly format: "json" | "yaml";
+}>;
+/**
+ * Parse a strategy file and return its validated header
+ * (`name`, `version`, `description`). Failures are returned as a
+ * `{ ok: false, reason }` value rather than thrown so the caller can
+ * batch-collect warnings.
+ */
+export declare function parseStrategyHeader(filePath: string): Promise<ParsedStrategyHeader>;
+/**
+ * Parse a `comma-project.json` manifest and return its name plus the
+ * absolute paths of every strategy it references. Strategy entries in
+ * the manifest are resolved relative to the manifest's directory.
+ */
+export declare function parseProjectManifest(manifestPath: string): Promise<ParsedProjectManifest>;
+/** List strategy files directly inside `dir` (non-recursive). */
+export declare function listStrategyFiles(dir: string): string[];
+/**
+ * List `<dir>/<child>/comma-project.json` manifest paths for every
+ * subdirectory of `dir` that contains one.
+ */
+export declare function listProjectManifests(dir: string): string[];
+/**
+ * Build a {@link DiscoveredStrategy} from a parsed strategy header.
+ * Project-scoped entries get a `"<project> > <name>"` label.
+ */
+export declare function buildDiscoveredStrategy(input: {
+    readonly header: Extract<ParsedStrategyHeader, {
+        ok: true;
+    }>;
+    readonly path: string;
+    readonly origin: DiscoveredStrategyOrigin;
+    readonly projectName?: string;
+    readonly manifestPath?: string;
+}): DiscoveredStrategy;
+/**
+ * Locate the root directory of the `@comma-agents/core` package.
+ *
+ * Walks up from this source file looking for a `package.json` whose
+ * `name === "@comma-agents/core"`. This works in both workspace
+ * development (where the source lives under `packages/core/src/`) and
+ * when the package is consumed from `node_modules`.
+ *
+ * Returns `null` if the package root cannot be located (e.g., when the
+ * file has been bundled into a single artifact without a package
+ * manifest nearby).
+ */
+export declare function findCorePackageRoot(): string | null;

package/dist/strategy/discover/index.d.ts

@@ -0,0 +1,3 @@
+export { discoverStrategies } from "./discover";
+export type { DiscoveredStrategy, DiscoveredStrategyOrigin, DiscoverStrategiesOptions, DiscoverStrategiesResult, DiscoveryWarning, } from "./discover.types";
+export { readStrategyFile } from "./discover.utils";

package/dist/strategy/exporter/exporter.d.ts

@@ -0,0 +1,27 @@
+import type { LoadedStrategy } from "../loader/loader.types";
+import type { ExportStrategyOptions } from "./exporter.types";
+/**
+ * Serialize a loaded strategy back to a JSON or YAML string.
+ *
+ * Uses the original validated data (`strategy.raw`) for faithful
+ * round-trip serialization. This means any fields that were normalized
+ * or defaulted during loading are preserved in their original form.
+ *
+ * @param strategy - A previously loaded strategy.
+ * @param options  - Format and indentation options.
+ * @returns The serialized strategy string.
+ *
+ * @example
+ * ```ts
+ * import { loadStrategy, exportStrategy } from "@comma-agents/core";
+ *
+ * const strategy = await loadStrategy("./strategy.json", { providers });
+ *
+ * // Export as JSON (default)
+ * const json = exportStrategy(strategy);
+ *
+ * // Export as YAML
+ * const yaml = exportStrategy(strategy, { format: "yaml" });
+ * ```
+ */
+export declare function exportStrategy(strategy: LoadedStrategy, options?: ExportStrategyOptions): string;

package/dist/strategy/exporter/exporter.types.d.ts

@@ -0,0 +1,6 @@
+export interface ExportStrategyOptions {
+    /** Output format. @default "json" */
+    readonly format?: "json" | "yaml";
+    /** Indentation for JSON output. @default 2 */
+    readonly indent?: number;
+}

package/dist/strategy/index.d.ts

@@ -0,0 +1,10 @@
+export type { DiscoveredStrategy, DiscoveredStrategyOrigin, DiscoverStrategiesOptions, DiscoverStrategiesResult, DiscoveryWarning, } from "./discover/index";
+export { discoverStrategies, readStrategyFile } from "./discover/index";
+export { exportStrategy } from "./exporter/exporter";
+export type { ExportStrategyOptions } from "./exporter/exporter.types";
+export { loadStrategy, loadStrategyFromString } from "./loader/loader";
+export type { LoadedStrategy, LoadStrategyOptions, } from "./loader/loader.types";
+export type { LoadedProject } from "./loader/project-loader";
+export { loadProject } from "./loader/project-loader";
+export type { AgentDef, AgentStep, BroadcastFlowDef, BuiltInToolName, CommaProjectManifest, CycleFlowDef, FlowDef, LLMAgentDef, SequentialFlowDef, Strategy, UserAgentDef, } from "./schema";
+export { CommaProjectManifestSchema, isAgentStep, isFlowDef, isLLMAgentDef, isUserAgentDef, StrategySchema, } from "./schema";

package/dist/strategy/loader/loader.d.ts

@@ -0,0 +1,39 @@
+import type { LoadedStrategy, LoadStrategyOptions } from "./loader.types";
+/**
+ * Load a strategy from a JSON or YAML file.
+ *
+ * Auto-detects format by file extension (`.json`, `.yaml`, `.yml`).
+ * Validates the structure, instantiates agents and flows, and returns
+ * a runnable `LoadedStrategy`.
+ *
+ * Model and tool resolution happen via global registries. Call
+ * `registerModel()` / `registerProvider()` / `registerTool()` before
+ * loading a strategy.
+ *
+ * @param filePath - Absolute or relative path to the strategy file.
+ * @param options  - Input collector, flow hooks, model override.
+ * @returns The loaded strategy with a runnable entry flow.
+ * @throws {StrategyValidationError} If the file is invalid or missing required fields.
+ *
+ * @example
+ * ```ts
+ * import { loadStrategy, registerProvider } from "@comma-agents/core";
+ *
+ * registerProvider("openai", (modelId) => openai(modelId));
+ * const strategy = await loadStrategy("./strategy.json");
+ * ```
+ */
+export declare function loadStrategy(filePath: string, options?: LoadStrategyOptions): Promise<LoadedStrategy>;
+/**
+ * Load a strategy from a raw JSON or YAML string.
+ *
+ * Useful when the content is already in memory (e.g., received over
+ * a WebSocket from the TUI, or from a test fixture).
+ *
+ * @param content - The raw strategy string.
+ * @param format  - "json" or "yaml".
+ * @param options - Input collector, hooks, abort signal, model override.
+ * @returns The loaded strategy with a runnable entry flow.
+ * @throws {StrategyValidationError} If parsing or validation fails.
+ */
+export declare function loadStrategyFromString(content: string, format: "json" | "yaml", options?: LoadStrategyOptions): Promise<LoadedStrategy>;

package/dist/strategy/loader/loader.types.d.ts

@@ -0,0 +1,106 @@
+import type { Agent } from "../../agents/agent/agent.types";
+import type { InputCollector } from "../../agents/built-in/user/user-agent.types";
+import type { FlowHooks } from "../../flows/flow/flow.types";
+import type { LanguageService } from "../../language";
+import type { SkillRegistry } from "../../skills/skills.types";
+import type { LaunchStrategyHandle } from "../../tools/launch-strategy.types";
+import type { Strategy } from "../schema";
+/**
+ * Options for loading a strategy.
+ *
+ * Model and tool resolution happen internally via global registries
+ * (registerModel / registerProvider / registerTool). The loader does
+ * not accept provider factories or credential stores — callers must
+ * configure those globally before loading a strategy.
+ */
+export interface LoadStrategyOptions {
+    /**
+     * Input collector function for user agents.
+     * Required if the strategy contains any user agents with `requireInput: true`.
+     */
+    readonly inputCollector?: InputCollector;
+    /**
+     * Flow hooks to inject into all flows via `hookIntoFlow()` after
+     * construction. Useful for the daemon to observe step execution,
+     * flow lifecycle, etc.
+     */
+    readonly flowHooks?: FlowHooks;
+    /**
+     * Override the model for ALL LLM agents in the strategy.
+     *
+     * When set, every agent's model string is replaced with this value,
+     * regardless of what the strategy file specifies. Format: "providerID/modelID".
+     *
+     * Useful for the daemon's `--model-override` flag, allowing a single
+     * daemon instance to serve any provider/model combination without
+     * editing strategy files.
+     *
+     * @example "github-copilot/gpt-4o"
+     */
+    readonly modelOverride?: string;
+    /**
+     * Skill registry to make available to every LLM agent in this strategy.
+     *
+     * When provided, every agent that lists `load_skill` in its `tools`
+     * array can resolve skill names against this registry. The loader also
+     * prepends a compact `## Available Skills` block to each agent's
+     * `systemPrompt` so the model knows what to ask for. Build the
+     * registry with `loadSkills(workspaceRoot)`.
+     */
+    readonly skillRegistry?: SkillRegistry;
+    /**
+     * Optional base directory of the strategy file, used to resolve relative paths
+     * (such as system prompt file paths).
+     */
+    readonly strategyDir?: string;
+    /**
+     * Optional handle for spawning sub-strategies, threaded into every
+     * agent's {@link ToolContext} so tools such as `launch_strategy` can
+     * delegate to a runtime-supplied implementation (e.g., the daemon
+     * executor, which wires the nested run's flow/agent hooks to the
+     * parent run's broadcast pipeline).
+     *
+     * When omitted, `launch_strategy` falls back to an in-process
+     * `loadStrategy` + `flow.call()` invocation with no broadcast.
+     */
+    readonly launchStrategy?: LaunchStrategyHandle;
+    /** Optional runtime language service threaded into every agent tool call. */
+    readonly languageService?: LanguageService;
+    /**
+     * Optional run identifier propagated to every agent's
+     * {@link AgentConfig.runId} (and from there into each tool's
+     * {@link ToolContext.runId}).
+     *
+     * Distinct from `sessionId` (which scopes the audit log and trash
+     * metadata across an entire user/daemon session): `runId` identifies
+     * a single strategy invocation. The daemon executor passes the
+     * top-level run id here, and gives each `launch_strategy` sub-load
+     * a *fresh* derived id, so recursive strategy invocations have
+     * isolated state for tools that key on `runId` (notably `todo_*`,
+     * which shares state across agents within one invocation but must not
+     * leak into recursive sub-runs).
+     *
+     * When omitted, runId-aware tools fall back to `agentName`-only
+     * keying (their original behaviour) — safe for tests and embedded
+     * callers that don't care about cross-launch isolation.
+     */
+    readonly runId?: string;
+}
+/**
+ * The result of loading a strategy — contains the runnable flow
+ * and metadata for inspection.
+ */
+export interface LoadedStrategy {
+    /** Strategy name from the file. */
+    readonly name: string;
+    /** Strategy version from the file. */
+    readonly version: string;
+    /** Optional description. */
+    readonly description?: string;
+    /** The instantiated entry flow as a runnable Agent. */
+    readonly flow: Agent;
+    /** The instantiated agent registry (for inspection/testing). */
+    readonly agents: Readonly<Record<string, Agent>>;
+    /** The raw validated strategy data (for exporting). */
+    readonly raw: Strategy;
+}

package/dist/strategy/loader/loader.utils.d.ts

@@ -0,0 +1,20 @@
+import type { Agent } from "../../agents/agent/agent.types";
+import type { SkillRegistry } from "../../skills/skills.types";
+import type { FlowDef, Strategy } from "../schema";
+import type { LoadStrategyOptions } from "./loader.types";
+/**
+ * Build all agents defined in the strategy into live Agent instances.
+ *
+ * Model and tool resolution happen inside createAgent via global
+ * registries — the loader only passes string identifiers through.
+ */
+export declare function buildAgentRegistry(strategy: Strategy, options: LoadStrategyOptions): Promise<Record<string, Agent>>;
+/** @internal Used by tests to assert the header gets attached. */
+export declare function previewSkillsHeader(registry: SkillRegistry): string;
+/**
+ * Recursively build a flow definition into a runnable Agent.
+ *
+ * If `options.flowHooks` is provided, hooks are injected into the
+ * created flow via `hookIntoFlow()` after construction.
+ */
+export declare function buildFlow(flowDef: FlowDef, agents: Readonly<Record<string, Agent>>, options: LoadStrategyOptions): Agent;

package/dist/strategy/loader/project-loader.d.ts

@@ -0,0 +1,9 @@
+import type { CommaProjectManifest } from "../schema";
+export interface LoadedProject {
+    readonly name: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly manifest: CommaProjectManifest;
+    readonly manifestDir: string;
+}
+export declare function loadProject(manifestPath: string): Promise<LoadedProject>;