@comma-agents/core 2.0.0-rc.0

package/dist/tools/io/newline.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Newline style as detected in a source buffer.
+ *
+ * - `"lf"`    — Unix (`\n`). Default for new files.
+ * - `"crlf"`  — Windows (`\r\n`).
+ * - `"mixed"` — File contains both `\n` and `\r\n`. We preserve the
+ *   dominant style on write but flag this on read.
+ * - `"none"`  — No newlines at all (single line or empty file).
+ */
+export type NewlineStyle = "lf" | "crlf" | "mixed" | "none";
+/**
+ * Detect the newline style of a string by counting `\r\n` vs lone
+ * `\n` occurrences.
+ *
+ * Lone `\r` (classic Mac OS) is treated as `none`/`lf` per modern
+ * tooling — we don't try to preserve it.
+ */
+export declare function detectNewline(content: string): NewlineStyle;
+/**
+ * Normalize all newlines in `content` to `\n`. Used before applying
+ * structural edits (so `oldText` matching is newline-agnostic);
+ * `applyNewline` re-emits the original style afterwards.
+ */
+export declare function toLF(content: string): string;
+/**
+ * Re-apply a newline style to a buffer that has been normalized to LF.
+ *
+ * - `"crlf"` rewrites `\n` back to `\r\n`.
+ * - `"lf"`, `"mixed"`, and `"none"` leave the content as-is. (For
+ *   `"mixed"` we deliberately don't try to reconstruct the original
+ *   per-line pattern; preserving LF is the safer default and matches
+ *   what editors do when "Use LF" is the user's setting.)
+ */
+export declare function applyNewline(content: string, style: NewlineStyle): string;

package/dist/tools/io/sandbox-error.d.ts

@@ -0,0 +1,13 @@
+import type { SandboxViolationError } from "../../errors";
+import type { ToolError } from "../tool.types";
+/**
+ * Map a `SandboxViolationError` to the appropriate `ToolError`.
+ *
+ * Mapping:
+ * - `jail`, `absolute-path`       → `outside_workspace` (non-recoverable;
+ *   the path is structurally invalid, not just policy-blocked).
+ * - `read-denied`, `write-denied`,
+ *   `forbidden-glob`, `ask-no-handler`,
+ *   `ask-aborted`                 → `permission_denied`.
+ */
+export declare function sandboxErrorToToolError(error: SandboxViolationError): ToolError;

package/dist/tools/io/session-file-state.d.ts

@@ -0,0 +1,68 @@
+import type { AuditEntry } from "./audit.types";
+/**
+ * Most-recent known state for a single file in this session.
+ */
+export interface SessionFileEntry {
+    /**
+     * Workspace-relative path of the file.
+     */
+    readonly path: string;
+    /**
+     * SHA-256 the agent last produced or observed for this file. For
+     * deleted files this is the hash at the moment of deletion (so the
+     * LLM can re-create with the correct expected hash if it wants).
+     */
+    readonly sha256: string;
+    /**
+     * `true` when the file is known to have been deleted in this
+     * session (most recent audit entry was a `"delete"`). Lookups still
+     * return the entry so the LLM can see it was deleted.
+     */
+    readonly deleted: boolean;
+    /**
+     * `true` when the on-disk hash no longer matches `sha256` (the file
+     * was edited outside the agent between sessions). Set by
+     * `verifySessionFileState` — defaults to `false` from
+     * `buildSessionFileState` alone.
+     */
+    readonly stale: boolean;
+}
+/**
+ * Snapshot of every file path the session has touched, keyed by
+ * workspace-relative path.
+ *
+ * Immutable from the caller's perspective: rebuild by replaying the
+ * audit log rather than mutating in place.
+ */
+export type SessionFileState = ReadonlyMap<string, SessionFileEntry>;
+/**
+ * Replay an ordered audit log into a `SessionFileState`.
+ *
+ * Replay rules (deterministic, audit-log order):
+ * - `"create"` / `"update"` → set `{ sha256: afterSha256, deleted: false }`.
+ *   `afterSha256` is required; entries missing it are skipped (defensive
+ *   against malformed log lines).
+ * - `"delete"` → set `{ sha256: beforeSha256 ?? "", deleted: true }`.
+ * - `"move"` → delete the source entry, then upsert the target with
+ *   `afterSha256`.
+ * - Failed entries (`success: false`) are skipped — they didn't
+ *   mutate disk so the prior state stands.
+ *
+ * Replays run in O(n) over the entries. Caller is responsible for
+ * passing entries in chronological order; `AuditSink.load` guarantees
+ * insertion order, which is chronological.
+ */
+export declare function buildSessionFileState(entries: readonly AuditEntry[]): SessionFileState;
+/**
+ * For each known (non-deleted) entry in `state`, recompute the
+ * on-disk SHA-256 and flag entries whose stored hash no longer
+ * matches as `stale`. Missing files (`ENOENT`) are also flagged
+ * stale so the LLM can decide whether to re-create.
+ *
+ * Returns a fresh `SessionFileState` — does not mutate the input.
+ *
+ * @param state - Result of `buildSessionFileState`.
+ * @param resolveAbsolute - Map workspace-relative path → absolute
+ *   path. Provided by the caller so this module stays sandbox-free.
+ */
+export declare function verifySessionFileState(state: SessionFileState, resolveAbsolute: (path: string) => string): Promise<SessionFileState>;

package/dist/tools/io/stale-file.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Recovery hint returned on every `stale_file` failure. Appended to
+ * the tool's LLM-facing `output` by `agent.utils.ts` (because
+ * `error.recoverable` is `true`).
+ *
+ * Wording is deliberately imperative and short — the LLM is asked
+ * to perform a specific corrective action, not to "consider" one.
+ */
+export declare const STALE_FILE_RECOVERY_HINT = "Re-read the file to obtain the current sha256 and re-apply your edit.";

package/dist/tools/io/trash.d.ts

@@ -0,0 +1,57 @@
+/** Metadata stored inside each trash archive. */
+export interface TrashMetadata {
+    readonly trashedAt: string;
+    readonly originalPath: string;
+    readonly originalSha256: string;
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly agentName?: string;
+}
+/** Subset of TrashMetadata injected by the daemon executor into the sandbox config. */
+export type SandboxTrashMetadata = Pick<TrashMetadata, "runId" | "sessionId">;
+/** A single trash entry returned by `listTrash`. */
+export interface TrashEntry {
+    readonly path: string;
+    readonly metadata: TrashMetadata;
+    readonly sizeBytes: number;
+}
+/**
+ * Compute the trash bucket directory for `workspaceRoot`.
+ */
+export declare function trashWorkspaceDir(workspaceRoot: string): string;
+/**
+ * Move `absSourcePath` into the workspace's trash bucket as a tar.gz
+ * archive, returning the absolute path to the archive.
+ *
+ * The archive contains:
+ * - `metadata.json` with audit information
+ * - The original file at its workspace-relative path
+ */
+export declare function moveToTrash(workspaceRoot: string, absSourcePath: string, metadata?: Omit<TrashMetadata, "trashedAt" | "originalPath" | "originalSha256">): Promise<string>;
+/**
+ * List all trash entries for a workspace.
+ */
+export declare function listTrash(workspaceRoot: string): Promise<readonly TrashEntry[]>;
+/**
+ * Read the metadata.json from a trash archive without extracting files.
+ */
+export declare function readTrashMetadata(archivePath: string): Promise<TrashMetadata | undefined>;
+/**
+ * Restore a file from a trash archive.
+ *
+ * @param workspaceRoot - Workspace root directory.
+ * @param trashPath - Absolute path to the .tar.gz trash archive.
+ * @param targetPath - Optional workspace-relative override for the restore location.
+ *   Defaults to the original path from metadata.
+ * @returns The absolute path of the restored file.
+ */
+export declare function restoreFromTrash(workspaceRoot: string, trashPath: string, targetPath?: string): Promise<string>;
+/**
+ * Clear all trash entries for a workspace.
+ *
+ * @returns Count of cleared entries and total bytes freed.
+ */
+export declare function clearTrash(workspaceRoot: string): Promise<{
+    cleared: number;
+    bytesFreed: number;
+}>;

package/dist/tools/launch-strategy.types.d.ts

@@ -0,0 +1,38 @@
+/** Input to a {@link LaunchStrategyHandle}. */
+export interface LaunchStrategyRequest {
+    /** Absolute path to the strategy file. */
+    readonly strategyPath: string;
+    /**
+     * Optional absolute path to a `comma-project.json` manifest. When
+     * present, the runtime is expected to call `loadProject(manifestPath)`
+     * before loading the strategy (registering custom tools, etc.).
+     */
+    readonly manifestPath?: string;
+    /** Initial message passed to the strategy's entry flow. */
+    readonly input: string;
+    /**
+     * Provider/model override applied to all LLM agents in the
+     * sub-strategy. Format: `"providerID/modelID"`.
+     */
+    readonly modelOverride?: string;
+}
+/** Output of a successful sub-strategy run. */
+export interface LaunchStrategyResult {
+    /** The sub-strategy's `name` field. */
+    readonly strategyName: string;
+    /** Final text produced by the strategy's entry flow. */
+    readonly text: string;
+    /**
+     * Why the flow stopped (e.g., `"stop"`, `"tool-calls"`). Mirrors
+     * `AgentCallResult.finishReason` from the underlying flow call.
+     */
+    readonly finishReason?: string;
+}
+/**
+ * Run a sub-strategy and return its final result.
+ *
+ * Implementations are responsible for wiring `inputCollector`,
+ * `flowHooks`, agent hooks, and the loaded project (if any), as well
+ * as broadcasting events to any observers.
+ */
+export type LaunchStrategyHandle = (request: LaunchStrategyRequest) => Promise<LaunchStrategyResult>;

package/dist/tools/result/index.d.ts

@@ -0,0 +1 @@
+export { errorResult, okResult, toolError } from "./result";

package/dist/tools/result/result.d.ts

@@ -0,0 +1,47 @@
+import type { ToolError, ToolErrorKind, ToolResult } from "../tool.types";
+/**
+ * Build a successful `ToolResult`.
+ *
+ * Use this from every tool's `execute` to guarantee the `ok` invariant
+ * (`ok: true` ⇒ `error` undefined) without having to repeat the shape.
+ *
+ * @param output - Text returned to the LLM.
+ * @param options - Optional structured `data` and `metadata` payloads.
+ * @example
+ * ```ts
+ * return okResult("Wrote 12 bytes", { data: { sha256, sizeBytes: 12 } });
+ * ```
+ */
+export declare function okResult<DataShape = unknown>(output: string, options?: {
+    readonly data?: DataShape;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}): ToolResult<DataShape>;
+/**
+ * Build a failure `ToolResult` from a structured `ToolError`.
+ *
+ * `output` defaults to `error.message` so the LLM still receives a
+ * human-readable string when the AI SDK only forwards `output`.
+ *
+ * @param errorInput - Either a fully-built `ToolError` or the fields needed to construct one.
+ * @param options - Optional `output` override and `data` payload.
+ * @example
+ * ```ts
+ * return errorResult({
+ *   kind: "stale_file",
+ *   message: "File changed since last read",
+ *   path,
+ *   recoverable: true,
+ *   suggestedNextAction: STALE_FILE_RECOVERY_HINT,
+ * });
+ * ```
+ */
+export declare function errorResult<DataShape = unknown>(errorInput: ToolError, options?: {
+    readonly output?: string;
+    readonly data?: DataShape;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}): ToolResult<DataShape>;
+/**
+ * Convenience: build a `ToolError` without manually spelling the literal kind twice.
+ * Equivalent to writing the object literal directly; provided for ergonomics.
+ */
+export declare function toolError(kind: ToolErrorKind, message: string, fields?: Omit<ToolError, "kind" | "message">): ToolError;

package/dist/tools/tool.constants.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDefinition } from "./tool.types";
+/**
+ * The set of tool names recognized as built-in.
+ */
+export declare const BUILT_IN_TOOL_NAMES: readonly ["read_file", "list_directory", "search_files", "glob", "create_file", "write_file", "edit_file", "delete_file", "restore_file", "move_file", "run_command", "webfetch", "load_skill", "list_skills", "list_strategy", "launch_strategy", "todo_add", "todo_complete", "todo_get", "todo_get_next", "todo_remove", "todo_clear", "ask_question", "lsp_request"];
+/** Factory map for instantiating built-in tools by name. */
+export declare const BUILT_IN_TOOL_FACTORIES: Readonly<Record<string, () => ToolDefinition>>;

package/dist/tools/tool.registry.d.ts

@@ -0,0 +1,54 @@
+import type { ToolDefinition } from "./tool.types";
+/**
+ * Register a custom tool with the global tool registry.
+ *
+ * Registered tools can be referenced by name in agent definitions
+ * (strategy files, agent descriptions, or programmatic config).
+ * Custom registry tools take precedence over built-in tools during
+ * resolution — if you register a tool with a built-in name (e.g., "bash"),
+ * it shadows the default. A warning is logged in that case.
+ *
+ * @example
+ * ```ts
+ * import { registerTool, defineTool } from "@comma-agents/core";
+ *
+ * const myTool = defineTool({
+ *   description: "Fetch a URL",
+ *   parameters: z.object({ url: z.string() }),
+ *   execute: async ({ url }) => okResult(await fetch(url).then(r => r.text())),
+ * });
+ *
+ * registerTool("fetch", myTool);
+ * ```
+ */
+export declare function registerTool(name: string, tool: ToolDefinition): void;
+/**
+ * Remove a previously registered custom tool.
+ * Returns `true` if the tool was registered and removed.
+ * Built-in tools cannot be unregistered via this function.
+ */
+export declare function unregisterTool(name: string): boolean;
+/**
+ * Resolve an array of tool name strings into a `Record<string, ToolDefinition>`.
+ *
+ * Resolution order for each name:
+ * 1. Global tool registry (custom tools via `registerTool()`)
+ * 2. Built-in tool factories (see `BUILT_IN_TOOL_NAMES` in `tool.constants.ts`)
+ * 3. Explicit `customTools` parameter (passed by the strategy loader / description loader)
+ * 4. Error — unknown tool name
+ *
+ * Custom registry tools shadow built-in tools of the same name.
+ *
+ * @throws {StrategyValidationError} If a tool name cannot be resolved.
+ */
+export declare function resolveTools(toolNames: readonly string[], agentName: string, customTools?: Readonly<Record<string, ToolDefinition>>): Record<string, ToolDefinition>;
+/**
+ * Get the list of currently registered custom tool names.
+ * Does not include built-in tools.
+ */
+export declare function getRegisteredToolNames(): readonly string[];
+/**
+ * Reset the global tool registry to empty state.
+ * Primarily for tests.
+ */
+export declare function resetToolRegistry(): void;

package/dist/tools/tool.types.d.ts

@@ -0,0 +1,191 @@
+import type { z } from "zod";
+import type { InputCollector } from "../agents/built-in/user/user-agent.types";
+import type { Guard, Policy } from "../guard/guard.types";
+import type { LanguageService } from "../language";
+import type { SkillRegistry } from "../skills/skills.types";
+import type { AuditSink } from "./io/audit.types";
+import type { LaunchStrategyHandle } from "./launch-strategy.types";
+/**
+ * Context passed to tool execute functions.
+ * Provides the calling agent's identity, its per-tool Guard for
+ * file-system and command authorization, cancellation support,
+ * and optional session/audit/skill state.
+ */
+export interface ToolContext {
+    /** Name of the agent that invoked this tool. */
+    readonly agentName: string;
+    /** AbortSignal for cancellation propagation. */
+    readonly abort: AbortSignal;
+    /**
+     * Per-tool guard that handles path resolution, jail enforcement,
+     * policy chain evaluation, and interactive "ask" dispatch.
+     * Always present — defaults to a permissive guard when none is configured.
+     */
+    readonly guard: Guard;
+    /**
+     * Optional session identifier. When present, mutations are written to a
+     * session-scoped audit log and `SessionFileState` can be reconstructed
+     * across runtime restarts.
+     *
+     * Sessions are a broader concept than runs — one user/daemon session
+     * typically spans many strategy runs and is the unit of audit-log
+     * grouping and trash-archive identification. For per-run isolation
+     * (notably `todo_*` silos across recursive `launch_strategy` calls),
+     * use {@link runId} instead.
+     */
+    readonly sessionId?: string;
+    /**
+     * Optional run identifier — one strategy invocation. The daemon
+     * supplies the top-level run's id at the entry point and a *fresh*
+     * derived id for each `launch_strategy` sub-load, so recursive
+     * sub-strategies get isolated state for tools that key on `runId`.
+     *
+     * Distinct from {@link sessionId}: sessionId groups many runs (audit,
+     * trash); runId identifies a single run. Tools that need per-run shared
+     * state with per-launch isolation (e.g., `todo_*`) silo on `runId`.
+     */
+    readonly runId?: string;
+    /**
+     * Optional audit sink for destructive file operations.
+     */
+    readonly auditSink?: AuditSink;
+    /**
+     * Optional skill registry exposed to the `load_skill` tool.
+     */
+    readonly skillRegistry?: SkillRegistry;
+    /**
+     * Optional input collector forwarded from the parent strategy.
+     *
+     * Tools that spawn sub-strategies (e.g., `launch_strategy`) pass this
+     * to `loadStrategyFromString` so any `user` agents in the child can
+     * prompt through the same UI as the parent run.
+     */
+    readonly inputCollector?: InputCollector;
+    /**
+     * Optional handle for spawning a sub-strategy.
+     *
+     * When provided by the runtime (e.g., the daemon executor), tools
+     * such as `launch_strategy` delegate to this handle instead of
+     * calling `loadStrategy` directly, so flow / agent hooks and
+     * broadcast wiring are reused for the nested run.
+     */
+    readonly launchStrategy?: LaunchStrategyHandle;
+    /**
+     * Optional runtime language service.
+     *
+     * Core defines the stable contract and language tools; runtimes such as the
+     * daemon provide concrete implementations (TypeScript today, more language
+     * adapters later).
+     */
+    readonly languageService?: LanguageService;
+}
+/**
+ * Closed enumeration of error kinds emitted by built-in tools.
+ *
+ * The set is fixed so callers (LLMs and orchestration code) can switch on
+ * `kind` without parsing free-form messages. New kinds are added here
+ * deliberately and never derived from underlying error strings.
+ */
+export type ToolErrorKind = "not_found" | "already_exists" | "permission_denied" | "outside_workspace" | "binary_file" | "file_too_large" | "stale_file" | "old_text_not_found" | "multiple_matches" | "overlapping_edits" | "patch_parse_error" | "patch_apply_error" | "command_failed" | "timeout" | "skill_unavailable" | "language_unavailable" | "unknown";
+/**
+ * Structured error returned by a tool when an operation cannot complete.
+ *
+ * Tools must populate `recoverable` and (when recoverable) `suggestedNextAction`
+ * so the calling LLM can self-correct without escalating to the user.
+ */
+export interface ToolError {
+    /** Stable machine-readable error category. */
+    readonly kind: ToolErrorKind;
+    /** Human-readable description of what went wrong. */
+    readonly message: string;
+    /** Resolved path the error refers to, when applicable. */
+    readonly path?: string;
+    /** Free-form structured detail (match ranges, conflict indices, etc.). */
+    readonly details?: Readonly<Record<string, unknown>>;
+    /** Whether the LLM can plausibly retry after applying `suggestedNextAction`. */
+    readonly recoverable: boolean;
+    /** When `recoverable`, a concrete instruction for the LLM's next call. */
+    readonly suggestedNextAction?: string;
+}
+/**
+ * Result returned from a tool execution.
+ *
+ * The shape is dual-purpose:
+ * - `output` and `metadata` remain the LLM-facing surface: `output` is the
+ *   text returned to the model and `metadata` is opaque side-channel data
+ *   for serializers and hooks.
+ * - `ok`, `error`, and `data` are the structured surface used by tests,
+ *   the daemon, and any code that needs to inspect the outcome without
+ *   parsing strings.
+ *
+ * `ok` is the source of truth for success/failure. When `ok` is `false`,
+ * `error` MUST be set. When `ok` is `true`, `error` MUST be undefined.
+ */
+export interface ToolResult<DataShape = unknown> {
+    /** Whether the tool completed successfully. */
+    readonly ok: boolean;
+    /** The textual output to return to the LLM. */
+    readonly output: string;
+    /** Structured payload — typed per-tool via the `DataShape` generic. */
+    readonly data?: DataShape;
+    /** Structured failure information. Required when `ok` is `false`. */
+    readonly error?: ToolError;
+    /** Optional opaque metadata for hooks and serializers. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Definition of a tool that an agent can invoke.
+ *
+ * Tools have a description (for the LLM), Zod-validated parameters,
+ * and an async execute function.
+ *
+ * Optionally, tools can contribute to the agent's system prompt via
+ * the `systemPrompt` field. This is useful when a tool needs to inject
+ * complex context or instructions that should be visible to the LLM.
+ *
+ * @typeParam ParameterSchema - Zod schema type for the tool's parameters
+ * @typeParam DataShape - Typed payload returned in `ToolResult.data`
+ */
+export interface ToolDefinition<ParameterSchema extends z.ZodType = z.ZodType, DataShape = unknown> {
+    /** Human-readable description of what this tool does (sent to the LLM). */
+    readonly description: string;
+    /** Zod schema that validates and types the tool's parameters. */
+    readonly parameters: ParameterSchema;
+    /**
+     * Additional policies for this tool (e.g., run_command deny/approval patterns).
+     * Added to the tool's Guard policy chain by `createSandbox()`.
+     */
+    readonly policies?: readonly Policy[];
+    /**
+     * Optional system prompt contribution from this tool.
+     *
+     * When provided, this content is injected ONCE into the agent's system
+     * prompt at agent creation time (not per-call). This allows tools to
+     * define complex context, instructions, or formatting requirements that
+     * the LLM should know about.
+     *
+     * Can be a static string or a function that receives the ToolContext
+     * and returns a string (sync or async). The function form is useful
+     * when the prompt depends on runtime state (e.g., current workspace).
+     *
+     * @example
+     * ```ts
+     * // Static prompt
+     * defineTool({
+     *   systemPrompt: "When using this tool, always format output as JSON.",
+     *   // ...
+     * })
+     *
+     * // Dynamic prompt (function)
+     * defineTool({
+     *   systemPrompt: async (toolContext) => {
+     *     return `Working directory: ${toolContext.guard.cwd}`;
+     *   },
+     *   // ...
+     * })
+     * ```
+     */
+    readonly systemPrompt?: string | ((toolContext: ToolContext) => Promise<string> | string);
+    /** Execute the tool with validated arguments and context. */
+    execute(validatedArguments: z.infer<ParameterSchema>, toolContext: ToolContext): Promise<ToolResult<DataShape>>;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@comma-agents/core",
+  "version": "2.0.0-rc.0",
+  "description": "Core agent orchestration framework: agents, flows, hooks, and providers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "bun run ../../scripts/build-public-package.ts core",
+    "prepack": "bun run build",
+    "test": "bun test --coverage",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src"
+  },
+  "dependencies": {
+    "@ai-sdk/openai-compatible": "2.0.30",
+    "@types/diff": "8.0.0",
+    "ai": "6.0.91",
+    "diff": "9.0.0",
+    "liquidjs": "10.27.0",
+    "tar-stream": "3.2.0",
+    "turndown": "7.2.4",
+    "yaml": "2.8.3",
+    "zod": "3.25.76",
+    "strip-json-comments": "5.0.3"
+  },
+  "engines": { "bun": ">=1.3.0" },
+  "publishConfig": { "access": "public", "tag": "next" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CloAI/CommaAgents.git",
+    "directory": "packages/core"
+  },
+  "author": "CloAI",
+  "license": "MIT",
+  "devDependencies": {
+    "@comma-agents/utils": "file:../utils",
+    "@types/tar-stream": "^3.1.4",
+    "@types/turndown": "5.0.6"
+  }
+}