@skaile/workspaces 5.4.0 → 5.6.0

package/dist/runner/src/agents/run-controller.d.ts

@@ -0,0 +1,208 @@
+/**
+ * agents/run-controller.ts
+ *
+ * The framework-owned lifecycle of `agent.run` runs, independent of the host
+ * that stores them and the driver that executes them.
+ *
+ * ```text
+ *             ┌───────────── approve ─────────────┐
+ * queued ──► running ──► waiting_approval ◄── (a held capability call)
+ *   ▲          │ └────► waiting_children ──┐ (children still live when the turn ends)
+ *   └──────────┴───────── resume ◄─────────┘
+ *              └──► succeeded | failed | cancelled   (cancelled from any live state)
+ * ```
+ *
+ * What it guarantees, whichever host drives it:
+ *
+ * - **Limits.** A run may delegate to a depth of {@link RunLimits.maxDepth}
+ *   (a root run started outside any run is depth 1) and a root run has at most
+ *   {@link RunLimits.maxConcurrentChildren} live descendants. A run whose
+ *   turn ended with live children is `waiting_children` and holds no driver;
+ *   the last child to finish resumes it with a host message.
+ * - **Serialization.** Runs of one `standing` instance execute one at a time
+ *   (a queue, so memory writes never interleave); other instances and `role`
+ *   instances run concurrently.
+ * - **Idempotent start.** A start with the same `(callerSessionId, callId)`
+ *   answers the run the first one created.
+ * - **Persisted approvals.** A held capability call (`requestApproval`) or a
+ *   held start parks the run in `waiting_approval`, its turn ends, and the
+ *   approval row survives a restart. Deciding claims the row with a
+ *   compare-and-set, so the stored operation executes at most once, with the
+ *   `operationId` it was parked under; its result is persisted before the
+ *   session is resumed with `{operationId, status, result}`. A decision on a
+ *   consumed or expired approval, or on one whose stored args no longer hash
+ *   to `argsHash`, is `approval_invalid`; so is re-requesting a call with
+ *   changed args.
+ * - **Cancel** stops the run and every descendant; their pending approvals expire.
+ *
+ * The controller imports nothing of a host: storage is the injected
+ * {@link RunStore}, execution the injected {@link RunLauncher}, policy the
+ * injected `authorize`, and the held operation runs through the injected
+ * `execute`. Run state changes go to the store's event log and `onEvent`;
+ * `subagent` protocol events go to `emit`.
+ */
+import type { AgentRun, AgentRunEventRecord, AgentRunFailure, AgentRunReport, Logger, RunHostMessage, RunStore, SubagentEvent } from "@skaile/workspaces/types";
+import type { AgentIo } from "@skaile/workspaces/types/manifests";
+/** Who acts. Built by the host from its own authentication, never from a model payload. */
+export interface RunActor {
+    /** User or service id; recorded as `AgentRun.requestedBy` on a start. */
+    id: string;
+    /**
+     * The session the call comes from. When set, the run must belong to this
+     * session's delegation tree (the session, or a run it started, dispatched
+     * it); an agent never reaches a run outside its own tree. Absent for a
+     * host-level actor (a REST route): only `authorize` gates it.
+     */
+    sessionId?: string;
+}
+export type RunAction = "start" | "read" | "cancel" | "decide" | "resume";
+/** What the controller needs to know about an instance a run addresses. */
+export interface RunInstanceInfo {
+    id: string;
+    lifecycle: "standing" | "role";
+    description?: string;
+    revisionHash?: string;
+    io?: AgentIo;
+    status: "ready" | "unavailable";
+    error?: string;
+}
+/** The delegation and concurrency bounds. */
+export interface RunLimits {
+    /** Deepest run chain; a root run started outside any run is depth 1. Default 2. */
+    maxDepth: number;
+    /** Live descendants one root run may have. Default 4. */
+    maxConcurrentChildren: number;
+}
+export declare const DEFAULT_RUN_LIMITS: RunLimits;
+export interface StartRunRequest {
+    instanceId: string;
+    /** Revision the caller saw; a different current revision is `revision_changed`. */
+    revisionHash?: string;
+    input?: unknown;
+    budget?: {
+        max_turns?: number;
+        max_tokens?: number;
+    };
+    /** Capability-dispatch call id; with the actor's session the idempotency key of the start. */
+    callId?: string;
+    /** `required` parks the run in `waiting_approval` until `decideApproval`. */
+    approval?: "required" | "none";
+}
+/** What one turn of a run's session is told to do. */
+export type RunTurn = {
+    kind: "start";
+    input: unknown;
+} | {
+    kind: "resume";
+    messages: RunHostMessage[];
+};
+/** How a turn ended. A run that is `waiting_approval` or `cancelled` after its turn ignores the outcome. */
+export type RunTurnOutcome = {
+    kind: "completed";
+    output?: unknown;
+} | {
+    kind: "failed";
+    error: AgentRunFailure;
+};
+/** The session a launcher built for one turn. */
+export interface RunDriverHandle {
+    /** Name of the driver the run executes on (`AgentRun.harness`). */
+    harness: string;
+    /** Run the turn to its end. Must settle promptly once the launch `signal` aborts. */
+    turn(turn: RunTurn): Promise<RunTurnOutcome>;
+    abort(reason?: unknown): void;
+    /** Release the session's process. Called after every turn: a suspended run holds no driver. */
+    dispose(): Promise<void>;
+}
+/** Answer of {@link RunLaunchContext.requestApproval} to the session's capability call. */
+export type RunOperationApproval = {
+    status: "pending_approval";
+    approvalId: string;
+    operationId: string;
+} | {
+    status: "approved" | "denied" | "expired";
+    approvalId: string;
+    operationId: string;
+    result?: unknown;
+    error?: AgentRunFailure;
+};
+export interface RunLaunchContext {
+    run: AgentRun;
+    /** `true` when the run's native session (`run.sessionId`) already exists and is continued. */
+    resuming: boolean;
+    /** The identity calls from this run's session carry (`{ id: run.requestedBy, sessionId: run.sessionId }`). */
+    actor: RunActor;
+    /** Aborts when the run is cancelled. */
+    signal: AbortSignal;
+    /**
+     * For the session's capability bridge: hold a `requiresApproval` call
+     * instead of executing it. Hand the answer to the model as the call's
+     * result; the run's turn ends and the controller resumes it after the decision.
+     */
+    requestApproval: (call: {
+        callId?: string;
+        capability: string;
+        args: unknown;
+    }) => Promise<RunOperationApproval>;
+}
+/** Builds the session for one turn of a run. */
+export type RunLauncher = (ctx: RunLaunchContext) => Promise<RunDriverHandle>;
+/** One held operation, handed to `execute` when its approval is granted. */
+export interface ApprovedOperation {
+    runId: string;
+    /** Stable across redelivery: execute the effect under this id so a host can deduplicate. */
+    operationId: string;
+    capability: string;
+    args: unknown;
+    /** The run's own identity, as the capability call would have carried it. */
+    actor: RunActor;
+}
+export interface RunControllerDeps {
+    store: RunStore;
+    launch: RunLauncher;
+    /** Host policy. Throw to refuse; the controller reports `not_authorized`. */
+    authorize: (actor: RunActor, run: AgentRun, action: RunAction) => void | Promise<void>;
+    /** The instance a run addresses; `undefined` = unknown. */
+    getInstance: (instanceId: string) => RunInstanceInfo | undefined | Promise<RunInstanceInfo | undefined>;
+    /** Execute an approved operation (the capability call the run was held on). Its return value is persisted as the result. */
+    execute: (operation: ApprovedOperation) => Promise<unknown>;
+    workspaceId: string;
+    limits?: Partial<RunLimits>;
+    /** `subagent` protocol events (started when a run is created, finished when it ends). */
+    emit?: (event: SubagentEvent) => void;
+    /** Called after each event was appended to the store's log; broadcast from here. */
+    onEvent?: (record: AgentRunEventRecord) => void;
+    /** Id of a run's native session; default `<workspaceId>:run:<runId>`. */
+    sessionIdFor?: (runId: string) => string;
+    log?: Logger;
+}
+/** A refused or impossible request. `code` is stable and reaches the model and the host unchanged. */
+export declare class AgentRunError extends Error {
+    readonly code: string;
+    readonly issues?: string[] | undefined;
+    constructor(code: string, message: string, issues?: string[] | undefined);
+}
+export interface RunController {
+    /** Create a run and queue it (or hold it behind an approval). Answers at once; see {@link waitForRun}. */
+    startRun(request: StartRunRequest, actor: RunActor): Promise<AgentRunReport>;
+    getRun(runId: string, actor: RunActor): Promise<AgentRun>;
+    getRunReport(runId: string, actor: RunActor): Promise<AgentRunReport>;
+    /** Resolve when the run ended or needs a decision (`waiting_approval`). */
+    waitForRun(runId: string, actor: RunActor): Promise<AgentRunReport>;
+    /** Cancel the run and all its descendants. */
+    cancelRun(runId: string, actor: RunActor): Promise<AgentRunReport>;
+    decideApproval(approvalId: string, decision: "approve" | "deny", actor: RunActor): Promise<AgentRunReport>;
+    /** Continue a run no driver of this process holds: re-queue it, or finish a delivery a restart cut short. */
+    resumeRun(runId: string, actor: RunActor): Promise<AgentRunReport>;
+    /** See {@link RunLaunchContext.requestApproval}. Trusted: the host's session bridge calls it, not the model. */
+    requestApproval(runId: string, call: {
+        callId?: string;
+        capability: string;
+        args: unknown;
+    }): Promise<RunOperationApproval>;
+    /** Cancel every run still live in this process and wait for their sessions to wind down. */
+    dispose(): Promise<void>;
+}
+/** Build a run controller over an injected store, launcher and authorizer. */
+export declare function createRunController(deps: RunControllerDeps): RunController;
+//# sourceMappingURL=run-controller.d.ts.map

package/dist/runner/src/agents/run-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-controller.d.ts","sourceRoot":"","sources":["../../../../runner/src/agents/run-controller.ts"],"names":[],"mappings":"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"}

package/dist/runner/src/agents/standalone-surface.d.ts

@@ -0,0 +1,30 @@
+/**
+ * agents/standalone-surface.ts
+ *
+ * The agent surface for a session that has no host and no `startAgentServer`
+ * around it (`skaile run "<prompt>"`, `skaile repl`): `agent.*` served by a
+ * nested driver session in this process, no `memory.*`, no `trigger.*`. Builds
+ * the capability registry, registers the surface, and hands back the
+ * `AgentSessionConfig` fields a session needs to expose it.
+ */
+import type { AgentEvent, Logger } from "@skaile/workspaces/types";
+import type { AgentSession, AgentSessionConfig } from "../session-builder.js";
+export interface StandaloneAgentSurfaceOpts {
+    /** The session config the surface is for (its driver, model and agent dir seed the nested role sessions). */
+    config: AgentSessionConfig;
+    /** Receives the `subagent` events of role runs. */
+    onEvent?: (event: AgentEvent) => void;
+    log?: Logger;
+    /** Builds a nested role session; defaults to `createAgentSession` (a seam for tests). */
+    createSession: (config: AgentSessionConfig) => Promise<AgentSession>;
+}
+export interface StandaloneAgentSurface {
+    /** Fields to layer onto the session config; `undefined` when the workspace has no instance to run. */
+    sessionConfig: Partial<AgentSessionConfig> | undefined;
+    /** Re-resolve the instances once the session is built (its composed `run` sub-agents are known then). */
+    attach: (session: AgentSession) => Promise<void>;
+    dispose: () => Promise<void>;
+}
+/** Build the in-process agent surface for `config`'s workspace, or none when the workspace declares no instance beyond the primary. */
+export declare function createStandaloneAgentSurface(opts: StandaloneAgentSurfaceOpts): Promise<StandaloneAgentSurface>;
+//# sourceMappingURL=standalone-surface.d.ts.map

package/dist/runner/src/agents/standalone-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone-surface.d.ts","sourceRoot":"","sources":["../../../../runner/src/agents/standalone-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAUnE,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI9E,MAAM,WAAW,0BAA0B;IACzC,6GAA6G;IAC7G,MAAM,EAAE,kBAAkB,CAAC;IAC3B,mDAAmD;IACnD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,aAAa,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,sBAAsB;IACrC,sGAAsG;IACtG,aAAa,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC;IACvD,yGAAyG;IACzG,MAAM,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAQD,uIAAuI;AACvI,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAiFjC"}

package/dist/runner/src/capability-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../../runner/src/capability-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../../runner/src/capability-registry.ts"],"names":[],"mappings":"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"}

package/dist/runner/src/composition/bootstrap.d.ts

@@ -1,59 +1,15 @@
 /**
  * composition/bootstrap.ts
  *
- * Wires the composition resolver into the agent session lifecycle.
- *
- * This module provides:
- *   - `resolveAgentComposition()` — called by session-builder.ts to produce
- *     inline blocks (→ system prompt) and discoverable entries (→ capability
- *     registry)
- *   - `registerCompositionCapabilities()` — called by serve.ts to register
- *     discoverable entries as Protocol v2 capabilities
- *
- * Phase 1 limitation: the content loader uses `resolveMixin()` which only
- * resolves local-path refs (./file.md, /abs/path). Scoped catalog refs
- * (@publisher/name) require a populated RepoMap from workspace config, which
- * Phase 2 / Library integration will provide. Unresolvable refs produce
- * warnings but do not block session start.
+ * Registers resolved composition entries with the session's capability
+ * registry (`registerCompositionCapabilities`, called by serve.ts) and opens
+ * the optional asset index used to describe them. Resolution itself lives in
+ * `resolve-instance.ts` (`resolveAgentInstance`).
  */
-import { type AgentManifest } from "@skaile/workspaces/core";
+import type { IAssetIndex } from "@skaile/workspaces/library";
 import type { Logger } from "@skaile/workspaces/types";
 import type { CapabilityRegistry } from "../capability-registry.js";
-import { type RepoMap } from "../mixin-resolver.js";
-import type { DiscoverableEntry, ResolvedComposition } from "./types.js";
-export type { ResolvedComposition };
-/**
- * Options for {@link resolveAgentComposition}.
- *
- * @docLink packages/runner/capabilities#resolve-agent-composition
- */
-export interface ResolveAgentCompositionOpts {
-    /** Path to the agent definition directory (where agent.yaml lives) */
-    agentDir: string;
-    /** Parsed agent manifest (must have `composes` field) */
-    manifest: AgentManifest;
-    /**
-     * Project root — reserved for Phase 2 workspace config resolution.
-     * In Phase 1 this is unused but accepted so the call site doesn't
-     * need updating when Library integration lands.
-     */
-    projectDir: string;
-    /** Pre-built repo map for catalog resolution. Empty in Phase 1. */
-    repos?: RepoMap;
-    /** Logger for composition resolution warnings */
-    log?: Logger;
-}
-/**
- * Resolve an agent's `composes:` items into inline blocks and discoverable
- * entries. Called by session-builder.ts during the session creation pipeline.
- *
- * Returns null when the manifest has no `composes:` items.
- *
- * @param opts - Resolution options including agentDir, manifest, and optional repos/log.
- * @returns A {@link ResolvedComposition} or `null` when there are no composition items.
- * @docLink packages/runner/capabilities#resolve-agent-composition
- */
-export declare function resolveAgentComposition(opts: ResolveAgentCompositionOpts): Promise<ResolvedComposition | null>;
+import type { DiscoverableEntry } from "./types.js";
 /**
  * Register discoverable composition entries as Protocol v2 capabilities.
  *
@@ -66,8 +22,14 @@ export declare function resolveAgentComposition(opts: ResolveAgentCompositionOpt
  * that compose many assets.
  *
  * @param registry - The session capability registry to register capabilities onto.
- * @param entries - Discoverable entries from a prior {@link resolveAgentComposition} call.
+ * @param entries - Discoverable entries from a prior {@link resolveAgentInstance} call.
  * @docLink packages/runner/capabilities#register-composition-capabilities
  */
 export declare function registerCompositionCapabilities(registry: CapabilityRegistry, entries: DiscoverableEntry[]): void;
+/**
+ * Try to open the LocalIndex SQLite store if it exists.
+ * Returns a stub when the library DB is missing (user hasn't synced yet)
+ * or when opening fails (e.g. corrupt DB).
+ */
+export declare function openLocalIndexIfAvailable(log?: Logger): Promise<IAssetIndex>;
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/runner/src/composition/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../../runner/src/composition/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,KAAK,aAAa,EAAsC,MAAM,yBAAyB,CAAC;AAEjG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,OAAO,EAAE,KAAK,OAAO,EAAgB,MAAM,sBAAsB,CAAC;AAGlE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGzE,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAMpC;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,2BAA2B,GAChC,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CA0CrC;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,iBAAiB,EAAE,GAC3B,IAAI,CAsBN"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../../runner/src/composition/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAMpD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,iBAAiB,EAAE,GAC3B,IAAI,CAsBN;AAwBD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA6BlF"}

package/dist/runner/src/composition/compile.d.ts

@@ -1,13 +1,18 @@
 /**
  * composition/compile.ts
  *
- * Implements `skaile rebuild <agent>` — re-snapshots all inline-snapshot items,
- * bumps the prompt version, and writes `<agent>/compile_manifest.json`.
+ * Implements `skaile rebuild <agent>` — resolves every `composes:` item through
+ * the content source, captures kind, resolved ref and bytes, bumps the prompt
+ * version and writes `<agent>/compile_manifest.json` (schema 2).
  *
- * The compile manifest records what was resolved and when, so the runner can
- * verify content hasn't drifted without a rebuild.
+ * The compile manifest is what an agent runs from: `inline-snapshot` serves its
+ * bytes and `discoverable` items hand out its bytes on invocation. A later
+ * change to a local file or to the catalog changes nothing until the next
+ * `skaile rebuild`.
  */
 import type { AgentComposeItem } from "@skaile/workspaces/types/manifests";
+import * as z from "zod";
+import { type CompositionContentSource } from "./content-source.js";
 import { type CompileManifest } from "./types.js";
 /**
  * Filename for the agent compile manifest written by `skaile rebuild`.
@@ -15,6 +20,23 @@ import { type CompileManifest } from "./types.js";
  * @docLink packages/runner/capabilities#compile-composition
  */
 export declare const COMPILE_MANIFEST_FILENAME = "compile_manifest.json";
+/** One captured composition item, as stored in `compile_manifest.json` and in run snapshots. */
+export declare const CompileManifestEntrySchema: z.ZodObject<{
+    asset_ref: z.ZodString;
+    kind: z.ZodString;
+    resolved_ref: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+    hash: z.ZodString;
+    binding: z.ZodEnum<{
+        discoverable: "discoverable";
+        "inline-live": "inline-live";
+        "inline-snapshot": "inline-snapshot";
+        delegate: "delegate";
+        run: "run";
+    }>;
+    resolved_at: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
 /**
  * Options for {@link compileComposition}.
  *
@@ -23,18 +45,10 @@ export declare const COMPILE_MANIFEST_FILENAME = "compile_manifest.json";
 export interface CompileOpts {
     /** Path to the agent directory (where agent.yaml and compile_manifest.json live) */
     agentDir: string;
-    /** The agent's composes: items */
+    /** The agent's composes: items (may be empty — an empty composition is valid). */
     items: AgentComposeItem[];
-    /**
-     * Content loader — given an asset ref + kind, returns the content text.
-     * Returns null if the content cannot be loaded.
-     */
-    loadContent: (ref: string, kind: string) => Promise<string | null>;
-    /**
-     * Version extractor — given an asset ref, returns the resolved version string.
-     * Returns null if unknown.
-     */
-    resolveVersion?: (ref: string) => Promise<string | null>;
+    /** Where composition bytes come from. */
+    source: CompositionContentSource;
 }
 /**
  * Result returned by {@link compileComposition}.
@@ -46,29 +60,30 @@ export interface CompileResult {
     manifest: CompileManifest;
     /** Path to the written file */
     manifestPath: string;
-    /** Number of entries that were successfully resolved */
+    /** Number of entries written (every item resolves or the compile throws) */
     resolvedCount: number;
-    /** Warnings for unresolvable items */
-    warnings: string[];
 }
 /**
  * Compile (rebuild) the agent's composition.
  *
- * 1. Reads existing compile_manifest.json (if present) for version continuity
- * 2. Re-resolves ALL items (both snapshot and non-snapshot get recorded)
- * 3. Bumps prompt_version
- * 4. Writes compile_manifest.json
+ * 1. Resolves ALL items through the content source (any unresolvable item throws)
+ * 2. Rejects sub-agent loops (`agent` items that compose their own ancestor)
+ * 3. Bumps prompt_version (continuing a schema-1 file's counter)
+ * 4. Writes compile_manifest.json atomically
  *
- * @param opts - Compile options including agentDir, items, and content loader.
- * @returns A {@link CompileResult} with the written manifest and any warnings.
+ * @param opts - Compile options including agentDir, items and the content source.
+ * @returns A {@link CompileResult} with the written manifest.
+ * @throws {CompositionError} `composition_asset_missing` / `composition_conflict` for an item that cannot be served.
  * @docLink packages/runner/capabilities#compile-composition
  */
 export declare function compileComposition(opts: CompileOpts): Promise<CompileResult>;
 /**
- * Load an existing compile_manifest.json, or return undefined if not found.
+ * Load an existing compile_manifest.json.
  *
  * @param manifestPath - Absolute path to the manifest file.
- * @returns The parsed {@link CompileManifest} or `undefined` when missing or malformed.
+ * @returns The parsed {@link CompileManifest}, or `undefined` when the file does not exist.
+ * @throws {CompositionError} `composition_rebuild_required` for a schema-1 artifact or a malformed
+ *   file; `composition_conflict` when an entry's `hash` no longer matches its `content`.
  * @docLink packages/runner/capabilities#load-compile-manifest
  */
 export declare function loadCompileManifest(manifestPath: string): Promise<CompileManifest | undefined>;
@@ -77,7 +92,8 @@ export declare function loadCompileManifest(manifestPath: string): Promise<Compi
  * `<agentDir>/compile_manifest.json`.
  *
  * @param agentDir - Absolute path to the agent definition directory.
- * @returns The parsed {@link CompileManifest} or `undefined` when missing or malformed.
+ * @returns The parsed {@link CompileManifest} or `undefined` when the file does not exist.
+ * @throws {CompositionError} see {@link loadCompileManifest}.
  * @docLink packages/runner/capabilities#load-compile-manifest-from-dir
  */
 export declare function loadCompileManifestFromDir(agentDir: string): Promise<CompileManifest | undefined>;

package/dist/runner/src/composition/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../../runner/src/composition/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,KAAK,eAAe,EAA6C,MAAM,YAAY,CAAC;AAM7F;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAMjE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B;;;OAGG;IACH,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnE;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAkDlF;AAMD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAWtC;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAEtC"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../../runner/src/composition/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAG3E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAEL,KAAK,wBAAwB,EAE9B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,eAAe,EAA6C,MAAM,YAAY,CAAC;AAM7F;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,gGAAgG;AAChG,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;iBASrC,CAAC;AAoBH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,yCAAyC;IACzC,MAAM,EAAE,wBAAwB,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CA4ClF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA6CtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAEtC"}

package/dist/runner/src/composition/content-source.d.ts

@@ -0,0 +1,94 @@
+/**
+ * composition/content-source.ts
+ *
+ * The one place composition bytes come from. A `composes:` ref resolves, in
+ * order, through
+ *
+ *   1. a local path (`./rules.md`, `/abs/RULES.md`, a directory holding the
+ *      kind's manifest) read straight from disk;
+ *   2. the project lock (`skaile.lock.yaml`): a locked asset is served exactly
+ *      as pinned, from the store cache or the catalog checkout, and its bytes
+ *      are verified against the per-file hashes the lock recorded — the pin
+ *      wins over whatever the catalog holds now;
+ *   3. the catalog: a discovery scan of the local catalog roots (the
+ *      `ai-assets/` tree, source clones). Several distinct matches are an
+ *      error, never a pick.
+ *
+ * Nothing here touches the network. A ref that cannot be served throws a
+ * {@link CompositionError}; an item is never dropped silently.
+ */
+import type { IAssetKindRegistry } from "@skaile/workspaces/plugins";
+/**
+ * One composition asset as the content source served it.
+ *
+ * @docLink packages/runner/capabilities#composition-asset
+ */
+export interface CompositionAsset {
+    /**
+     * Where the bytes came from, in a stable spelling: `kind:@publisher/name#version`
+     * for a locked or catalog asset, `local:<path>` for a file on disk.
+     */
+    canonicalRef: string;
+    /** Asset kind the item was loaded as. */
+    kind: string;
+    /** Resolved version; `null` for a local file (identified by its content hash only). */
+    version: string | null;
+    /** SHA-256 (hex) of `content`. */
+    sha256: string;
+    /** Prompt-injectable text (frontmatter stripped). */
+    content: string;
+    /**
+     * Absolute path of the primary file (or knowledge directory) the content
+     * was read from. Diagnostic and traversal aid; never part of the compile
+     * manifest.
+     */
+    location?: string;
+}
+/**
+ * Loads composition assets. One instance serves one agent directory (relative
+ * refs resolve against it).
+ *
+ * @docLink packages/runner/capabilities#composition-content-source
+ */
+export interface CompositionContentSource {
+    /**
+     * Load the asset a `composes:` ref names.
+     * @throws {CompositionError} `composition_asset_missing` when nothing serves the ref;
+     *   `composition_conflict` when several candidates match or locked bytes drifted.
+     */
+    load(ref: string, kind: string): Promise<CompositionAsset>;
+    /** A source for another agent directory (sub-agent traversal), sharing catalog scans. */
+    scoped(agentDir: string): CompositionContentSource;
+}
+/**
+ * Options for {@link createCompositionContentSource}.
+ *
+ * @docLink packages/runner/capabilities#composition-content-source
+ */
+export interface CompositionContentSourceOpts {
+    /** Agent definition directory — base of relative refs. */
+    agentDir: string;
+    /** Project root — holds `skaile.lock.yaml` and `.skaile/cache/store`. */
+    projectDir: string;
+    /** Kind registry used to recognise a kind's manifest file. Defaults to the built-in providers plus `knowledge`. */
+    registry?: IAssetKindRegistry;
+    /**
+     * Catalog roots to scan. Defaults to the `ai-assets/` tree above the project,
+     * the declared `sources:` clones and the project's source cache.
+     */
+    catalogRoots?: readonly string[];
+}
+/**
+ * Create the content source for one agent directory.
+ *
+ * @param opts - Agent dir, project dir and optional registry / catalog roots.
+ * @returns A {@link CompositionContentSource} that resolves local, lock-pinned and catalog refs.
+ * @docLink packages/runner/capabilities#composition-content-source
+ */
+export declare function createCompositionContentSource(opts: CompositionContentSourceOpts): CompositionContentSource;
+/**
+ * Hash helper shared by the compile writer and the resolver: the hash a
+ * {@link CompositionAsset} / compile entry records for `content`.
+ */
+export declare function hashContent(content: string): string;
+//# sourceMappingURL=content-source.d.ts.map

package/dist/runner/src/composition/content-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-source.d.ts","sourceRoot":"","sources":["../../../../runner/src/composition/content-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAQrE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3D,yFAAyF;IACzF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,wBAAwB,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,mHAAmH;IACnH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAoJD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,4BAA4B,GACjC,wBAAwB,CAS1B;AA+VD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/runner/src/composition/dry-run.d.ts

@@ -0,0 +1,34 @@
+/**
+ * composition/dry-run.ts
+ *
+ * What `skaile run --dry-run` prints for a single-shot agent run: the resolved
+ * composition items (ref, kind, binding, version, hash) and how each one
+ * reaches each supported harness. No model is spawned and no run snapshot is
+ * written.
+ */
+import { type DriverTarget } from "@skaile/workspaces/core";
+import type { ResolvedAgentInstance } from "./resolve-instance.js";
+/** One row of the dry-run report. */
+export interface CompositionDryRunRow {
+    /** `composes[].ref` as written. */
+    ref: string;
+    kind: string;
+    binding: string;
+    /** Resolved version; `null` for a local file. */
+    version: string | null | undefined;
+    /** SHA256 of the composed bytes. */
+    hash: string | undefined;
+    /** Where the bytes came from. */
+    resolvedRef: string | undefined;
+    /** How the item reaches each harness. */
+    support: Record<DriverTarget, string>;
+}
+/**
+ * Describe a resolved agent instance for `--dry-run`.
+ *
+ * @param resolved - The result of {@link resolveAgentInstance}; its manifest carries the effective `composes` (convention items first).
+ * @returns One row per effective composition item, in order.
+ * @docLink packages/runner/capabilities#composition-dry-run
+ */
+export declare function describeComposition(resolved: ResolvedAgentInstance): CompositionDryRunRow[];
+//# sourceMappingURL=dry-run.d.ts.map

package/dist/runner/src/composition/dry-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../../../../runner/src/composition/dry-run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAGnE,qCAAqC;AACrC,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,oCAAoC;IACpC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,iCAAiC;IACjC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,oBAAoB,EAAE,CAmB3F"}