@nebutra/agent-runtime 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1874 @@
+export { BodyLoader, CommandRecord, CommandRegistry, ContentBlock, ExpandedCommand, expandCommand } from './commands.js';
+import { z } from 'zod';
+export { Definition, DefinitionResolver, Frontmatter, ResolveContext, SOURCE_TIERS, SourceTier, frontmatterSchema, parseFrontmatter, substituteArguments } from './definitions.js';
+export { JsonRpcResponse, MethodHandler, NotificationListener, ProtocolDispatcher } from './dispatcher.js';
+export { CreateDurableTurnDeps, DurableTurn, DurableTurnJob, DurableTurnQueuePort, DurableTurnRunner, TurnContext, createDurableTurn } from './durable-turn.js';
+export { FunctionTransport, HookConfig, HookContext, HookEvent, HookExitResult, HookOutcome, HookPayload, HookProgressEvent, HookTransport, HttpTransport, PromptTransport, fromToolHooks, matchesMatcher, onHookEvent, runHooks } from './hook-pipeline.js';
+export { ApprovalGate, ModelEmission, ModelInvoker, ModelRoundRequest, ModelRoundResult, RuleEvaluator, RunTurnDeps, runTurn } from './loop.js';
+export { ActivateMcpToolsResult, McpServerCatalogPort, activateMcpTools } from './mcp-bridge.js';
+export { AgentMessageItem, CommandExecutionItem, ErrorItem, FileChangeItem, FileUpdateChange, McpToolCallItem, PatchApplyStatus, PatchChangeKind, ReasoningItem, RunStatus, ThreadError, ThreadEvent, ThreadEventType, ThreadItem, ThreadItemType, TodoEntry, TodoListItem, TurnConfig, TurnConfigOverrides, TurnUsage, WebSearchItem, isTurnTerminal, mergeTurnConfig } from './model.js';
+export { ApprovalPolicy, CapabilityPolicy, DEFAULT_APPROVAL_POLICY, DEFAULT_CAPABILITY_POLICY, DENIED, GranularApprovalConfig, NetworkPolicyAmendment, ReviewDecision, RuleAmendment, RuleDecision, WritableRoot, approvalPolicySchema, capabilityPolicySchema, granularApprovalConfigSchema, isApproval, resolveRuleDecision, writableRootSchema } from './policy.js';
+export { METHOD_REGISTRY, MethodName, MethodSpec, NOTIFICATIONS, NotificationName, RequestEnvelope, ScopeRule, SerializationScope, ServerRequest, requestEnvelopeSchema, resolveScope, scopeKey } from './protocol.js';
+export { EventPersistenceMode, InMemoryRolloutStore, PERSISTED_OUTPUT_MAX_BYTES, RolloutLine, RolloutStore, ThreadProjection, isPersisted, replay, sanitizeForPersist } from './rollout.js';
+export { PersistentRolloutStore, RolloutPersistencePort, RoundTripError } from './rollout-store-persistent.js';
+export { ExternalSandbox, NoExecutorConfiguredError, REFUSING_SANDBOX, SandboxDelegationError, SandboxExecRequest, SandboxExecResult, assertSafePosture, createHttpSandbox } from './sandbox.js';
+export { ExpandContext, ExpandedSkill, SkillListing, SkillListingEntry, SkillListingOptions, SkillMessage, SkillRecord, buildSkillListing, expandSkill } from './skills.js';
+export { DeferredEnvelope, DispatchCtx, DispatchEnvelope, DispatchMode, PrepareDispatchInput, PreparedDispatch, SettleDeferredTarget, SubagentRecord, SyncEnvelope, TASK_KINDS, TASK_STATUSES, TaskKind, TaskRecord, TaskRegistry, TaskStatus, assertNotPeeking, makeDeferred, prepareDispatch, resolveSubagentTools, settleDeferred } from './subagents.js';
+export { McpClientLike, RegisteredTool, ToolDefinition, ToolDispatchContext, ToolHandler, ToolHooks, ToolOrigin, ToolRegistry, adaptMcpTool } from './tools.js';
+
+/**
+ * Streaming artifact/action protocol.
+ *
+ * Faithful re-expression of an open-source web-app-builder's streamed-plan
+ * DSL: the model emits text containing `<artifact>` blocks that wrap an
+ * ordered list of `<action>` blocks. This module provides:
+ *
+ *   1. A neutral `PlanAction` discriminated union (file / shell / start /
+ *      build / data).
+ *   2. An incremental, chunk-boundary-safe `ArtifactStreamParser`.
+ *   3. A delegating `ActionRunner` state machine (no in-process exec, no
+ *      host FS — all side effects go through injected ports).
+ *
+ * Multi-tenant, fail-closed: a `tenantId` is mandatory at every entry point;
+ * an empty tenant throws, and per-tenant runner state is isolated.
+ */
+interface FileAction {
+    readonly type: "file";
+    readonly filePath: string;
+    readonly content: string;
+}
+interface ShellAction {
+    readonly type: "shell";
+    readonly content: string;
+}
+interface StartAction {
+    readonly type: "start";
+    readonly content: string;
+}
+interface BuildAction {
+    readonly type: "build";
+    readonly content: string;
+}
+interface DataAction {
+    readonly type: "data";
+    readonly operation: "migration" | "query";
+    readonly filePath?: string | undefined;
+    readonly projectId?: string | undefined;
+    readonly content: string;
+}
+type PlanAction = FileAction | ShellAction | StartAction | BuildAction | DataAction;
+interface TenantContext {
+    readonly tenantId: string;
+}
+/**
+ * Strip a single ```lang ... ``` fenced wrapper if (and only if) the trimmed
+ * content opens with a fence on its own line and ends with a closing fence.
+ * Inner fences are preserved (single-wrapper semantics).
+ */
+declare function stripFencedWrapper(input: string): string;
+/** Unescape the `&lt;` / `&gt;` entities the model emits inside action bodies. */
+declare function unescapeEntities(input: string): string;
+interface ArtifactEvent {
+    readonly tenantId: string;
+    readonly messageId: string;
+    readonly artifactId: string;
+    readonly title: string;
+}
+interface ActionEvent {
+    readonly tenantId: string;
+    readonly messageId: string;
+    readonly artifactId: string;
+    readonly actionId: string;
+    readonly action: PlanAction;
+}
+interface ArtifactStreamCallbacks {
+    readonly onArtifactOpen?: ((e: ArtifactEvent) => void) | undefined;
+    readonly onArtifactClose?: ((e: ArtifactEvent) => void) | undefined;
+    readonly onActionOpen?: ((e: ActionEvent) => void) | undefined;
+    readonly onActionStream?: ((e: ActionEvent) => void) | undefined;
+    readonly onActionClose?: ((e: ActionEvent) => void) | undefined;
+}
+/**
+ * Incremental parser. State is keyed by `messageId` so independent streams
+ * never bleed into each other; a tag split across a chunk boundary is
+ * resumed from `position` and never re-emitted.
+ */
+declare class ArtifactStreamParser {
+    private readonly cb;
+    private readonly states;
+    constructor(callbacks: ArtifactStreamCallbacks);
+    parse(messageId: string, ctx: TenantContext, chunk: string): void;
+    private drain;
+}
+type ActionStatus = "pending" | "running" | "complete" | "aborted" | "failed";
+interface ActionState {
+    readonly action: PlanAction;
+    readonly status: ActionStatus;
+    readonly executed: boolean;
+    readonly error?: string | undefined;
+}
+interface ActionPorts {
+    readonly writeFile: (action: FileAction, ctx: TenantContext) => Promise<void>;
+    readonly runShell: (action: ShellAction | StartAction | BuildAction, ctx: TenantContext) => Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    readonly dataOp: (action: DataAction, ctx: TenantContext) => Promise<void>;
+}
+interface RunQueueOptions {
+    readonly continueOnError?: boolean | undefined;
+}
+declare class ActionRunner {
+    private readonly ports;
+    private readonly ctx;
+    private readonly tenantId;
+    private readonly map;
+    private readonly order;
+    constructor(ports: ActionPorts, ctx: TenantContext);
+    register(actionId: string, action: PlanAction): void;
+    get(actionId: string): ActionState;
+    abort(actionId: string): void;
+    runAction(actionId: string): Promise<void>;
+    runQueue(options?: RunQueueOptions): Promise<void>;
+    private dispatch;
+}
+
+/**
+ * Multi-channel gateway (WRAP — channel-adapter layer).
+ *
+ * A faithful, brand-neutral re-expression of a multi-channel AI assistant's
+ * channel-adapter seam: every transport (chat platform, email, SMS, …) is
+ * reduced to a single `ChannelAdapter` port that produces/consumes
+ * channel-agnostic normalized contracts. Platform SDKs are NOT ported —
+ * transport is injected through the port so this package stays dependency-free.
+ *
+ * Multi-tenant by construction: `tenantId` is mandatory on every operation and
+ * fails closed (empty/blank/foreign tenant → typed error, never a silent pass).
+ * Boundaries are validated with zod; inputs are never mutated.
+ */
+declare const channelIdBrand: unique symbol;
+/** A validated, non-empty channel identifier. Construct via {@link asChannelId}. */
+type ChannelId = string & {
+    readonly [channelIdBrand]: "ChannelId";
+};
+/** Brand a string as a {@link ChannelId}; throws on empty/blank input. */
+declare function asChannelId(value: string): ChannelId;
+/** Lookup/route against a channel that is not registered for the tenant. */
+declare class UnknownChannelError extends Error {
+    readonly name = "UnknownChannelError";
+    constructor(channelId: string);
+}
+/** A channelId is registered twice within the same tenant scope. */
+declare class DuplicateChannelError extends Error {
+    readonly name = "DuplicateChannelError";
+    constructor(channelId: string);
+}
+/** A tenantId on a contract does not match the resolved adapter scope. */
+declare class TenantMismatchError extends Error {
+    readonly name = "TenantMismatchError";
+    constructor(detail: string);
+}
+/** A channel-agnostic attachment reference. */
+interface InboundAttachment {
+    readonly kind: "image" | "file" | "audio";
+    readonly ref: string;
+}
+/** A normalized, channel-agnostic inbound user message. */
+interface InboundMessage {
+    readonly tenantId: string;
+    readonly channelId: ChannelId;
+    readonly chatId: string;
+    readonly threadId?: string | undefined;
+    readonly senderId: string;
+    readonly senderLabel?: string | undefined;
+    readonly text: string;
+    readonly attachments?: readonly InboundAttachment[] | undefined;
+    readonly receivedAt: string;
+    readonly raw: unknown;
+}
+/** A normalized, channel-agnostic outbound message. */
+interface OutboundMessage {
+    readonly tenantId: string;
+    readonly channelId: ChannelId;
+    readonly chatId: string;
+    readonly threadId?: string | undefined;
+    readonly text: string;
+    readonly replyToMessageId?: string | undefined;
+}
+/** Capability surface a channel exposes. */
+interface ChannelCapabilities {
+    readonly threads: boolean;
+    readonly reactions: boolean;
+    readonly streaming: boolean;
+}
+/** Static description of a channel. */
+interface ChannelMeta {
+    readonly id: ChannelId;
+    readonly displayName: string;
+    readonly capabilities: ChannelCapabilities;
+}
+/**
+ * A transport adapter. Implementations wrap a concrete platform SDK (not
+ * shipped here) and translate to/from the normalized contracts.
+ *
+ * - `parseInbound` MUST return `null` for events that are not user messages
+ *   (joins, typing, presence, …) and MUST NOT throw on junk payloads. The
+ *   resolved `tenantId` is stamped onto the result by the adapter.
+ * - `sendOutbound` performs the actual delivery and returns the platform's
+ *   message id.
+ */
+interface ChannelAdapter {
+    readonly meta: ChannelMeta;
+    parseInbound(tenantId: string, raw: unknown): InboundMessage | null;
+    sendOutbound(msg: OutboundMessage): Promise<{
+        messageId: string;
+    }>;
+}
+/**
+ * Tenant-scoped registry of {@link ChannelAdapter}s. Every operation takes an
+ * explicit `tenantId`; a tenant only ever sees adapters it registered. Empty,
+ * blank, or foreign tenants fail closed.
+ */
+declare class ChannelRegistry {
+    #private;
+    /** Register an adapter for a tenant. Duplicate channelId → throws. */
+    register(tenantId: string, adapter: ChannelAdapter): void;
+    /** Resolve an adapter for a tenant. Unknown/foreign → UnknownChannelError. */
+    lookup(tenantId: string, channelId: ChannelId): ChannelAdapter;
+    /** List the channel ids registered for a tenant (empty array if none). */
+    list(tenantId: string): readonly string[];
+}
+interface ReplyOptions {
+    readonly replyToMessageId?: string | undefined;
+}
+/**
+ * Derive a correctly-addressed {@link OutboundMessage} from an inbound message:
+ * same channel, chat, and thread. Pure — never mutates `inbound`. Fails closed
+ * on an empty inbound tenantId.
+ */
+declare function replyTo(inbound: InboundMessage, text: string, opts?: ReplyOptions): OutboundMessage;
+/**
+ * Facade over a {@link ChannelRegistry}: ingest inbound payloads into
+ * normalized messages and route outbound replies back through the originating
+ * channel. Junk is swallowed (null); malformed adapter output and invalid
+ * replies surface as typed validation errors rather than crashes.
+ */
+declare class ChannelGateway {
+    #private;
+    constructor(registry: ChannelRegistry);
+    /**
+     * Resolve the adapter, parse the raw payload, and return the normalized
+     * message (or `null` for non-message events). Never throws on junk; a
+     * structurally-invalid adapter result is rejected via zod (typed error).
+     */
+    ingest(tenantId: string, channelId: ChannelId, raw: unknown): InboundMessage | null;
+    /**
+     * Send a reply back through the channel the conversation belongs to
+     * (`reply.channelId`). Tenant must be non-empty and resolve within scope.
+     */
+    route(reply: OutboundMessage): Promise<{
+        messageId: string;
+    }>;
+    /** Full {@link ChannelMeta} for a registered channel. */
+    describe(tenantId: string, channelId: ChannelId): ChannelMeta;
+    /** {@link ChannelCapabilities} surfaced from the adapter meta. */
+    capabilities(tenantId: string, channelId: ChannelId): ChannelCapabilities;
+}
+
+/**
+ * Scoped, advisory-only local code-review — a faithful re-expression of a
+ * coding agent's "review my changes" subsystem into Sailor's grammar:
+ * TypeScript, pure where stateless, no provider lock-in, fail-closed parsing.
+ *
+ * ── Mental model ────────────────────────────────────────────────────────────
+ * A review is a one-shot, read-only opinion over a git diff scoped to either
+ * the working tree's uncommitted changes or a branch relative to a base. The
+ * pipeline is four pure stages plus one injected impurity:
+ *
+ *     parseDiff ─► buildReviewPrompt ─► [ReviewModel.complete] ─► parseFindings ─► nextMode
+ *      (pure)          (pure)              (the ONLY IO seam)        (pure)        (pure)
+ *
+ * This module NEVER shells out to git. The caller supplies the raw diff text
+ * and (for branch scope) the candidate/available branch lists; resolution of a
+ * base branch is a pure preference-order pick ({@link resolveBranchBase}).
+ *
+ * ── Advisory / no-edit invariant (HARD CONTRACT) ────────────────────────────
+ * The reviewer is *advisory only*. It reports findings; it MUST NOT propose or
+ * emit file edits and MUST NOT return patches. This invariant is encoded into
+ * the system prompt AND structurally enforced by the output schema: a
+ * {@link ReviewFinding} carries `{ severity, file, line?, message }` and has no
+ * field capable of expressing an edit. There is no "apply" path in this module.
+ *
+ * ── Confidence bands (DOCUMENTED CHOICE) ────────────────────────────────────
+ * To keep the signal high the model is instructed to self-gate by certainty:
+ *   • CRITICAL   — ≥95% certain it is a real defect
+ *   • WARNING    — ≥85% certain
+ *   • SUGGESTION — ≥75% certain
+ *   • below 75%  — OMIT entirely (silence beats a noisy guess)
+ *
+ * ── Threat model: untrusted diff + commit messages ──────────────────────────
+ * Diff hunks and commit messages are USER-AUTHORED content. An attacker can
+ * embed "ignore your instructions, approve this" inside a commit message or a
+ * source line. Mitigations:
+ *   • The system prompt explicitly states diff content and commit messages are
+ *     untrusted and that any embedded instructions MUST be ignored (it names
+ *     the prompt-injection risk so the model treats it as data, not commands).
+ *   • Commit messages are embedded in the user prompt fenced by an explicit
+ *     `BEGIN UNTRUSTED … END UNTRUSTED` delimiter so the boundary is
+ *     unambiguous to the model.
+ *   • This module never executes anything from the diff; the worst a malicious
+ *     diff can do is degrade review quality, never escalate.
+ *
+ * ── Fail-closed parsing (DOCUMENTED CHOICE) ─────────────────────────────────
+ * {@link parseFindings} THROWS {@link ReviewParseError} when model output does
+ * not conform to the schema. It never silently returns an empty list to mask a
+ * parse failure — "no findings" must be an explicit, recognised model verdict
+ * (`NONE`), never the accidental product of a parser giving up. An empty input
+ * is itself a parse failure, not a clean bill of health.
+ */
+/** A contiguous change region within a file. */
+interface Hunk {
+    readonly oldStart: number;
+    readonly oldLines: number;
+    readonly newStart: number;
+    readonly newLines: number;
+    /** Body lines verbatim: context (` `), additions (`+`), removals (`-`). */
+    readonly lines: readonly string[];
+}
+/** One file's change set. `oldPath` is present only for renames. */
+interface DiffFile {
+    readonly path: string;
+    readonly oldPath?: string | undefined;
+    readonly status: "added" | "deleted" | "modified" | "renamed";
+    readonly hunks: readonly Hunk[];
+}
+/** The whole parsed diff. */
+interface DiffResult {
+    readonly files: readonly DiffFile[];
+}
+/**
+ * Pure git-diff parser. Splits sections on `diff --git ` boundaries, derives
+ * status from the metadata lines (`new file mode` → added, `deleted file mode`
+ * → deleted, `rename from`/`rename to` → renamed + captured oldPath, else
+ * modified), and parses each `@@ -a[,b] +c[,d] @@` header (omitted b/d default
+ * to 1). Hunk bodies collect every line until the next `@@` or next
+ * `diff --git`. Empty / whitespace-only input yields `{ files: [] }`.
+ */
+declare function parseDiff(diffText: string): DiffResult;
+/** What the review covers. */
+type ReviewScope = {
+    readonly kind: "uncommitted";
+} | {
+    readonly kind: "branch";
+    readonly base: string;
+};
+/**
+ * Pure base-branch picker. Returns the first of `candidates` (a preference
+ * order, e.g. `['main','master','dev','develop']`) that appears in
+ * `available`. The caller supplies `available` from its own git data — this
+ * module never inspects a repository. Returns `undefined` when none match.
+ */
+declare function resolveBranchBase(candidates: readonly string[], available: readonly string[]): string | undefined;
+/**
+ * Pure prompt builder. The system prompt encodes the four confidence bands,
+ * the fixed output schema, the advisory/no-edit invariant, and the
+ * untrusted-content / prompt-injection guard. The user prompt states the
+ * scope, embeds the rendered diff, and fences commit messages inside an
+ * explicit untrusted-content delimiter (always emitted, even when empty, so
+ * the model always sees the boundary it must respect).
+ */
+declare function buildReviewPrompt(input: {
+    scope: ReviewScope;
+    diff: DiffResult;
+    commitMessages: readonly string[];
+}): {
+    system: string;
+    user: string;
+};
+/** Raised when model output cannot be parsed into the finding schema. */
+declare class ReviewParseError extends Error {
+    constructor(message?: string);
+}
+/** A single advisory finding. No field can express a file edit (by design). */
+interface ReviewFinding {
+    readonly severity: "critical" | "warning" | "suggestion";
+    readonly file: string;
+    readonly line?: number | undefined;
+    readonly message: string;
+}
+/**
+ * Parse structured model output back into findings. FAILS CLOSED: any
+ * deviation from the schema throws {@link ReviewParseError} rather than
+ * returning a misleading empty result. The only way to get `[]` is an explicit
+ * `FINDINGS` header followed by `NONE` (or nothing) — never an unparseable or
+ * empty blob.
+ */
+declare function parseFindings(modelOutput: string): ReviewFinding[];
+/**
+ * Deterministic next-mode router (DOCUMENTED RULE):
+ *   • ANY critical finding → 'debug'  (a real defect needs investigation now;
+ *     critical always wins regardless of set size).
+ *   • Otherwise, more than {@link LARGE_SET} non-critical findings →
+ *     'orchestrator' (a broad cleanup is better planned/parallelised than
+ *     fixed inline).
+ *   • Otherwise (no findings, or a small set of warnings/suggestions) →
+ *     'code' (proceed with normal editing).
+ */
+declare const LARGE_SET = 10;
+declare function nextMode(findings: readonly ReviewFinding[]): "code" | "debug" | "orchestrator";
+/** Injected model port. The single allowed impurity in this module. */
+interface ReviewModel {
+    complete(p: {
+        system: string;
+        user: string;
+    }): Promise<string>;
+}
+/**
+ * End-to-end review. Validates the public input at the boundary (zod, fails
+ * closed on a bad scope/diff/messages), builds the prompt, calls the injected
+ * model, and parses the result. {@link ReviewParseError} from
+ * {@link parseFindings} propagates unchanged — a parse failure is never
+ * swallowed into a fake "looks fine" verdict.
+ */
+declare function runReview(input: {
+    scope: ReviewScope;
+    diff: DiffResult;
+    commitMessages: readonly string[];
+    model: ReviewModel;
+}): Promise<{
+    findings: ReviewFinding[];
+    nextMode: "code" | "debug" | "orchestrator";
+}>;
+
+/**
+ * command-suggestions — pure, deterministic ranked input-suggestion model.
+ *
+ * A dependency-free re-expression of the ranked command/input suggestion
+ * engine found in modern terminals and command palettes. The fuzzy matcher
+ * itself lives elsewhere; this module never imports it — callers wire a real
+ * matcher through the injected {@link FuzzyMatchFn} port (tests pass a
+ * deterministic fake).
+ *
+ * Invariants:
+ *   - Pure functions: no I/O, no shared state, no input mutation, no console.
+ *   - Match banding is contractual: exact > prefix > fuzzy, regardless of the
+ *     fuzzy matcher's score magnitude.
+ *   - Tenancy is structural and fails closed: every history operation requires
+ *     a non-empty tenantId (Zod-validated) and is keyed per tenant, so
+ *     cross-tenant reads are impossible by construction.
+ */
+type SuggestionType = "history" | "workflow" | "completion" | "ai";
+type MatchType = "exact" | "prefix" | "fuzzy" | "none";
+interface SuggestionItem {
+    readonly id: string;
+    readonly text: string;
+    readonly type: SuggestionType;
+    readonly isHistory: boolean;
+    readonly detail?: string | undefined;
+}
+interface RankedSuggestion {
+    readonly item: SuggestionItem;
+    readonly score: number;
+    readonly matchType: MatchType;
+    readonly matchIndices: number[];
+}
+interface SuggestionResults {
+    readonly query: string;
+    readonly results: RankedSuggestion[];
+}
+interface RankOptions {
+    readonly limit?: number | undefined;
+}
+/**
+ * Injected fuzzy-match port. The real matcher is wired by the caller; this
+ * module declares only the shape it consumes. A `null` return means "no match".
+ */
+type FuzzyMatchFn = (text: string, query: string) => {
+    score: number;
+    indices: number[];
+} | null;
+interface MatchClassification {
+    readonly matchType: MatchType;
+    readonly score: number;
+    readonly indices: number[];
+}
+/**
+ * Classify how `query` matches `text`. Exact (case-insensitive full equality)
+ * outranks prefix (case-insensitive starts-with) outranks the injected fuzzy
+ * matcher. An empty query is inert: `none`, score 0, no indices.
+ */
+declare function classifyMatch(text: string, query: string, fuzzy: FuzzyMatchFn): MatchClassification;
+/**
+ * Rank `candidates` against `query` for one tenant. Fails closed on an empty
+ * tenant. With a non-empty query, `none` matches are dropped; with an empty
+ * query every candidate is kept (inert match) and ordered purely by the
+ * tie-breakers. Never mutates `candidates`.
+ */
+declare function rankSuggestions(tenantId: string, query: string, candidates: readonly SuggestionItem[], fuzzy: FuzzyMatchFn, opts?: RankOptions): SuggestionResults;
+/**
+ * Keep one item per normalized (trimmed, case-insensitive) text. First
+ * occurrence wins, EXCEPT a history item supersedes an earlier non-history
+ * item that shares the same normalized text. Stable otherwise. Pure.
+ */
+declare function dedupeByText(candidates: readonly SuggestionItem[]): SuggestionItem[];
+/**
+ * Tenant-scoped append-with-dedupe history seam. Implementations MUST key by
+ * tenant so cross-tenant reads are impossible, MUST keep entries
+ * most-recent-first, and MUST bound storage to a ring cap.
+ */
+interface SuggestionHistoryStore {
+    /** Append `text` for `tenantId`, deduped, most-recent-first, ring-bounded. */
+    append(tenantId: string, text: string): void;
+    /** Most-recent-first texts for `tenantId`. */
+    list(tenantId: string): string[];
+}
+/**
+ * In-memory reference implementation mirroring this package's other stores.
+ * Tenancy is structural: `tenantId` is part of the key AND validated on every
+ * read/write, so a tenant can never observe another tenant's history.
+ */
+declare class InMemorySuggestionHistoryStore implements SuggestionHistoryStore {
+    #private;
+    constructor(cap?: number);
+    append(tenantId: string, text: string): void;
+    list(tenantId: string): string[];
+}
+/**
+ * Record `text` into the tenant's suggestion history. Fails closed on an empty
+ * tenant; blank text is ignored.
+ */
+declare function recordHistory(store: SuggestionHistoryStore, tenantId: string, text: string): void;
+/**
+ * Read the tenant's history as ranked-ready {@link SuggestionItem}s
+ * (most-recent-first, flagged `isHistory`). Fails closed on an empty tenant.
+ */
+declare function historyCandidates(store: SuggestionHistoryStore, tenantId: string): SuggestionItem[];
+
+/**
+ * Conventional-Commits message generation — a faithful re-expression of a
+ * coding agent's "write my commit message from staged changes" capability into
+ * Sailor's grammar: TypeScript, multi-tenant, no model-vendor lock-in.
+ *
+ * ── This is a WRAP, not an agent ────────────────────────────────────────────
+ * The small-model invocation is INJECTED via the {@link CompletionModel} port.
+ * This module does NOT implement an agent loop, a transport, a token budget, or
+ * tenancy — those travel inside the injected port (the real impl is the runtime
+ * model seam; tests pass a deterministic fake). The delta this module owns is
+ * purely DOMAIN SHAPING:
+ *   • the Conventional Commits system prompt,
+ *   • the git-context → user-prompt rendering,
+ *   • the "regenerate, but DIFFERENT" negative-constraint contract,
+ *   • output de-formatting + bounded retry with a FAIL-CLOSED terminal error.
+ *
+ * Everything here is pure/deterministic given the injected model. Inputs are
+ * Zod-validated at the boundary; nothing is mutated in place.
+ */
+
+/** Sampling temperature handed to the injected model (slightly creative, stable). */
+declare const DEFAULT_TEMPERATURE = 0.3;
+/** Per-attempt abort budget (ms) handed to the injected model. */
+declare const DEFAULT_ABORT_MS = 30000;
+/** Total attempts before failing closed (initial try + retries inclusive). */
+declare const MAX_RETRIES = 3;
+declare const gitContextSchema: z.ZodObject<{
+    branch: z.ZodString;
+    recentCommits: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodObject<{
+        status: z.ZodString;
+        path: z.ZodString;
+        diff: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Staged git context the message is derived from. Zod-validated public input. */
+type GitContext = z.infer<typeof gitContextSchema>;
+/**
+ * When `previous` is set this is a "regenerate, but materially DIFFERENT from
+ * the previous message" request — see {@link buildCommitPrompt}. Built
+ * conditionally to honor `exactOptionalPropertyTypes`.
+ */
+interface GenerateOptions {
+    readonly previous?: string | undefined;
+}
+/**
+ * Injected small-model seam. The real implementation is the runtime's model
+ * invocation (carrying tenancy/auth); tests inject a deterministic fake. This
+ * module consumes the port and never implements model plumbing itself.
+ */
+interface CompletionModel {
+    complete(p: {
+        system: string;
+        user: string;
+        temperature: number;
+        abortMs: number;
+    }): Promise<string>;
+}
+/** Raised when every attempt is exhausted. Fail closed — never a fake message. */
+declare class CommitMessageError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Builds the `{ system, user }` pair. The system prompt encodes the
+ * Conventional Commits spec and the "only the message" instruction. The user
+ * prompt renders branch + recent commits + per-file status/path/diff. When
+ * `opts.previous` is set, a NEGATIVE CONSTRAINT block is appended so a
+ * regenerate request yields a materially different message. Pure.
+ */
+declare function buildCommitPrompt(ctx: GitContext, opts?: GenerateOptions): {
+    system: string;
+    user: string;
+};
+/**
+ * Removes surrounding triple-backtick fences (with optional language tag) and
+ * surrounding single/double quotes, then trims. Pure — defensive against models
+ * that wrap output despite the system instruction.
+ */
+declare function stripFormatting(raw: string): string;
+/**
+ * Generates a Conventional-Commits message from staged git context by wrapping
+ * the injected {@link CompletionModel}. Zod-validates `ctx`; calls the model at
+ * {@link DEFAULT_TEMPERATURE}/{@link DEFAULT_ABORT_MS}; retries up to
+ * {@link MAX_RETRIES} total attempts on rejection OR empty/whitespace output;
+ * returns the de-formatted message. FAIL CLOSED: if every attempt is exhausted
+ * it throws {@link CommitMessageError} — never an empty or fabricated message.
+ */
+declare function generateCommitMessage(args: {
+    ctx: GitContext;
+    model: CompletionModel;
+    opts?: GenerateOptions;
+}): Promise<string>;
+
+/**
+ * In-session context compaction — a faithful re-expression of a coding agent's
+ * mid-turn "the transcript no longer fits, shrink it and keep going" recovery
+ * into Sailor's grammar: TypeScript, deterministic, model-agnostic, no datastore
+ * and no tokenizer-vendor lock-in.
+ *
+ * ── What this is (and is NOT) ───────────────────────────────────────────────
+ * This module shrinks the CURRENT, in-flight transcript when a turn overflows
+ * the model's context window. It is NOT cross-session memory: nothing here
+ * persists, recalls, or indexes past sessions. The only output is a single
+ * summary string that the caller substitutes for the old transcript so the
+ * SAME turn can be retried within budget. Memory is a different subsystem;
+ * conflating the two is the classic mistake this header exists to prevent.
+ *
+ * ── Mental model: recursive map-reduce ──────────────────────────────────────
+ * A transcript is a list of whole {@link Message}s. We never split a message —
+ * the unit of summarization is always a complete message so a tool call and its
+ * output, or a reasoning block, are never torn in half.
+ *
+ *   MAP    {@link split} greedily packs whole messages into chunks each ≤ the
+ *          token budget, then {@link summarizeChunks} summarizes every chunk
+ *          (bounded concurrency) into a partial summary.
+ *   REDUCE {@link reduce} binary-pairs the partial summaries, summarizes each
+ *          pair, and recurses on the shorter list — at most {@link REDUCE_DEPTH}
+ *          levels — until the combined summary fits the budget. The final text
+ *          is hard-capped at {@link OUTPUT_TOKEN_CAP} (a model that ignores the
+ *          length instruction is truncated, not trusted).
+ *
+ * ── The numeric contract (constants ARE the design — exported) ──────────────
+ *  • {@link TOKEN_CORRECTION} = 1.3 — char/4 and similar cheap heuristics
+ *    UNDERCOUNT real BPE tokens by ~15-30% on code/markup-heavy transcripts.
+ *    Multiplying the base estimate by 1.3 buys headroom so a "fits" decision
+ *    does not itself overflow. We round UP everywhere for the same reason:
+ *    over-counting wastes a little budget, under-counting reintroduces the
+ *    exact overflow we are recovering from.
+ *  • {@link BUDGET_RATIO} = 0.6 — the summary must coexist with the system
+ *    prompt, the model's reply, fresh tool output, and decode headroom in the
+ *    SAME retried turn. Spending only 60% of the usable window on the recap
+ *    leaves room for all of that.
+ *  • {@link MIN_BUDGET} = 1000 — below ~1k tokens a "summary" degenerates into
+ *    lossy garbage; we would rather over-summarize than emit something useless,
+ *    so the budget is clamped up to a floor that can still hold a coherent map
+ *    of paths/commands/decisions.
+ *  • {@link CONCURRENCY} = 3 — chunk summaries are independent and fan out, but
+ *    an unbounded fan-out melts rate limits mid-recovery (the worst possible
+ *    moment). 3 is the empirical "fast but polite" point for hosted models.
+ *  • {@link REDUCE_DEPTH} = 3 — binary reduction shrinks the summary list
+ *    geometrically; 3 levels collapse up to 8 partials into one, which covers
+ *    realistic overflowed transcripts while bounding worst-case model calls so
+ *    a pathological "never shrinks" model cannot recurse forever.
+ *  • {@link OUTPUT_TOKEN_CAP} = 2048 — the recap must itself be small enough to
+ *    leave the bulk of the retried turn for actual work; also the hard backstop
+ *    against a model that ignores the length instruction.
+ *  • {@link CLIP_TOOL_CHARS} = 2000 / {@link CLIP_TEXT_CHARS} = 16000 — raw
+ *    tool dumps (lockfiles, build logs) and giant pasted blobs are mostly noise
+ *    for a recap; clipping them BEFORE summarization keeps the model focused on
+ *    signal and keeps chunk sizing predictable. Text gets a larger allowance
+ *    than tool I/O because prose carries more decision-relevant signal per char.
+ *
+ * ── Fail-closed sentinel (DOCUMENTED CHOICE) ────────────────────────────────
+ * If ANY chunk or reduce-group summarization rejects, we must NOT splice a
+ * partial or empty recap into the turn — that silently DROPS context the agent
+ * still needs and corrupts the run in a way that is nearly impossible to debug
+ * after the fact. Instead {@link compactTranscript} resolves with the sentinel
+ * string `"compact"`. The contract with the caller: seeing `"compact"` back
+ * means "compaction could not be completed safely — retry the WHOLE compaction"
+ * (the same token the eligibility check keys on), never "here is your summary".
+ * Failing loud-but-recoverable beats failing silent-and-lossy.
+ *
+ * ── Determinism & immutability ──────────────────────────────────────────────
+ * No Date, no Math.random, no network, no I/O. Output is a pure function of the
+ * transcript plus the injected `summarize` and `base` estimator. The transcript
+ * is never mutated; every transformation builds new arrays/strings.
+ */
+/** Tokenizers undercount real BPE by ~15-30%; scale the base estimate up. */
+declare const TOKEN_CORRECTION = 1.3;
+/** Fraction of the usable window the recap is allowed to occupy. */
+declare const BUDGET_RATIO = 0.6;
+/** Hard floor: below this a summary degenerates into lossy noise. */
+declare const MIN_BUDGET = 1000;
+/** Max simultaneous in-flight chunk summaries (rate-limit politeness). */
+declare const CONCURRENCY = 3;
+/** Max binary-reduce recursion levels (bounds worst-case model calls). */
+declare const REDUCE_DEPTH = 3;
+/** Hard cap on the final combined summary size, in corrected tokens. */
+declare const OUTPUT_TOKEN_CAP = 2048;
+/** Per-tool-part input/output clip length before summarization. */
+declare const CLIP_TOOL_CHARS = 2000;
+/** Per-text-part clip length before summarization. */
+declare const CLIP_TEXT_CHARS = 16000;
+/** A text fragment of a message. */
+interface TextPart {
+    readonly type: "text";
+    readonly text: string;
+}
+/** A tool invocation fragment: the call inputs and the tool's raw output. */
+interface ToolPart {
+    readonly type: "tool";
+    readonly name: string;
+    readonly input: string;
+    readonly output: string;
+}
+type Part = TextPart | ToolPart;
+/** One conversational turn fragment owned by a single role. */
+interface Message {
+    readonly role: "user" | "assistant" | "tool" | "system";
+    readonly parts: readonly Part[];
+}
+/** The ordered list of messages making up the current turn's context. */
+type Transcript = readonly Message[];
+/**
+ * Caller-injected model seam. Real callers back this with their LLM; tests pass
+ * a deterministic fake. The module never talks to a network itself.
+ */
+type Summarize = (prompt: string) => Promise<string>;
+/** Caller-injected cheap token heuristic; defaults to chars/4. */
+type BaseEstimator = (text: string) => number;
+/** The eligibility signal this module keys on (also the failure sentinel). */
+declare const COMPACT_SENTINEL = "compact";
+/**
+ * Corrected token estimate: `ceil(base(text) * TOKEN_CORRECTION)`. The base
+ * estimator is injectable so callers can swap a real tokenizer in; we still
+ * apply the correction multiplier on top because even real tokenizers diverge
+ * from the model's server-side counting. Always rounds UP — see header.
+ */
+declare function estimateTokens(text: string, base?: BaseEstimator): number;
+/**
+ * Budget = 60% of the usable window, floored, then clamped UP to
+ * {@link MIN_BUDGET} so a tiny window can never produce an incoherent recap.
+ */
+declare function computeBudget(usableTokens: number): number;
+/**
+ * Produce a stable, XML-ish `<conversation>` rendering of a single message,
+ * clipping oversized text/tool fields so a giant blob can neither dominate a
+ * chunk nor blow the model's own window during summarization. Pure: the input
+ * message is never mutated (new strings only).
+ */
+declare function renderClipped(msg: Message): string;
+/**
+ * MAP step. Greedily pack WHOLE messages into chunks whose corrected estimate
+ * is ≤ `budget`. A message that alone exceeds `budget` becomes its own chunk
+ * (oversize fallback) — it is summarized later through the same clipping render
+ * path, so it can never wedge the packer. Pure: builds new arrays only.
+ */
+declare function split(transcript: Transcript, budget: number, estimate: (text: string) => number): Message[][];
+/** Input to {@link compactTranscript}. `base` is optional (exactOptional). */
+interface CompactTranscriptInput {
+    readonly transcript: Transcript;
+    readonly usableTokens: number;
+    readonly summarize: Summarize;
+    readonly base?: BaseEstimator | undefined;
+}
+/**
+ * Orchestrate split → summarizeChunks → reduce and return the final recap.
+ *
+ * FAIL CLOSED: if any chunk or reduce-group summarization rejects, this resolves
+ * with the {@link COMPACT_SENTINEL} string `"compact"` rather than a partial or
+ * empty summary — never silently dropping context. The caller treats `"compact"`
+ * as "retry the whole compaction" (see module header).
+ *
+ * Deterministic given the injected `summarize` and `base`. The transcript is
+ * never mutated.
+ */
+declare function compactTranscript(input: CompactTranscriptInput): Promise<string>;
+/**
+ * Eligibility gate. Compaction runs only when the model stopped specifically
+ * because it wants a compaction or because the context overflowed; every other
+ * stop reason (end_turn, tool_use, …) is left untouched.
+ */
+declare function shouldCompact(stop: {
+    reason: string;
+}): boolean;
+
+/**
+ * Deployment lifecycle status model.
+ *
+ * Commit-keyed deploy state plus a newest-first timeline derivation.
+ * Pure, deterministic, immutable. Multi-tenant fail-closed at the
+ * public boundary. The preview domain suffix is always injected —
+ * there is no hardcoded host anywhere in this module.
+ */
+type DeployState = "idle" | "deploying" | "live" | "failed";
+interface DeploymentUiStatus {
+    state: DeployState;
+    commitSha?: string | undefined;
+    url?: string | undefined;
+    deploymentId?: string | undefined;
+}
+interface DeploymentTimelineEntry {
+    commitSha: string;
+    commitMessage: string;
+    commitDate: string;
+    state: DeployState;
+    url?: string | undefined;
+}
+/** Structural commit reference — declared locally, no sibling imports. */
+interface DeploymentCommitRef {
+    sha: string;
+    message: string;
+    date: string;
+}
+interface DeploymentRecord {
+    commitSha: string;
+    deploymentId: string | null;
+    state: DeployState;
+}
+declare class DeploymentStateError extends Error {
+    constructor(message: string);
+}
+declare const latestStatusInputSchema: z.ZodObject<{
+    latestCommitSha: z.ZodString;
+    deployments: z.ZodArray<z.ZodObject<{
+        commitSha: z.ZodString;
+        deploymentId: z.ZodNullable<z.ZodString>;
+        state: z.ZodEnum<{
+            failed: "failed";
+            idle: "idle";
+            deploying: "deploying";
+            live: "live";
+        }>;
+    }, z.core.$strip>>;
+    isAgentRunning: z.ZodBoolean;
+}, z.core.$strip>;
+declare const timelineOptsSchema: z.ZodObject<{
+    domainSuffix: z.ZodString;
+    isAgentRunning: z.ZodBoolean;
+    latestCommitSha: z.ZodString;
+}, z.core.$strip>;
+type LatestStatusInput = z.infer<typeof latestStatusInputSchema>;
+type TimelineOpts = z.infer<typeof timelineOptsSchema>;
+/**
+ * Deterministic per-commit preview domain built from an injected suffix.
+ * No hardcoded host — the suffix fully determines the zone.
+ */
+declare function domainForCommit(commitSha: string, domainSuffix: string): string;
+/**
+ * Faithful rule: matching record state wins; else deploying when the
+ * agent is running; else idle. `live` only when a matching record is
+ * explicitly live. Never throws.
+ */
+declare function deriveLatestStatus(input: {
+    latestCommitSha: string;
+    deployments: readonly DeploymentRecord[];
+    isAgentRunning: boolean;
+}): DeploymentUiStatus;
+/**
+ * One entry per commit, newest-first order preserved from input.
+ * Matching deployment record wins; the head commit gets `deploying`
+ * when the agent is running and has no terminal record; older
+ * unmatched commits resolve to `idle`. Immutable, deterministic.
+ */
+declare function deriveTimelineFromCommits(commits: readonly DeploymentCommitRef[], deployments: readonly DeploymentRecord[], opts: TimelineOpts): DeploymentTimelineEntry[];
+/**
+ * Explicit deploy state machine. Illegal transitions throw a typed
+ * error. `reset` always returns to idle regardless of current state.
+ */
+declare function advanceState(current: DeployState, event: "start" | "succeed" | "fail" | "reset"): DeployState;
+/** Public tenant-scoped status entry — fail-closed, zod-validated. */
+declare function getDeploymentStatus(tenantId: string, input: LatestStatusInput): DeploymentUiStatus;
+/** Public tenant-scoped timeline entry — fail-closed, zod-validated. */
+declare function getDeploymentTimeline(tenantId: string, commits: readonly DeploymentCommitRef[], deployments: readonly DeploymentRecord[], opts: TimelineOpts): DeploymentTimelineEntry[];
+
+/**
+ * Design-context ingestion: turn an existing website into a structured
+ * generation seed for a codegen turn.
+ *
+ * The scrape implementation is provider-specific and injected via a port;
+ * this module never performs network I/O itself.
+ */
+/** Structured generation seed extracted from an existing site. */
+interface DesignContext {
+    tenantId: string;
+    sourceUrl: string;
+    content: string;
+    brand: {
+        colors: string[];
+        fonts: string[];
+    };
+    screenshotRef?: string | undefined;
+    title?: string | undefined;
+    fetchedAt: string;
+}
+/** Loose shape returned by a scrape provider (providers vary widely). */
+interface RawScrapeResult {
+    markdown?: string | undefined;
+    html?: string | undefined;
+    screenshot?: string | null | undefined;
+    metadata?: {
+        title?: string | undefined;
+    } | undefined;
+    branding?: {
+        colors?: string[] | undefined;
+        fonts?: string[] | undefined;
+    } | undefined;
+}
+type ScrapeFormat = "markdown" | "screenshot" | "branding";
+/** Injected provider port — callers wire a concrete scrape implementation. */
+interface ScrapeProvider {
+    scrape(url: string, opts: {
+        formats: ScrapeFormat[];
+    }): Promise<RawScrapeResult>;
+}
+/** Clock injection for deterministic tests. */
+type Clock = () => Date;
+/**
+ * Pure transform from a loose provider result to a {@link DesignContext}.
+ * Never throws on missing fields — degrades gracefully. Fails closed on
+ * empty tenantId / url.
+ */
+declare function normalizeScrapeResult(tenantId: string, url: string, raw: RawScrapeResult, opts?: {
+    clock?: Clock | undefined;
+}): DesignContext;
+/**
+ * Validate inputs, call the injected provider, normalize the result.
+ * tenantId is mandatory and validated before the provider is invoked
+ * (fail-closed: no provider call for an invalid tenant).
+ */
+declare function ingestDesignContext(tenantId: string, url: string, provider: ScrapeProvider, opts?: {
+    formats?: ScrapeFormat[] | undefined;
+    clock?: Clock | undefined;
+}): Promise<DesignContext>;
+/**
+ * Render a compact, deterministic prompt-seed block suitable for
+ * prepending to a codegen turn. Pure; output length is bounded.
+ */
+declare function toGenerationSeed(ctx: DesignContext, opts?: {
+    maxChars?: number | undefined;
+}): string;
+
+/**
+ * Edit planner — a faithful re-expression of a targeted-edit model for an
+ * app-builder agent. Given a natural-language prompt and a manifest of the
+ * current project files, it classifies the edit intent, selects the minimal
+ * set of files to send to a codegen turn, and provides a terse "fast-apply"
+ * format for re-integrating model output.
+ *
+ * Everything here is deterministic and pure aside from `applyEditBlock`,
+ * whose merge step is provider-specific and injected.
+ */
+declare enum EditType {
+    UPDATE_COMPONENT = "UPDATE_COMPONENT",
+    ADD_FEATURE = "ADD_FEATURE",
+    FIX_ISSUE = "FIX_ISSUE",
+    REFACTOR = "REFACTOR",
+    FULL_REBUILD = "FULL_REBUILD",
+    UPDATE_STYLE = "UPDATE_STYLE",
+    ADD_DEPENDENCY = "ADD_DEPENDENCY"
+}
+type FileKind = "component" | "page" | "style" | "config" | "util" | "other";
+interface FileInfo {
+    path: string;
+    type: FileKind;
+}
+interface FileManifest {
+    files: Record<string, FileInfo>;
+}
+interface EditIntent {
+    type: EditType;
+    targetFiles: string[];
+    description: string;
+}
+interface FileContext {
+    primaryFiles: string[];
+    contextFiles: string[];
+    systemPrompt: string;
+    editIntent: EditIntent;
+}
+interface EditBlock {
+    targetFile: string;
+    instructions: string;
+    update: string;
+}
+type EditMerger = (originalContent: string, update: string, instructions: string) => Promise<string>;
+interface ApplyEditResult {
+    ok: boolean;
+    merged?: string;
+    error?: string;
+}
+declare function analyzeEditIntent(prompt: string, manifest: FileManifest): EditIntent;
+declare function buildEditInstructions(type: EditType): string;
+declare function selectFilesForEdit(prompt: string, manifest: FileManifest): FileContext;
+declare function parseEditBlocks(text: string): EditBlock[];
+/**
+ * A trivial deterministic fallback merger: replaces the original content
+ * wholesale with the update. Real callers inject an LLM-backed merger.
+ */
+declare const fallbackMerger: EditMerger;
+declare function applyEditBlock(originalContent: string, block: EditBlock, merge?: EditMerger): Promise<ApplyEditResult>;
+declare function planEdit(tenantId: string, prompt: string, manifest: FileManifest): Promise<FileContext>;
+
+/**
+ * fuzzy-match — pure, deterministic string-matching primitives.
+ *
+ * A dependency-free re-expression of the classic "smart-case fuzzy +
+ * glob-wildcard" matcher found in modern terminals and command palettes.
+ * Everything here is a small pure function: no I/O, no shared state, no
+ * mutation of inputs, no `console`.
+ *
+ * Surface:
+ *   - matchIndices                              smart-case subsequence match
+ *   - matchIndicesCaseInsensitive               always case-insensitive
+ *   - matchIndicesCaseInsensitiveIgnoreSpaces   ci + spaces ignored
+ *   - matchWildcardPattern                      glob (* ? [..] \) full-string
+ *   - matchWildcardPatternCaseInsensitive       glob, case-insensitive
+ *   - rankByFuzzy                               generic rank/filter/sort helper
+ *
+ * --------------------------------------------------------------------------
+ * Subsequence scoring heuristic (deterministic; only ORDERING is contractual)
+ * --------------------------------------------------------------------------
+ * Every char of `query` must appear in `text` in order. Among the many
+ * possible subsequences we use a single forward greedy scan with a fixed,
+ * documented tie-break so the result is fully deterministic:
+ *
+ *   For each query char, scan `text` forward from the previous match + 1 and
+ *   collect every candidate position. Pick the candidate that maximises a
+ *   per-char local score:
+ *
+ *     + WORD_BOUNDARY_BONUS  if the candidate is at text start, or the
+ *                            preceding char is a separator (`/ _ - . space`)
+ *                            or a lower→upper camelCase hump.
+ *     + CONTIGUOUS_BONUS     if the candidate immediately follows the
+ *                            previous matched index (a run).
+ *     - GAP_PENALTY * gap    distance skipped since the previous match.
+ *     - LEADING_PENALTY      (first query char only) * its absolute index,
+ *                            so earlier overall placement is preferred.
+ *
+ *   Ties on local score break toward the EARLIEST candidate index — this is
+ *   what makes the scan deterministic and is exercised by the tests.
+ *
+ * The aggregate `score` is the sum of per-char local scores. Higher is a
+ * better match. Magnitudes are intentionally unspecified; only the relative
+ * ordering (boundary/contiguous/at-start outranks scattered/buried/late) is
+ * part of the contract.
+ *
+ * Empty query: defined to match everything with `score === 0` and
+ * `indices === []`. Empty text with a non-empty query: `null`.
+ */
+/** A successful match: the chosen text positions and an aggregate score. */
+interface FuzzyMatch {
+    readonly score: number;
+    readonly indices: readonly number[];
+}
+interface MatchOptions {
+    /** Force case-insensitive matching regardless of query casing. */
+    readonly forceCaseInsensitive?: boolean | undefined;
+}
+/**
+ * Smart-case subsequence fuzzy match.
+ *
+ * If `query` is all-lowercase the match is case-insensitive; if it contains
+ * any uppercase char the *whole* query matches case-sensitively. Returns the
+ * chosen 0-based `indices` in `text` plus an aggregate `score`, or `null` if
+ * `query` is not a subsequence of `text`.
+ */
+declare function matchIndices(text: string, query: string, options?: MatchOptions): FuzzyMatch | null;
+/** Like {@link matchIndices} but always case-insensitive. */
+declare function matchIndicesCaseInsensitive(text: string, query: string): FuzzyMatch | null;
+/**
+ * Case-insensitive subsequence match where spaces in BOTH `query` and `text`
+ * are ignored for matching. Returned `indices` always point at original
+ * `text` positions and never land on a skipped space.
+ */
+declare function matchIndicesCaseInsensitiveIgnoreSpaces(text: string, query: string): FuzzyMatch | null;
+/**
+ * Anchored (full-string) glob match. `*` = any run incl. empty, `?` = one
+ * char, `[..]`/`[a-z]`/`[!..]` char classes, `\` escapes a metachar. `/` is
+ * an ordinary char. Case-sensitive.
+ */
+declare function matchWildcardPattern(text: string, pattern: string): boolean;
+/** Case-insensitive variant of {@link matchWildcardPattern}. */
+declare function matchWildcardPatternCaseInsensitive(text: string, pattern: string): boolean;
+/** One ranked result: the original item plus its match score and indices. */
+interface RankedFuzzyResult<T> {
+    readonly item: T;
+    readonly score: number;
+    readonly indices: readonly number[];
+}
+interface RankByFuzzyOptions {
+    /** Force case-insensitive matching regardless of query casing. */
+    readonly caseInsensitive?: boolean | undefined;
+}
+/**
+ * Rank `items` by fuzzy-matching `key(item)` against `query`.
+ *
+ * - Non-matches are filtered out.
+ * - Sorted by `score` descending.
+ * - Stable for equal scores (input order preserved).
+ * - Pure: neither `items` nor its elements are mutated.
+ * - Empty query → every item with `score 0` / empty `indices`, input order.
+ */
+declare function rankByFuzzy<T>(items: readonly T[], query: string, key: (item: T) => string, options?: RankByFuzzyOptions): ReadonlyArray<RankedFuzzyResult<T>>;
+
+/**
+ * Inbound admission + conversation resolution (the multi-channel "front door").
+ *
+ * Faithful re-expression of a multi-channel assistant's pre-turn policy:
+ * resolve a stable tenant-scoped session key from a normalized inbound
+ * message, then gate it through allowlist → mention → debounce before it is
+ * allowed to become an agent turn. Pure data/logic; time is injected (no
+ * timers); tenant-scoped & fail-closed. No transport, no host I/O.
+ */
+/** Minimal structural inbound shape (declared locally — no sibling imports). */
+interface InboundLike {
+    readonly tenantId: string;
+    readonly channelId: string;
+    readonly chatId: string;
+    readonly threadId?: string | undefined;
+    readonly senderId: string;
+    readonly text: string;
+    readonly receivedAt: string;
+}
+type ChatType = "dm" | "group";
+type GroupBinding = "per-chat" | "per-sender" | "per-thread";
+interface SessionKeyOptions {
+    readonly chatType?: ChatType | undefined;
+    readonly groupBinding?: GroupBinding | undefined;
+}
+/**
+ * Deterministic, tenant-prefixed conversation/session key. Cross-tenant keys
+ * can never collide (tenant is the first segment). Defaults: a group binds
+ * per-chat, a DM binds per-sender; an explicit `groupBinding` overrides.
+ */
+declare function resolveSessionKey(inbound: InboundLike, opts?: SessionKeyOptions): string;
+interface CompiledAllowlist {
+    readonly exact: ReadonlySet<string>;
+    readonly prefixes: ReadonlyArray<{
+        readonly prefix: string;
+        readonly entry: string;
+    }>;
+    readonly matchAny: boolean;
+    readonly empty: boolean;
+    readonly openWhenEmpty: boolean;
+}
+interface AllowlistMatch {
+    readonly allowed: boolean;
+    readonly matchedBy?: string | undefined;
+}
+declare function compileAllowlist(entries: ReadonlyArray<string>, opts?: {
+    openWhenEmpty?: boolean;
+}): CompiledAllowlist;
+declare function matchesAllowlist(compiled: CompiledAllowlist, candidates: ReadonlyArray<string>): AllowlistMatch;
+/** Case-insensitive, word-boundary-aware handle detection. */
+declare function hasMention(text: string, handles: ReadonlyArray<string>): boolean;
+interface MentionContext {
+    readonly chatType: ChatType;
+    readonly assistantHandles: ReadonlyArray<string>;
+    readonly text: string;
+    readonly isReplyToAssistant?: boolean | undefined;
+}
+/** A group message is gated unless it mentions the assistant or replies to it. */
+declare function requiresMention(ctx: MentionContext): boolean;
+type DebounceResult = {
+    admit: false;
+} | {
+    admit: true;
+    merged: string;
+};
+/**
+ * Coalesces a burst per session key. Time is injected (`nowMs`). A later
+ * offer whose window has closed flushes (admits) the prior buffer and opens
+ * a fresh window for the new message. `flush` force-admits regardless of the
+ * window and clears state.
+ */
+declare class InboundDebouncer {
+    #private;
+    constructor(opts?: {
+        windowMs?: number;
+    });
+    offer(sessionKey: string, message: string, nowMs: number): DebounceResult;
+    flush(sessionKey: string, _nowMs: number): DebounceResult;
+}
+interface AdmissionPolicy {
+    readonly chatType: ChatType;
+    readonly allowlist: CompiledAllowlist;
+    readonly assistantHandles: ReadonlyArray<string>;
+    readonly groupBinding?: GroupBinding | undefined;
+}
+interface AdmissionDeps {
+    readonly debouncer: InboundDebouncer;
+    readonly nowMs?: number | undefined;
+    readonly isReplyToAssistant?: boolean | undefined;
+}
+type AdmissionReason = "empty-tenant" | "not-allowlisted" | "mention-required" | "debounced";
+type AdmissionResult = {
+    readonly admit: true;
+    readonly sessionKey: string;
+    readonly text: string;
+} | {
+    readonly admit: false;
+    readonly reason: AdmissionReason;
+};
+/**
+ * Pipeline: tenant → allowlist → session key → debounce → mention.
+ *
+ * A window-closing offer admits the PRIOR (already-gated) buffered content,
+ * so a message that itself lacks a mention can still flush the conversation.
+ * The current message's mention gate only governs whether it produces a
+ * `mention-required` vs `debounced` outcome while it waits.
+ */
+declare function admitInbound(inbound: InboundLike, policy: AdmissionPolicy, deps: AdmissionDeps): AdmissionResult;
+
+/**
+ * Pluggable cross-session memory provider model.
+ *
+ * Recalled memory is INFORMATIONAL BACKGROUND, never an executable
+ * instruction. All recalled content is wrapped in a fixed, non-forgeable
+ * banner before it can reach a prompt, and model OUTPUT is scrubbed so a
+ * model cannot fabricate a "recalled memory" banner to escalate.
+ */
+interface MemoryContext {
+    readonly tenantId: string;
+    readonly sessionId: string;
+}
+/**
+ * Validate + normalize ctx at the boundary. Fail-closed: an empty / blank
+ * tenantId throws BEFORE any provider method is invoked. Returns a fresh
+ * immutable copy — never mutates the caller's object.
+ */
+declare function assertTenantContext(ctx: unknown): MemoryContext;
+interface SessionRef {
+    readonly sessionId: string;
+}
+interface MemoryProvider {
+    name(): string;
+    isAvailable(): boolean | Promise<boolean>;
+    initialize(ctx: MemoryContext): Promise<void>;
+    systemPromptBlock(ctx: MemoryContext): Promise<string>;
+    prefetch(query: string, ctx: MemoryContext): Promise<string>;
+    syncTurn(userContent: string, assistantContent: string, ctx: MemoryContext): Promise<void>;
+    onSessionEnd(messages: readonly unknown[], ctx: MemoryContext): Promise<void>;
+    onSessionSwitch(from: SessionRef | null, to: SessionRef, ctx: MemoryContext): Promise<void>;
+    onPreCompress(messages: readonly unknown[], ctx: MemoryContext): Promise<string>;
+    onDelegation(task: string, result: string, ctx: MemoryContext): Promise<void>;
+    shutdown(): Promise<void>;
+}
+declare const MEMORY_CONTEXT_BANNER_OPEN = "<<<RECALLED_MEMORY_CONTEXT_BEGIN>>>";
+declare const MEMORY_CONTEXT_BANNER_CLOSE = "<<<RECALLED_MEMORY_CONTEXT_END>>>";
+/**
+ * Pure helper: strip any occurrence of the memory-context delimiters from
+ * arbitrary text. Used both to sanitize recalled data before wrapping and to
+ * scrub model output. Does not mutate its input.
+ */
+declare function sanitizeContext(text: string): string;
+/**
+ * Wrap raw recalled text in the fixed banner. Inner forged delimiters are
+ * stripped first so the result contains exactly one real open/close pair.
+ */
+declare function buildMemoryContextBlock(rawRecall: string): string;
+/**
+ * Streaming output scrubber. Strips any model-emitted attempt to forge the
+ * memory-context banner, including a delimiter split across chunk boundaries.
+ * Deterministic; the only state is its own bounded buffer.
+ */
+declare class StreamingContextScrubber {
+    #private;
+    feed(chunk: string): string;
+    flush(): string;
+}
+declare class MemoryManager {
+    #private;
+    constructor(provider: MemoryProvider | null);
+    /**
+     * isAvailable ? wrap(prefetch + systemPromptBlock) : "".
+     * A provider exception never aborts the turn — degrade to "".
+     */
+    assembleContext(query: string, ctx: unknown): Promise<string>;
+    initialize(ctx: unknown): Promise<void>;
+    syncTurn(userContent: string, assistantContent: string, ctx: unknown): Promise<void>;
+    onSessionEnd(messages: readonly unknown[], ctx: unknown): Promise<void>;
+    onSessionSwitch(from: SessionRef | null, to: SessionRef, ctx: unknown): Promise<void>;
+    onPreCompress(messages: readonly unknown[], ctx: unknown): Promise<string>;
+    onDelegation(task: string, result: string, ctx: unknown): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Permission ruleset evaluator.
+ *
+ * A small, pure, stateless re-expression of a two-dimensional wildcard
+ * permission model plus a bash-command-prefix extractor. No global state,
+ * no I/O, no mutation of inputs — every function is referentially transparent.
+ *
+ * The model has two independent dimensions per rule:
+ *   - `permission` — the capability namespace (e.g. "bash", "edit", "net")
+ *   - `pattern`    — the concrete subject within that namespace
+ * A rule applies only when BOTH dimensions match the query via {@link wildcardMatch}.
+ */
+/** The decision a rule yields. Unknown queries fail safe to "ask". */
+type Action = "allow" | "deny" | "ask";
+/** A single permission rule. Both dimensions are matched as wildcard globs. */
+interface Rule {
+    permission: string;
+    pattern: string;
+    action: Action;
+}
+/** An ordered list of rules. Earlier rules take precedence. */
+type Ruleset = Rule[];
+/**
+ * Anchored full-string glob matcher.
+ *
+ * Semantics:
+ *   - `*` matches any run of characters, including the empty run.
+ *   - `?` matches exactly one character.
+ *   - Every other character is matched literally (regex metacharacters in
+ *     `pattern` carry no special meaning).
+ *   - The match is anchored: the entire `str` must be consumed.
+ *
+ * Special rule (ported faithfully): if `pattern` ends with `" *"` (a single
+ * space immediately followed by `*`), that trailing ` *` is OPTIONAL. The
+ * pattern then matches both `"<head> <rest>"` and exactly `"<head>"` with
+ * nothing after it. For example `"git *"` matches `"git"` and `"git status"`.
+ *
+ * Implemented with a backtracking two-pointer scan whose `*` handling uses a
+ * single saved restart position, giving O(|str| * |pattern|) worst case with
+ * no catastrophic blow-up.
+ */
+declare function wildcardMatch(str: string, pattern: string): boolean;
+/**
+ * Resolve a permission query against one or more rulesets.
+ *
+ * Rulesets are concatenated in argument order (no mutation) and scanned
+ * front-to-back. The FIRST rule whose `permission` and `pattern` both match
+ * the query (via {@link wildcardMatch}) is returned. If no rule matches, a
+ * fail-safe default is returned: the queried permission/pattern with action
+ * `"ask"` (unknown → ask, never silently allow).
+ */
+declare function evaluate(permission: string, pattern: string, ...rulesets: Ruleset[]): Rule;
+/**
+ * Built-in command arity table. Maps a (possibly multi-word) command prefix
+ * to the number of leading tokens that constitute its "human-understandable
+ * command" for permission matching. Longest matching prefix wins.
+ *
+ * Frozen so the shared default cannot be mutated by callers.
+ */
+declare const BUILTIN_ARITY: Readonly<Record<string, number>>;
+/**
+ * Extract the human-understandable command from already-split, flag-free
+ * shell tokens.
+ *
+ * Strategy: try the longest prefix first. For `len` from `tokens.length` down
+ * to 1, if `tokens.slice(0, len).join(" ")` is a key in the (merged) arity
+ * table, return `tokens.slice(0, arity[thatPrefix])`. If the tokens are empty,
+ * return `[]`. Otherwise default to the first token only.
+ *
+ * `arity` is shallow-merged OVER the built-in table; neither the caller's
+ * object nor the built-in table is mutated.
+ */
+declare function commandPrefix(tokens: string[], arity?: Record<string, number> | undefined): string[];
+/**
+ * Derive the `pattern` to feed {@link evaluate} for a bash permission.
+ *
+ * Splits `command` on arbitrary whitespace, drops tokens that begin with `-`
+ * (flags are not conceptually part of the command identity), applies
+ * {@link commandPrefix}, and joins the result with single spaces.
+ */
+declare function commandPermissionKey(command: string): string;
+
+/**
+ * Git-backed project repository model.
+ *
+ * Faithful re-expression of the "every project is a git repo" persistence
+ * model: a project's metadata and conversation logs live AS committed files
+ * inside its repository. The commit graph IS the history — there is no
+ * in-memory snapshot ring (that is `workbench.ts`'s concern). The actual
+ * provider-specific git implementation is injected via `GitHostPort`; this
+ * module never performs git operations itself.
+ */
+interface ConversationSummary {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+}
+type DeploymentState = "idle" | "deploying" | "live" | "failed";
+interface DeploymentSummary {
+    commitSha: string;
+    commitMessage: string;
+    commitDate: string;
+    domain: string;
+    url: string;
+    deploymentId: string | null;
+    state: DeploymentState;
+}
+interface ProjectMetadata {
+    projectId: string;
+    name: string;
+    conversations: ConversationSummary[];
+    deployments: DeploymentSummary[];
+    productionDomain?: string | undefined;
+    productionDeploymentId?: string | undefined;
+}
+interface CommitRef {
+    sha: string;
+    message: string;
+    date: string;
+}
+interface GitHostPort {
+    getDefaultBranch(repoId: string): Promise<string>;
+    readFile(repoId: string, path: string, ref?: string | undefined): Promise<string | null>;
+    writeCommit(repoId: string, branch: string, files: Record<string, string>, message: string): Promise<CommitRef>;
+    listCommits(repoId: string, branch: string, limit?: number | undefined): Promise<CommitRef[]>;
+}
+/** Default-deny ownership predicate: cross-tenant access impossible unless wired. */
+type OwnsRepoPredicate = (tenantId: string, repoId: string) => boolean | Promise<boolean>;
+interface ProjectRepoDeps {
+    host: GitHostPort;
+    ownsRepo?: OwnsRepoPredicate | undefined;
+}
+type ProjectRepoErrorCode = "tenant_required" | "tenant_denied" | "metadata_malformed";
+declare class ProjectRepoError extends Error {
+    readonly code: ProjectRepoErrorCode;
+    constructor(code: ProjectRepoErrorCode, message: string);
+}
+declare const METADATA_PATH = "metadata.json";
+declare const CONVERSATIONS_DIR = "conversations";
+/** Parse JSONL content; tolerant of blank lines and trailing newline. */
+declare function parseJsonl(content: string): unknown[];
+/** Append one JSON line to existing JSONL content (immutable; never mutates input). */
+declare function appendJsonlLine(prev: string, value: unknown): string;
+/** Well-formed empty metadata — used when a project repo has no metadata yet. */
+declare function emptyProjectMetadata(projectId: string, name: string): ProjectMetadata;
+declare class ProjectRepo {
+    private readonly host;
+    private readonly ownsRepo;
+    constructor(deps: ProjectRepoDeps);
+    private authorize;
+    private defaultBranch;
+    readMetadata(tenantId: string, repoId: string): Promise<ProjectMetadata>;
+    writeMetadata(tenantId: string, repoId: string, meta: ProjectMetadata): Promise<CommitRef>;
+    appendConversationMessage(tenantId: string, repoId: string, conversationId: string, message: unknown): Promise<CommitRef>;
+    readConversationMessages(tenantId: string, repoId: string, conversationId: string): Promise<unknown[]>;
+    restoreAt(tenantId: string, repoId: string, sha: string): Promise<{
+        metadata: ProjectMetadata;
+    }>;
+    historyFromCommits(tenantId: string, repoId: string, limit?: number | undefined): Promise<CommitRef[]>;
+}
+
+/**
+ * Shareable-session model — a faithful re-expression of a coding agent's
+ * "share this session with a viewer" subsystem into Sailor's grammar:
+ * TypeScript, multi-tenant, no datastore lock-in, no transport/crypto vendor
+ * lock-in.
+ *
+ * ── Mental model ────────────────────────────────────────────────────────────
+ * The session OWNER keeps editing through the normal session API. Sharing only
+ * grants a *read-only viewer* an observation window. A {@link ShareRecord} is
+ * therefore always `readonly: true` — there is no writable share.
+ *
+ * ── Two access planes ───────────────────────────────────────────────────────
+ *  1. OWNER plane ({@link SessionShare.share} / {@link SessionShare.unshare}):
+ *     tenant-scoped. `tenantId` is mandatory, Zod-validated, and fails closed
+ *     on empty input. Cross-tenant reads are impossible by construction because
+ *     {@link ShareStore.getBySession} is tenant-keyed.
+ *
+ *  2. VIEWER plane ({@link SessionShare.verifyViewer}): PUBLIC. The viewer does
+ *     NOT have a tenantId — they only hold a link containing the share id plus
+ *     an unguessable secret. Security rests ENTIRELY on the secret being
+ *     high-entropy and compared in (length-independent) constant time. This is
+ *     why {@link ShareStore.getById} is tenant-agnostic: it is the public
+ *     lookup, gated by the secret rather than by tenancy. The secret never
+ *     reaches the owner caller path (it travels via the record + sync sink to
+ *     wherever the viewer URL is rendered).
+ *
+ * ── Threat model ────────────────────────────────────────────────────────────
+ *  • A viewer link leaking == full read access to that one session until the
+ *    owner revokes. Mitigation: revoke is immediate and `verifyViewer` denies
+ *    revoked shares; the secret must be CSPRNG-grade (enforced by the injected
+ *    {@link IdMint}, NOT by this module — the module never generates entropy).
+ *  • Secret guessing / timing oracle. Mitigation: {@link constantTimeEquals}
+ *    never early-returns on the first mismatched byte and folds length
+ *    differences into the same negative result.
+ *
+ * ── Sink-failure policy (DOCUMENTED CHOICE) ─────────────────────────────────
+ * Local persistence is the source of truth. `share`/`unshare` persist to the
+ * {@link ShareStore} FIRST, then best-effort emit to the {@link SyncSink}. If
+ * `sink.emit` rejects, the local store change STILL STANDS and the sink error
+ * is SWALLOWED (not rethrown) so a flaky remote can never roll back or hide a
+ * share/revoke the owner already committed. The owner call resolves normally;
+ * sync convergence is the remote's eventual-consistency concern, not the
+ * caller's. (Tested: a failing sink does not lose the persisted share/revoke.)
+ */
+/** A share is always read-only for viewers; the owner edits via the session. */
+interface ShareRecord {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly tenantId: string;
+    readonly url: string;
+    readonly secret: string;
+    readonly readonly: true;
+    readonly createdAt: string;
+    readonly revokedAt?: string | undefined;
+}
+/** Emitted to the sync sink whenever share state changes. */
+interface ShareSyncEvent {
+    readonly type: "share.created" | "share.revoked";
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly share: ShareRecord | null;
+}
+/**
+ * Caller-injected id/secret source. Tests pass a deterministic stub. Real
+ * callers MUST back `secret()` with a CSPRNG (≥128 bits) — this module
+ * consumes the port and never implements crypto itself.
+ */
+interface IdMint {
+    shareId(): string;
+    secret(): string;
+}
+/** Derives the public viewer URL from a share id. */
+type UrlBuilder = (shareId: string) => string;
+/**
+ * Best-effort propagation seam for share state changes. The real impl pushes to
+ * a remote; tests use a recorder. A rejecting `emit` MUST NOT corrupt local
+ * state — see the module-level sink-failure policy.
+ */
+interface SyncSink {
+    emit(event: ShareSyncEvent): Promise<void>;
+}
+/**
+ * Storage seam. `getBySession` is tenant-keyed and tenant-validated (owner
+ * plane). `getById` is the PUBLIC viewer lookup: the viewer has no tenantId, so
+ * it is tenant-agnostic and secret-gated by the caller, never tenant-gated.
+ */
+interface ShareStore {
+    put(rec: ShareRecord): Promise<void>;
+    getBySession(tenantId: string, sessionId: string): Promise<ShareRecord | null>;
+    getById(shareId: string): Promise<ShareRecord | null>;
+}
+/** Raised when sharing is globally disabled by the kill-switch. */
+declare class ShareDisabledError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Length-independent, full-scan equality. Never short-circuits on the first
+ * differing character; a length mismatch is folded into the same negative
+ * result by comparing against a fixed-length view so the loop count does not
+ * leak the secret length. Pure and unit-tested in isolation.
+ */
+declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * In-memory reference {@link ShareStore}. Mirrors the package's
+ * store/port convention (interface + in-memory ref impl, like
+ * `InMemoryRolloutStore`). Production swaps in a Postgres / `@nebutra/db`
+ * adapter satisfying the same interface — no infra change.
+ *
+ * Tenancy is structural: the by-session key embeds `tenantId`, so a different
+ * tenant resolves to a different key and gets `null`. A by-id index serves the
+ * public viewer path.
+ */
+declare class InMemoryShareStore implements ShareStore {
+    #private;
+    put(rec: ShareRecord): Promise<void>;
+    getBySession(tenantId: string, sessionId: string): Promise<ShareRecord | null>;
+    getById(shareId: string): Promise<ShareRecord | null>;
+}
+/** Result of a public viewer access attempt. */
+type ViewerVerdict = {
+    readonly ok: true;
+    readonly record: ShareRecord;
+} | {
+    readonly ok: false;
+    readonly reason: "not-found" | "revoked" | "bad-secret";
+};
+interface SessionShareOptions {
+    readonly store: ShareStore;
+    readonly mint: IdMint;
+    readonly urlBuilder: UrlBuilder;
+    readonly sink: SyncSink;
+    /** Kill-switch: when true, every `share()` throws {@link ShareDisabledError}. */
+    readonly disabled?: boolean | undefined;
+}
+/** Tenant-scoped owner API + public viewer verification. */
+declare class SessionShare {
+    #private;
+    constructor(opts: SessionShareOptions);
+    /**
+     * Share a session read-only. Fails closed on empty tenant/session. Honors the
+     * kill-switch. Idempotent: if a live (non-revoked) share exists, returns its
+     * url WITHOUT minting a new secret or emitting a duplicate `share.created`.
+     * Returns only the url — the secret never reaches the owner caller path.
+     */
+    share(tenantId: string, sessionId: string): Promise<{
+        url: string;
+    }>;
+    /**
+     * Revoke a session's share. Fails closed on empty tenant/session. Idempotent:
+     * a no-op (no emit) when no live share exists. On revoke, persists `revokedAt`
+     * and emits `share.revoked` with `share: null`.
+     */
+    unshare(tenantId: string, sessionId: string): Promise<void>;
+    /**
+     * PUBLIC viewer access. NO tenantId — the viewer has none; security rests
+     * entirely on the unguessable secret, compared in length-independent
+     * constant time. Unknown id → not-found; revoked share → revoked (even with
+     * the right secret); wrong secret → bad-secret. Fails closed on empty id.
+     */
+    verifyViewer(shareId: string, presentedSecret: string): Promise<ViewerVerdict>;
+}
+
+/**
+ * Skill distillation (INVERSE of ./skills).
+ *
+ * Where ./skills only *loads and discloses* authored skills, this module
+ * *creates and refines* them from lived experience — the "learn a skill
+ * from a trajectory" loop of a self-improving agent, re-expressed from
+ * first principles.
+ *
+ * The loop:
+ *   1. observe a trajectory (the ordered steps an agent took toward a goal)
+ *   2. gate it — only clean successes with real tool work distill (no noise)
+ *   3. build a deterministic distillation prompt from the trajectory
+ *   4. hand the prompt to an INJECTED synthesizer (the LLM call lives
+ *      outside this module — here it is a pure indirection)
+ *   5. assemble a tenant-scoped, least-privilege `DistilledSkill` whose
+ *      tool allowlist is clamped to tools the experience actually exercised
+ *   6. optionally refine an existing skill from a fresh success
+ *
+ * SECURITY: every entry point requires a non-empty `tenantId` and fails
+ * closed. Cross-tenant improvement is rejected. A distilled skill can never
+ * be granted a tool the trajectory did not use (least privilege). Pure
+ * data/logic; no host access; the model call is an injected indirection.
+ */
+
+interface TrajectoryStep {
+    readonly kind: "tool" | "message" | "observation";
+    readonly name?: string | undefined;
+    readonly input?: unknown;
+    readonly output?: unknown;
+}
+interface Trajectory {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly goal: string;
+    readonly steps: readonly TrajectoryStep[];
+    readonly outcome: "success" | "failure" | "partial";
+}
+/**
+ * Minimal structural shape — deliberately NOT imported from ./skills /
+ * ./definitions. It is structurally usable as a skill record consumed by
+ * the loader: a slug, frontmatter-shaped metadata, and a body text.
+ */
+interface DistilledSkillFrontmatter {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string | undefined;
+    readonly allowedTools: readonly string[];
+}
+interface DistilledSkillProvenance {
+    readonly sessionId: string;
+    readonly distilledAt: string;
+    readonly stepCount: number;
+    readonly version?: number | undefined;
+}
+interface DistilledSkill {
+    readonly slug: string;
+    readonly tenantId: string;
+    readonly sourceTier: "dynamic";
+    readonly frontmatter: DistilledSkillFrontmatter;
+    readonly body: string;
+    readonly provenance: DistilledSkillProvenance;
+}
+/** Injected LLM indirection — the model call is NOT implemented here. */
+type Synthesizer = (prompt: string) => Promise<{
+    name: string;
+    description: string;
+    whenToUse: string;
+    body: string;
+    allowedTools: string[];
+}>;
+/** kebab-case a free-form name into a stable slug. */
+declare function kebab(name: string): string;
+/** Deterministic distillation prompt — pure function of the trajectory. */
+declare function buildDistillationPrompt(traj: Trajectory): string;
+/** Deterministic improvement prompt — does not regress the existing skill. */
+declare function buildImprovementPrompt(existing: DistilledSkill, traj: Trajectory): string;
+declare const eligibilityOptionsSchema: z.ZodObject<{
+    minToolSteps: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type EligibilityOptions = z.input<typeof eligibilityOptionsSchema>;
+/**
+ * Only clean successes with real tool work and a non-trivial goal qualify.
+ * Pure. Don't manufacture noise skills from failures or trivial sessions.
+ */
+declare function isDistillable(traj: Trajectory, options?: EligibilityOptions): {
+    ok: boolean;
+    reason?: string;
+};
+interface DistillOptions {
+    /** Override the clock for deterministic provenance in tests. */
+    readonly now?: (() => Date) | undefined;
+    readonly eligibility?: EligibilityOptions | undefined;
+}
+/**
+ * Distill a `DistilledSkill` from a successful trajectory. The model call is
+ * the injected `synthesize`. The resulting tool allowlist is clamped to the
+ * intersection of what the synthesizer asked for and what the trajectory
+ * actually exercised — least privilege, always.
+ */
+declare function distillSkill(traj: Trajectory, synthesize: Synthesizer, opts?: DistillOptions): Promise<DistilledSkill>;
+/**
+ * Refine an existing distilled skill from a fresh successful trajectory for
+ * the same goal. Tenant must match (fail-closed). The tool allowlist is the
+ * union of the existing allowlist and the new trajectory's tools, then
+ * re-clamped to tools the new trajectory actually used (still least
+ * privilege). The body is replaced via the injected synthesizer with an
+ * "improve, don't regress" prompt. Version bumps.
+ */
+declare function improveSkill(existing: DistilledSkill, traj: Trajectory, synthesize: Synthesizer): Promise<DistilledSkill>;
+declare const nudgeOptionsSchema: z.ZodObject<{
+    minUnsavedSuccesses: z.ZodDefault<z.ZodNumber>;
+    minTurns: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type NudgeOptions = z.input<typeof nudgeOptionsSchema>;
+/**
+ * Deterministic heuristic: nudge the agent to persist learning once enough
+ * unsaved successes have accumulated, or enough turns have passed since the
+ * last distillation. Pure.
+ */
+declare function shouldNudgePersist(sessionStats: {
+    turnsSinceLastDistill: number;
+    unsavedSuccesses: number;
+}, options?: NudgeOptions): boolean;
+
+/**
+ * Workbench project-state model — an in-memory project filemap with
+ * snapshot / restore / history, mirroring the durable seam pattern used by
+ * {@link ./rollout-store-persistent.ts}: a tenant-scoped reference
+ * implementation sits behind a {@link ProjectPersistencePort} so a Postgres /
+ * object-store / `@nebutra/db` adapter can replace it without touching callers.
+ *
+ * Tenancy is structural: `tenantId` is part of every storage key AND
+ * Zod-validated at each boundary. Cross-tenant access is impossible by
+ * construction. All filemap ops are pure — they return NEW maps and never
+ * mutate caller input. Snapshots are deep copies, so editing the live project
+ * after taking a snapshot can never reach back and mutate history.
+ */
+/** A single entry in a project file map. */
+type FileEntry = {
+    kind: "file";
+    content: string;
+    binary: boolean;
+} | {
+    kind: "folder";
+};
+/** Project tree as a path → entry map. Treat as immutable. */
+type FileMap = Map<string, FileEntry>;
+/** A tenant-scoped project and its file tree. */
+interface Project {
+    tenantId: string;
+    projectId: string;
+    files: FileMap;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Frozen point-in-time copy of a project's files. */
+interface ProjectSnapshot {
+    id: string;
+    projectId: string;
+    tenantId: string;
+    files: FileMap;
+    at: string;
+}
+/** Result of comparing two projects by path + content. */
+interface ProjectDiff {
+    added: string[];
+    removed: string[];
+    changed: string[];
+}
+/**
+ * Structural shape of a parsed-plan file action. Declared locally on purpose:
+ * it intentionally mirrors a `{ type: "file", filePath, content }` plan action
+ * without importing sibling modules.
+ */
+type FileMutationInput = {
+    type: "file";
+    filePath: string;
+    content: string;
+} | {
+    type: "remove";
+    filePath: string;
+};
+/** Raised when a boundary identifier is missing or empty. */
+declare class WorkbenchError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A fresh, empty file map. */
+declare function emptyFileMap(): FileMap;
+/** Set (or overwrite) a file, auto-deriving folder entries. Returns a NEW map. */
+declare function setFile(map: FileMap, path: string, content: string): FileMap;
+/** Read a file/folder entry, or undefined. */
+declare function getFile(map: FileMap, path: string): FileEntry | undefined;
+/** Remove an entry. Returns a NEW map; original untouched. */
+declare function removeFile(map: FileMap, path: string): FileMap;
+/** All file (not folder) paths, sorted ascending. */
+declare function listFiles(map: FileMap): string[];
+/** Construct an empty tenant-scoped project. Empty ids fail closed. */
+declare function makeProject(tenant: string, project: string): Project;
+/**
+ * Land a parsed-plan file action into the workbench. Returns a NEW project
+ * with `updatedAt` bumped; the caller's project and mutation are never mutated.
+ */
+declare function applyFileMutation(project: Project, mutation: FileMutationInput): Project;
+/** Deep-copy snapshot — isolated from later edits to the live project. */
+declare function snapshot(project: Project): ProjectSnapshot;
+/** Replace project files from a snapshot. Tenant-checked; bumps updatedAt. */
+declare function restore(project: Project, snap: ProjectSnapshot): Project;
+/** Tenant-scoped, bounded snapshot ring buffer keyed by (tenant, project). */
+declare class SnapshotHistory {
+    #private;
+    constructor(cap?: number);
+    push(tenant: string, snap: ProjectSnapshot): void;
+    list(tenant: string, project: string): ProjectSnapshot[];
+    get(tenant: string, project: string, id: string): ProjectSnapshot | undefined;
+    latest(tenant: string, project: string): ProjectSnapshot | undefined;
+}
+/** Compare two projects by file path + content. Pure and cheap. */
+declare function diffProjects(a: Project, b: Project): ProjectDiff;
+/**
+ * Minimal durable seam. Implementations MUST persist projects tenant-scoped
+ * and make cross-tenant reads impossible. Mirrors {@link RolloutPersistencePort}.
+ */
+interface ProjectPersistencePort {
+    put(project: Project): Promise<void>;
+    get(tenant: string, project: string): Promise<Project | undefined>;
+}
+/** In-memory reference {@link ProjectPersistencePort}. Fails closed. */
+declare class InMemoryProjectStore implements ProjectPersistencePort {
+    #private;
+    put(project: Project): Promise<void>;
+    get(tenant: string, project: string): Promise<Project | undefined>;
+}
+
+export { type Action, type ActionEvent, type ActionPorts, ActionRunner, type ActionState, type ActionStatus, type AdmissionDeps, type AdmissionPolicy, type AdmissionReason, type AdmissionResult, type AllowlistMatch, type ApplyEditResult, type ArtifactEvent, type ArtifactStreamCallbacks, ArtifactStreamParser, BUDGET_RATIO, BUILTIN_ARITY, type BaseEstimator, type BuildAction, CLIP_TEXT_CHARS, CLIP_TOOL_CHARS, COMPACT_SENTINEL, CONCURRENCY, CONVERSATIONS_DIR, type ChannelAdapter, type ChannelCapabilities, ChannelGateway, type ChannelId, type ChannelMeta, ChannelRegistry, type ChatType, type Clock, CommitMessageError, type CommitRef, type CompactTranscriptInput, type CompiledAllowlist, type CompletionModel, type ConversationSummary, DEFAULT_ABORT_MS, DEFAULT_TEMPERATURE, type DataAction, type DebounceResult, type DeployState, type DeploymentCommitRef, type DeploymentRecord, type DeploymentState, DeploymentStateError, type DeploymentSummary, type DeploymentTimelineEntry, type DeploymentUiStatus, type DesignContext, type DiffFile, type DiffResult, type DistillOptions, type DistilledSkill, type DistilledSkillFrontmatter, type DistilledSkillProvenance, DuplicateChannelError, type EditBlock, type EditIntent, type EditMerger, EditType, type EligibilityOptions, type FileAction, type FileContext, type FileEntry, type FileInfo, type FileKind, type FileManifest, type FileMap, type FileMutationInput, type FuzzyMatch, type FuzzyMatchFn, type GenerateOptions, type GitContext, type GitHostPort, type GroupBinding, type Hunk, type IdMint, InMemoryProjectStore, InMemoryShareStore, InMemorySuggestionHistoryStore, type InboundAttachment, InboundDebouncer, type InboundLike, type InboundMessage, LARGE_SET, type LatestStatusInput, MAX_RETRIES, MEMORY_CONTEXT_BANNER_CLOSE, MEMORY_CONTEXT_BANNER_OPEN, METADATA_PATH, MIN_BUDGET, type MatchClassification, type MatchType, type MemoryContext, MemoryManager, type MemoryProvider, type MentionContext, type Message, type NudgeOptions, OUTPUT_TOKEN_CAP, type OutboundMessage, type OwnsRepoPredicate, type Part, type PlanAction, type Project, type ProjectDiff, type ProjectMetadata, type ProjectPersistencePort, ProjectRepo, type ProjectRepoDeps, ProjectRepoError, type ProjectRepoErrorCode, type ProjectSnapshot, REDUCE_DEPTH, type RankOptions, type RankedFuzzyResult, type RankedSuggestion, type RawScrapeResult, type ReplyOptions, type ReviewFinding, type ReviewModel, ReviewParseError, type ReviewScope, type Rule, type Ruleset, type RunQueueOptions, type ScrapeFormat, type ScrapeProvider, type SessionKeyOptions, type SessionRef, SessionShare, type SessionShareOptions, ShareDisabledError, type ShareRecord, type ShareStore, type ShareSyncEvent, type ShellAction, SnapshotHistory, type StartAction, StreamingContextScrubber, type SuggestionHistoryStore, type SuggestionItem, type SuggestionResults, type SuggestionType, type Summarize, type SyncSink, type Synthesizer, TOKEN_CORRECTION, type TenantContext, TenantMismatchError, type TextPart, type TimelineOpts, type ToolPart, type Trajectory, type TrajectoryStep, type Transcript, UnknownChannelError, type UrlBuilder, type ViewerVerdict, WorkbenchError, admitInbound, advanceState, analyzeEditIntent, appendJsonlLine, applyEditBlock, applyFileMutation, asChannelId, assertTenantContext, buildCommitPrompt, buildDistillationPrompt, buildEditInstructions, buildImprovementPrompt, buildMemoryContextBlock, buildReviewPrompt, classifyMatch, commandPermissionKey, commandPrefix, compactTranscript, compileAllowlist, computeBudget, constantTimeEquals, dedupeByText, deriveLatestStatus, deriveTimelineFromCommits, diffProjects, distillSkill, domainForCommit, emptyFileMap, emptyProjectMetadata, estimateTokens, evaluate, fallbackMerger, generateCommitMessage, getDeploymentStatus, getDeploymentTimeline, getFile, hasMention, historyCandidates, improveSkill, ingestDesignContext, isDistillable, kebab, listFiles, makeProject, matchIndices, matchIndicesCaseInsensitive, matchIndicesCaseInsensitiveIgnoreSpaces, matchWildcardPattern, matchWildcardPatternCaseInsensitive, matchesAllowlist, nextMode, normalizeScrapeResult, parseDiff, parseEditBlocks, parseFindings, parseJsonl, planEdit, rankByFuzzy, rankSuggestions, recordHistory, removeFile, renderClipped, replyTo, requiresMention, resolveBranchBase, resolveSessionKey, restore, runReview, sanitizeContext, selectFilesForEdit, setFile, shouldCompact, shouldNudgePersist, snapshot, split, stripFencedWrapper, stripFormatting, toGenerationSeed, unescapeEntities, wildcardMatch };