@skaile/workspaces 0.8.5

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

@@ -0,0 +1,212 @@
+import type { Capability, CapabilityOrigin, Logger } from "@skaile/workspaces/types";
+import type { DefinedCapability, HandlerContext } from "./define-capability.js";
+/**
+ * Function shape for the platform-bound capability invoker.
+ *
+ * The runner uses this to dispatch `host.*` capability invocations (e.g.
+ * `host.refresh_credential`, `host.audit`, `host.notify_user`) over the
+ * transport and await the matching `CapabilityResultCommand`. Implementations
+ * own the wire serialization and the per-call pending map.
+ *
+ * The result value is the capability's domain payload (already
+ * deserialised; for `host.refresh_credential` this is a `CredentialMint`).
+ * Capability-dispatch infrastructure failures (timeout, schema validation,
+ * transport disconnect) are thrown as `Error` so callers can distinguish
+ * them from domain failures encoded in the payload.
+ *
+ * @category Runtime
+ * @since 3.0.0
+ * @docLink packages/runner/capabilities#remote-invoker
+ */
+export type RemoteCapabilityInvoker = (name: string, input: unknown) => Promise<unknown>;
+/**
+ * Minimal LLM tool descriptor consumed by bridge drivers. Drivers translate
+ * this into the provider-specific tool spec (Claude tool definition, OpenAI
+ * function spec, etc.) at registration time.
+ *
+ * Only the fields needed for tool registration are surfaced here; runtime
+ * dispatch flows through {@link CapabilityRegistry.invoke}.
+ *
+ * @category Runtime
+ * @since 2.0.0
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export type LLMTool = {
+    /** Capability name; used as the LLM-visible tool name. */
+    name: string;
+    /** Human/LLM-readable description. */
+    description: string;
+    /** JSON Schema for the tool's input parameters. */
+    parameters: Record<string, unknown>;
+};
+/**
+ * Filter shape accepted by {@link CapabilityRegistry.list}. All fields are
+ * optional and match exactly when present.
+ *
+ * @category Runtime
+ * @since 2.0.0
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export type CapabilityListFilter = {
+    side?: "client" | "agent";
+    origin?: CapabilityOrigin["kind"];
+    scope?: "session" | "turn";
+};
+/**
+ * Side-tag declaring who is registering a capability. The registry uses
+ * this to enforce origin trust — a client cannot register an `agent`-side
+ * origin, and the agent cannot register `client` / external-origin
+ * capabilities.
+ *
+ * @category Runtime
+ * @since 2.0.0
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export type RegisterSource = "client" | "agent";
+/**
+ * Per-session registry of capabilities. Construct one per
+ * `startAgentServer` invocation; the runner threads it through serve mode's
+ * command handlers and the bridge.
+ *
+ * @category Runtime
+ * @since 2.0.0
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export declare class CapabilityRegistry {
+    private readonly byName;
+    private readonly logger;
+    private remoteInvoker?;
+    constructor(logger?: Logger);
+    /**
+     * Install the platform-bound invoker used by {@link invokeRemote}.
+     *
+     * The runner wires this up after the transport is connected and the
+     * per-session pending-call map is in place. Idempotent — repeated calls
+     * replace the prior invoker.
+     *
+     * @category Runtime
+     * @since 3.0.0
+     */
+    setRemoteInvoker(invoker: RemoteCapabilityInvoker | undefined): void;
+    /**
+     * Invoke a `host.*` (or other peer-side) capability on the platform.
+     *
+     * Composes a `capability_invoked` event under the hood and resolves with
+     * the matching `capability_result` payload. Infrastructure failures
+     * (timeout, schema mismatch, transport disconnect) reject with `Error`;
+     * domain failures (e.g. `{ ok: false, code }` for credential mints) ride
+     * in the resolved payload.
+     *
+     * @category Runtime
+     * @since 3.0.0
+     */
+    invokeRemote(name: string, input: unknown): Promise<unknown>;
+    /**
+     * Register a capability. Validates that the registering `source` is
+     * permitted to declare the capability's `origin.kind`; mismatches are
+     * dropped with a warning so untrusted callers cannot impersonate other
+     * registration sources.
+     *
+     * Allowed combinations:
+     * - source `'agent'`: origins `framework | agent | flow | skill | mcp | connector | mount`
+     * - source `'client'`: origin `client` only
+     *
+     * @param cap - capability to register (typically built via {@link defineCapability})
+     * @param source - which side is doing the registration
+     */
+    register(cap: DefinedCapability, source: RegisterSource): void;
+    /**
+     * Remove a capability by name. No-op when the name is unknown.
+     *
+     * @param name - capability name
+     */
+    deregister(name: string): void;
+    /**
+     * List capabilities, optionally filtering by `side`, `origin` kind, or
+     * `scope`. Returns the wire-format {@link Capability} shape (no internal
+     * Zod schemas or handlers).
+     */
+    list(filter?: CapabilityListFilter): Capability[];
+    /**
+     * Resolve a capability by name. Returns the full {@link DefinedCapability}
+     * (including the original Zod schemas + handler) for use by the bridge.
+     *
+     * @returns the capability or `null` when the name is not registered
+     */
+    resolve(name: string): DefinedCapability | null;
+    /**
+     * Build LLM tool descriptors for every registered capability whose
+     * audience includes `'llm'` (the default when {@link Capability.audience}
+     * is omitted). Bridge drivers consume this output directly when
+     * assembling the tool list passed to the underlying LLM SDK.
+     *
+     * Capabilities scoped to `'runtime'` only (e.g. `host.refresh_credential`,
+     * `runner.add_mount`) are filtered out so they never reach the model.
+     */
+    composeLLMTools(): LLMTool[];
+    /**
+     * Compose a deterministic prompt section from every registered
+     * capability whose audience includes `'llm'`. Ordering matches
+     * `ORIGIN_PROMPT_ORDER` (framework first, then client, then agent-side
+     * surfaces) so the agent sees a stable layout. Capabilities without a
+     * `promptFragment` are skipped.
+     */
+    composePromptSection(): string;
+    /**
+     * Serialize the registry to wire-format capabilities for hibernation. The
+     * runtime fields (`inputZod`, `outputZod`, `handler`) are dropped; only
+     * the wire shape is kept.
+     */
+    serialize(): Capability[];
+    /**
+     * Replay a wire snapshot taken via {@link serialize}. Wire-only capabilities
+     * (no handler) are stored so {@link list} / {@link composeLLMTools} return
+     * a complete picture; agent-side surfaces are expected to re-register
+     * fully (with handlers) from their original sources on wake.
+     *
+     * Per the v2 design, only `client`-side capabilities are persisted across
+     * hibernation by this method — agent-side ones come back via the
+     * skill / flow / connector / mount adapters. Snapshot entries from other
+     * origins are skipped on hydrate.
+     */
+    hydrate(snapshot: Capability[]): void;
+    /**
+     * Invoke a registered capability. Validates the input against the Zod
+     * schema, builds the per-handler logger, and runs the handler. Logs
+     * `info "invoking"` and `info "ok"` (or `error "failed"`) under the
+     * `capability:<origin>:<name>` slice for every call.
+     *
+     * @throws when the capability is unknown or the input fails validation
+     */
+    invoke(name: string, input: unknown, baseCtx: Omit<HandlerContext, "log">): Promise<unknown>;
+    /** True when `source` is allowed to register the given `origin`. */
+    private isOriginAllowed;
+    /** Strip the runtime-only fields from a {@link DefinedCapability}. */
+    private toWire;
+}
+/**
+ * Compute a deterministic signature over a registry's wire-format
+ * capabilities. Used by the session-resume cascade (tier-1 native SDK
+ * resume) to detect toolset drift between hibernate and wake.
+ *
+ * The signature hashes a canonicalized projection of each capability:
+ * `name + origin.kind + sha256(inputSchema)`. Capabilities are sorted
+ * by `name` so registration order does not affect the result.
+ *
+ * Excluded from the hash:
+ * - `displayName` and `userInvokable` — UI metadata only; do not affect
+ *   what the LLM can call.
+ * - `description` and `outputSchema` — text/shape changes that don't
+ *   alter the call surface.
+ *
+ * Spec: `_devlog/specs/2026-05-05-session-resume-restart-design.md`
+ * § "Capability signature".
+ *
+ * @param caps - Wire-format capabilities from {@link CapabilityRegistry.list}.
+ * @returns A hex SHA-256 string that uniquely identifies the toolset.
+ * @category Resume
+ * @since 3.2.0
+ * @docLink packages/runner/capabilities#compute-capability-signature
+ */
+export declare function computeCapabilitySignature(caps: readonly Capability[]): string;
+//# sourceMappingURL=capability-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../../runner/src/capability-registry.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,UAAU,EAEV,gBAAgB,EAChB,MAAM,EACP,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAiBhF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEzF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAahD;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,aAAa,CAAC,CAA0B;gBAEpC,MAAM,CAAC,EAAE,MAAM;IAI3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,SAAS,GAAG,IAAI;IAIpE;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAUlE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI;IAiB9D;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM9B;;;;OAIG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,UAAU,EAAE;IAajD;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAI/C;;;;;;;;OAQG;IACH,eAAe,IAAI,OAAO,EAAE;IAU5B;;;;;;OAMG;IACH,oBAAoB,IAAI,MAAM;IAoB9B;;;;OAIG;IACH,SAAS,IAAI,UAAU,EAAE;IAIzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI;IAcrC;;;;;;;OAOG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,GACnC,OAAO,CAAC,OAAO,CAAC;IAsBnB,oEAAoE;IACpE,OAAO,CAAC,eAAe;IAQvB,sEAAsE;IACtE,OAAO,CAAC,MAAM;CAmBf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAU9E"}

package/dist/runner/src/capability-roundtrip.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Client-side capability round-trip helpers.
+ *
+ * When the LLM invokes a `side: 'client'` capability, the runner does NOT
+ * execute the handler in-process. Instead it:
+ *
+ *  1. Generates a `callId`.
+ *  2. Emits a {@link CapabilityInvokedEvent} over the transport.
+ *  3. Registers a pending promise keyed by `callId`.
+ *  4. Awaits a {@link CapabilityResultCommand} from the platform; resolves
+ *     with `result` or rejects with `result.error`.
+ *
+ * `fireAndForget` short-circuits step 3 — the handler resolves with `{}`
+ * immediately after emitting the invoke event. The bridge-level dispatch
+ * also short-circuits before calling `hooks.invoke()`, so this is a
+ * defence-in-depth guard.
+ *
+ * The helpers below are extracted for unit testing; the actual wiring
+ * lives in `serve.ts` where the transport / pending map are owned.
+ *
+ * @category Capabilities
+ * @since 2.0.0
+ */
+import type { AgentEvent, Capability, CapabilityResultCommand } from "@skaile/workspaces/types";
+/**
+ * Registry of in-flight capability calls. The serve loop owns the map; this
+ * type is exported so tests can pass a real `Map` instance and assert the
+ * pending state across the round-trip.
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export type PendingCallEntry = {
+    resolve: (value: unknown) => void;
+    reject: (err: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+};
+/**
+ * Default timeout (60s) for waiting on a capability result from the platform.
+ * Mirrors the value used in `serve.ts`.
+ *
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export declare const DEFAULT_CAPABILITY_CALL_TIMEOUT_MS = 60000;
+/**
+ * Build the runner-side handler for a wire-format client capability. The
+ * returned function emits `capability_invoked` and waits for a matching
+ * `capability_result` command via the supplied pending-calls map.
+ *
+ * Decoupled from `serve.ts` so it can be exercised in isolation without
+ * spinning up `startAgentServer`.
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export declare function buildClientCapabilityHandler(args: {
+    wire: Capability;
+    pending: Map<string, PendingCallEntry>;
+    emit: (event: AgentEvent) => void;
+    timeoutMs?: number;
+    /** Override the callId factory for deterministic tests. */
+    generateCallId?: () => string;
+}): (input: unknown) => Promise<unknown>;
+/**
+ * Resolve / reject a pending capability call based on a `capability_result`
+ * command from the platform. Returns `true` when the callId matched a
+ * pending entry, `false` otherwise (for telemetry / debug logging).
+ * @docLink packages/runner/capabilities#registry-surface
+ */
+export declare function resolveCapabilityResult(pending: Map<string, PendingCallEntry>, cmd: CapabilityResultCommand): boolean;
+/**
+ * Reject a pending capability call when the platform sends a
+ * `capability_approve` with `decision: 'rejected'`. Used by capabilities
+ * declared `requiresApproval: true` — the platform shows a confirm UI on
+ * `capability_invoked`; on user denial it forwards the rejection back to the
+ * runner via this command instead of dispatching the handler.
+ *
+ * Returns `true` when the callId matched a pending entry, `false` otherwise
+ * (e.g. the call was already resolved via `capability_result`).
+ *
+ * Approvals (`decision: 'approved'`) are no-ops at this level — the platform
+ * still drives dispatch and replies via `capability_result`. This function
+ * only handles the rejection short-circuit.
+ *
+ * @param pending - Map of in-flight capability calls keyed by `callId`.
+ * @param callId - ID of the call being denied.
+ * @param feedback - Optional user-facing feedback message passed to the rejection error.
+ * @returns `true` when the call was found and rejected; `false` when already resolved.
+ * @category Capabilities
+ * @since 2.1.0
+ * @docLink packages/runner/capabilities#reject-capability-on-approval-deny
+ */
+export declare function rejectCapabilityOnApprovalDeny(pending: Map<string, PendingCallEntry>, callId: string, feedback?: string): boolean;
+//# sourceMappingURL=capability-roundtrip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability-roundtrip.d.ts","sourceRoot":"","sources":["../../../runner/src/capability-roundtrip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEhG;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,QAAS,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACvC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAkCvC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,GAAG,EAAE,uBAAuB,GAC3B,OAAO,CAYT;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAOT"}

package/dist/runner/src/compaction/index.d.ts

@@ -0,0 +1,6 @@
+export { TokenThresholdStrategy } from "./strategy.js";
+export type { CompactionContext, CompactionStrategy } from "./strategy.js";
+export { buildCompactionPrompt } from "./prompt.js";
+export { CompactionOrchestrator } from "./orchestrator.js";
+export type { CompactionOrchestratorOptions } from "./orchestrator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runner/src/compaction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../runner/src/compaction/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/runner/src/compaction/orchestrator.d.ts

@@ -0,0 +1,99 @@
+import type { AgentDriver } from "@skaile/workspaces/bridge";
+import type { CompactionConfig } from "@skaile/workspaces/core";
+import type { CompactionAttemptEvent, CompactionTrigger, SnapshotEvent } from "@skaile/workspaces/types";
+/**
+ * Detect whether the captured response from a compaction `prompt()` call is
+ * actually a rate-limit error message returned as text (instead of as a
+ * thrown error). Persisting such a "summary" would corrupt context
+ * restoration on the next wake — the snapshot prompt would inject the error
+ * text as if it were the conversation summary.
+ *
+ * Conservative: requires both a strong signal phrase AND a short response.
+ * Real summaries are routinely 2k+ chars; rate-limit relays are short.
+ *
+ * Issue: I-29.
+ */
+export declare function detectRateLimitInSummary(text: string): boolean;
+/**
+ * Validation of a compaction output's structural shape, run BEFORE we persist
+ * it as a `success`. Cheap synchronous checks only — no LLM calls.
+ *
+ * Failed validation does NOT throw; it returns a structured verdict so the
+ * orchestrator can record a `failed` Compaction row with the right errorCode.
+ *
+ * @param text         The captured summary text from the driver.
+ * @param tokensBefore Estimated input token count (from `driver.getTokenUsage()` before the call).
+ * @param tokensAfter  Output token count of the summary (from driver or chars/4 heuristic).
+ * @returns `{ ok: true }` on pass, otherwise `{ ok: false, errorCode }` with one of:
+ *          `"empty"` | `"too_short"` | `"poor_ratio"` | `"rate_limit"`.
+ *
+ * Spec: `_devlog/specs/2026-05-05-session-resume-restart-design.md` § Validation at write time.
+ * @docLink packages/runner/capabilities#validate-compaction-output
+ */
+export declare function validateCompactionOutput(text: string, tokensBefore: number, tokensAfter: number): {
+    ok: true;
+} | {
+    ok: false;
+    errorCode: string;
+};
+/**
+ * Options for the {@link CompactionOrchestrator}.
+ *
+ * @docLink packages/runner/dev-guide#compaction
+ */
+export interface CompactionOrchestratorOptions {
+    driver: AgentDriver;
+    config?: CompactionConfig;
+    skillDirectives?: string[];
+    mcpDirectives?: string[];
+    agentCompactionPrompt?: string;
+    onCompactionStart?: (trigger: CompactionTrigger) => void;
+    onSnapshot?: (snapshot: SnapshotEvent) => void;
+    /**
+     * Emitted on EVERY compaction attempt, success or failure. Phase 1 sink for
+     * the new `Compaction` table observability surface; the host's serve.ts wires
+     * this to forward events on the agent transport.
+     */
+    onCompactionAttempt?: (event: CompactionAttemptEvent) => void;
+    onCompactionEnd?: () => void;
+    onLog?: (line: string) => void;
+    /**
+     * Phase 3 (resume cascade): supplies the current capability registry
+     * signature at compaction time so it lands on the
+     * {@link CompactionAttemptEvent}. The wake selector compares this against
+     * the runner's current signature to decide tier-1 native SDK resume
+     * eligibility.
+     *
+     * Returns `null` when the host cannot compute a signature (legacy boot
+     * path, registry not yet bootstrapped); the orchestrator records `null`
+     * in that case and the resulting compaction is tier-1 ineligible.
+     */
+    getCurrentCapabilitySignature?: () => string | null;
+}
+/**
+ * Orchestrates context window compaction for a running agent session.
+ *
+ * Monitors token usage against the configured thresholds and triggers
+ * compaction via snapshots when the strategy fires.
+ *
+ * @docLink packages/runner/dev-guide#compaction
+ */
+export declare class CompactionOrchestrator {
+    private readonly driver;
+    private readonly strategy;
+    private readonly config;
+    private readonly opts;
+    private _isCompacting;
+    private lastCompactionSeq;
+    private lastCompactionTime;
+    private currentSeq;
+    private messagesSinceCompaction;
+    constructor(opts: CompactionOrchestratorOptions);
+    get hasNewMessagesSinceCompaction(): boolean;
+    trackMessage(seq: number): void;
+    shouldCompact(): boolean;
+    compact(trigger: CompactionTrigger, focus?: string): Promise<SnapshotEvent | null>;
+    private _doCompact;
+    initFromSnapshot(lastSnapshotSeq: number, lastSnapshotTime: number): void;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/runner/src/compaction/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../../runner/src/compaction/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACd,MAAM,0BAA0B,CAAC;AA0ClC;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAQjD;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACzD,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAC9D,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B;;;;;;;;;;OAUG;IACH,6BAA6B,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACrD;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IAErD,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAuB;IAChD,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,uBAAuB,CAAK;gBAExB,IAAI,EAAE,6BAA6B;IAU/C,IAAI,6BAA6B,IAAI,OAAO,CAE3C;IAED,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK/B,aAAa,IAAI,OAAO;IAgBlB,OAAO,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAU1E,UAAU;IAoMxB,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;CAK1E"}

package/dist/runner/src/compaction/prompt.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Assemble the final compaction prompt from layered sources.
+ *
+ * Resolution order:
+ *   base = agentPrompt ?? DEFAULT_COMPACTION_PROMPT
+ *   final = base + skillDirectives + focus
+ * @docLink packages/runner/dev-guide#compaction
+ */
+export declare function buildCompactionPrompt(opts: {
+    agentPrompt?: string;
+    skillDirectives?: string[];
+    mcpDirectives?: string[];
+    focus?: string;
+}): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/runner/src/compaction/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../../runner/src/compaction/prompt.ts"],"names":[],"mappings":"AAyDA;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAiBT"}

package/dist/runner/src/compaction/strategy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Runtime context data supplied to a {@link CompactionStrategy}
+ * when deciding whether to compact the context window.
+ *
+ * @docLink packages/runner/dev-guide#compaction
+ */
+export interface CompactionContext {
+    estimatedTokens: number;
+    contextWindow: number;
+    messageCount: number;
+    lastCompactionSeq: number | null;
+    timeSinceLastCompaction: number | null;
+}
+/**
+ * Strategy for deciding when the context window should be compacted.
+ *
+ * Implementations receive the current {@link CompactionContext} and
+ * return true when compaction should proceed.
+ *
+ * @docLink packages/runner/dev-guide#compaction
+ */
+export interface CompactionStrategy {
+    shouldCompact(context: CompactionContext): boolean;
+}
+/**
+ * Compaction strategy that triggers when estimated token usage
+ * exceeds a percentage of the context window. A cooldown period
+ * prevents thrashing.
+ *
+ * @docLink packages/runner/dev-guide#compaction
+ */
+export declare class TokenThresholdStrategy implements CompactionStrategy {
+    private readonly thresholdPercent;
+    private readonly minCooldownMs;
+    constructor(opts: {
+        thresholdPercent: number;
+        minCooldownMs: number;
+    });
+    shouldCompact(context: CompactionContext): boolean;
+}
+//# sourceMappingURL=strategy.d.ts.map

package/dist/runner/src/compaction/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../../../runner/src/compaction/strategy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;CACpD;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,IAAI,EAAE;QAAE,gBAAgB,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;IAKrE,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO;CAcnD"}

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

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+import type { AgentManifest } from "@skaile/workspaces/core";
+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>;
+/**
+ * Register discoverable composition entries as Protocol v2 capabilities.
+ *
+ * Each discoverable entry becomes a tool the LLM can invoke to "activate"
+ * that asset. When invoked, the handler returns the asset's full content
+ * (e.g. a SKILL.md body for skills, connection instructions for connectors).
+ *
+ * The LLM sees a lean tool list (name + description only) and loads full
+ * content on demand — this keeps the context window efficient for agents
+ * that compose many assets.
+ *
+ * @param registry - The session capability registry to register capabilities onto.
+ * @param entries - Discoverable entries from a prior {@link resolveAgentComposition} call.
+ * @docLink packages/runner/capabilities#register-composition-capabilities
+ */
+export declare function registerCompositionCapabilities(registry: CapabilityRegistry, entries: DiscoverableEntry[]): void;
+//# sourceMappingURL=bootstrap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../../runner/src/composition/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,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"}

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

@@ -0,0 +1,84 @@
+/**
+ * composition/compile.ts
+ *
+ * Implements `skaile rebuild <agent>` — re-snapshots all inline-snapshot items,
+ * bumps the prompt version, and writes `<agent>/compile_manifest.json`.
+ *
+ * The compile manifest records what was resolved and when, so the runner can
+ * verify content hasn't drifted without a rebuild.
+ */
+import type { AgentComposeItem } from "@skaile/workspaces/types/manifests";
+import { type CompileManifest } from "./types.js";
+/**
+ * Filename for the agent compile manifest written by `skaile rebuild`.
+ *
+ * @docLink packages/runner/capabilities#compile-composition
+ */
+export declare const COMPILE_MANIFEST_FILENAME = "compile_manifest.json";
+/**
+ * Options for {@link compileComposition}.
+ *
+ * @docLink packages/runner/capabilities#compile-composition
+ */
+export interface CompileOpts {
+    /** Path to the agent directory (where agent.yaml and compile_manifest.json live) */
+    agentDir: string;
+    /** The agent's composes: items */
+    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>;
+}
+/**
+ * Result returned by {@link compileComposition}.
+ *
+ * @docLink packages/runner/capabilities#compile-composition
+ */
+export interface CompileResult {
+    /** The written compile manifest */
+    manifest: CompileManifest;
+    /** Path to the written file */
+    manifestPath: string;
+    /** Number of entries that were successfully resolved */
+    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
+ *
+ * @param opts - Compile options including agentDir, items, and content loader.
+ * @returns A {@link CompileResult} with the written manifest and any warnings.
+ * @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.
+ *
+ * @param manifestPath - Absolute path to the manifest file.
+ * @returns The parsed {@link CompileManifest} or `undefined` when missing or malformed.
+ * @docLink packages/runner/capabilities#load-compile-manifest
+ */
+export declare function loadCompileManifest(manifestPath: string): Promise<CompileManifest | undefined>;
+/**
+ * Load compile manifest from an agent directory, reading the file from
+ * `<agentDir>/compile_manifest.json`.
+ *
+ * @param agentDir - Absolute path to the agent definition directory.
+ * @returns The parsed {@link CompileManifest} or `undefined` when missing or malformed.
+ * @docLink packages/runner/capabilities#load-compile-manifest-from-dir
+ */
+export declare function loadCompileManifestFromDir(agentDir: string): Promise<CompileManifest | undefined>;
+//# sourceMappingURL=compile.d.ts.map

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

@@ -0,0 +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,EAAkB,KAAK,eAAe,EAA6B,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"}