@tangle-network/agent-app 0.43.40 → 0.43.42

package/dist/durable-chat/index.d.ts

@@ -0,0 +1,419 @@
+import { C as ChatInteraction, g as InteractionAnswerValue, k as InteractionRequestWire, i as InteractionCancelData, j as InteractionPersistedPart } from '../contract-KfqJh_au.js';
+import { ChatPlan } from '../plans/index.js';
+import { DurableInteractionRouteArgs, DurableInteractionRoutePersistence } from '../interactions/index.js';
+import '@tangle-network/agent-interface';
+
+type DurableChatErrorCode = 'DURABLE_CHAT_BAD_REQUEST' | 'DURABLE_CHAT_UNAUTHORIZED' | 'DURABLE_CHAT_CONFLICT' | 'DURABLE_CHAT_UNAVAILABLE' | 'DURABLE_CHAT_GONE' | 'DURABLE_CHAT_NOT_FOUND';
+/** Typed, fail-loud errors for adapters and route seams. */
+declare class DurableChatError extends Error {
+    readonly code: DurableChatErrorCode;
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(code: DurableChatErrorCode, message: string, status: number, details?: unknown);
+}
+declare class DurableChatConflictError extends DurableChatError {
+    constructor(message?: string, details?: unknown);
+}
+declare class DurableChatUnavailableError extends DurableChatError {
+    constructor(message?: string, details?: unknown);
+}
+declare class DurableChatGoneError extends DurableChatError {
+    constructor(message?: string, details?: unknown);
+}
+
+/** An authorization-derived tenant/thread scope.  Consumers should only
+ * create this value after authenticating the request; the route never accepts
+ * an identity or scope from the request body. */
+type DurableChatScope = string & {
+    readonly __durableChatScope: unique symbol;
+};
+declare function createDurableChatScope(value: string): DurableChatScope;
+declare function durableChatScopeKey(scope: DurableChatScope): string;
+type DurablePlanDecision = 'approved' | 'rejected';
+type DurablePlanAuthorityDecision = DurablePlanDecision | 'approve' | 'reject';
+/** Projection retained by a durable store.  It is intentionally compatible
+ * with the browser `/plans` projection and adds no product-specific fields. */
+type DurablePlanProjection = ChatPlan & {
+    metadata?: Record<string, unknown>;
+    decidedBy?: string;
+};
+type DurablePlanCommandKey = string;
+type DurablePlanCommandState = 'claimed' | 'authority_committed' | 'finalized' | 'conflicted';
+interface DurablePlanCommandRecord {
+    scope: DurableChatScope;
+    planId: string;
+    revision: number;
+    decision: DurablePlanDecision;
+    commandKey: DurablePlanCommandKey;
+    authorityIdempotencyKey: string;
+    state: DurablePlanCommandState;
+    claimedAt: string;
+    authorityResult?: DurablePlanAuthorityResult;
+    receipt?: DurableFollowUpReceipt;
+    conflict?: string;
+}
+interface DurablePlanAuthorityCurrentResult {
+    /** Authoritative state. `null` means the authority has forgotten the plan. */
+    plan: DurablePlanProjection | null;
+    receipt?: DurableFollowUpReceipt;
+}
+interface DurableFollowUpReceipt {
+    /** Stable for a scope + plan + revision + decision. */
+    receiptId: string;
+    planId: string;
+    revision: number;
+    decision: DurablePlanDecision;
+    turnId: string;
+    state: string;
+    /** Authority's stable idempotency key, useful when reconciling. */
+    authorityIdempotencyKey: string;
+}
+interface DurablePlanAuthorityResult {
+    /** Authority's final plan projection. */
+    plan: DurablePlanProjection;
+    /** Sandbox-style follow-up result. */
+    followUp: {
+        turnId: string;
+        state: string;
+    };
+    /** True when the authority served a previously committed decision. */
+    idempotent?: boolean;
+    /** Stable authority operation id, if the provider has one. */
+    authorityId?: string;
+    receipt?: DurableFollowUpReceipt;
+}
+/** Structural port to Sandbox (or another durable plan authority). */
+interface DurablePlanAuthority {
+    current(args: {
+        scope: DurableChatScope;
+        planId: string;
+        revision?: number;
+    }): Promise<DurablePlanAuthorityCurrentResult | DurablePlanProjection | null>;
+    decide(args: {
+        scope: DurableChatScope;
+        planId: string;
+        revision: number;
+        decision: DurablePlanDecision;
+        feedback?: string;
+        idempotencyKey: string;
+    }): Promise<DurablePlanAuthorityResult>;
+}
+interface DurablePlanEffectRecord {
+    effectKey: string;
+    scope: DurableChatScope;
+    planId: string;
+    revision: number;
+    decision: DurablePlanDecision;
+    state: 'claimed' | 'completed' | 'error';
+    claimedAt: string;
+    completedAt?: string;
+    error?: string;
+}
+interface DurablePlanStore {
+    getPlanProjection(scope: DurableChatScope, planId: string, revision?: number): Promise<DurablePlanProjection | null>;
+    putPlanProjection(scope: DurableChatScope, projection: DurablePlanProjection): Promise<void>;
+    listPlanProjections?(scope: DurableChatScope, planId?: string): Promise<DurablePlanProjection[]>;
+    getPlanCommand(scope: DurableChatScope, commandKey: DurablePlanCommandKey): Promise<DurablePlanCommandRecord | null>;
+    claimPlanCommand(scope: DurableChatScope, command: DurablePlanCommandRecord): Promise<{
+        status: 'claimed';
+        record: DurablePlanCommandRecord;
+    } | {
+        status: 'existing';
+        record: DurablePlanCommandRecord;
+    } | {
+        status: 'conflict';
+        record?: DurablePlanCommandRecord;
+        reason: string;
+    }>;
+    recordPlanAuthorityResult(scope: DurableChatScope, commandKey: DurablePlanCommandKey, result: DurablePlanAuthorityResult, receipt: DurableFollowUpReceipt): Promise<void>;
+    finalizePlanCommand(scope: DurableChatScope, commandKey: DurablePlanCommandKey): Promise<void>;
+    getPlanEffect(scope: DurableChatScope, effectKey: string): Promise<DurablePlanEffectRecord | null>;
+    claimPlanEffect(scope: DurableChatScope, effect: DurablePlanEffectRecord): Promise<{
+        status: 'claimed';
+        record: DurablePlanEffectRecord;
+    } | {
+        status: 'existing';
+        record: DurablePlanEffectRecord;
+    }>;
+    completePlanEffect(scope: DurableChatScope, effectKey: string): Promise<void>;
+    failPlanEffect(scope: DurableChatScope, effectKey: string, error: string): Promise<void>;
+    getInteractionProjection(scope: DurableChatScope, interactionId: string): Promise<DurableInteractionProjection | null>;
+    upsertInteractionProjection(scope: DurableChatScope, projection: DurableInteractionProjection): Promise<DurableInteractionProjection>;
+    listInteractionProjections?(scope: DurableChatScope): Promise<DurableInteractionProjection[]>;
+    getAnswerIntent(scope: DurableChatScope, intentKey: string): Promise<DurableAnswerIntentRecord | null>;
+    claimAnswerIntent(scope: DurableChatScope, intent: DurableAnswerIntentRecord): Promise<{
+        status: 'claimed';
+        record: DurableAnswerIntentRecord;
+    } | {
+        status: 'existing';
+        record: DurableAnswerIntentRecord;
+    } | {
+        status: 'conflict';
+        record?: DurableAnswerIntentRecord;
+        reason: string;
+    }>;
+    acknowledgeAnswerIntent(scope: DurableChatScope, intentKey: string, acknowledgement: DurableInteractionAcknowledgement): Promise<void>;
+    /** Atomically settle the interaction projection (including semantic aliases)
+     * from the acknowledged intent and mark the intent finalized. */
+    finalizeAnswerIntent(scope: DurableChatScope, intentKey: string, guarantee?: DurableInteractionGuarantee): Promise<void>;
+    abortAnswerIntent(scope: DurableChatScope, intentKey: string, error: string): Promise<void>;
+}
+/** Alias used by adapters that store all durable chat state in one port. */
+type DurableChatStateStore = DurablePlanStore;
+type DurablePlanStateStore = DurablePlanStore;
+type DurablePlanCommandJournal = Pick<DurablePlanStore, 'getPlanCommand' | 'claimPlanCommand' | 'recordPlanAuthorityResult' | 'finalizePlanCommand'>;
+type DurableAnswerIntentJournal = Pick<DurablePlanStore, 'getAnswerIntent' | 'claimAnswerIntent' | 'acknowledgeAnswerIntent' | 'finalizeAnswerIntent' | 'abortAnswerIntent'>;
+interface DurableInteractionProjection extends ChatInteraction {
+    /** Sequence/event identity used to make ask replays idempotent. */
+    eventId?: string;
+    semanticKey?: string;
+    /** A cancel-before-ask row is a terminal tombstone. */
+    tombstone?: boolean;
+    updatedAt?: string;
+}
+type DurableAnswerIntentState = 'prepared' | 'acknowledged' | 'finalized' | 'aborted';
+interface DurableAnswerIntentRecord {
+    scope: DurableChatScope;
+    interactionId: string;
+    attemptKey: string;
+    intentKey: string;
+    outcome: 'accepted' | 'declined';
+    data?: Record<string, InteractionAnswerValue>;
+    state: DurableAnswerIntentState;
+    guarantee?: DurableInteractionGuarantee;
+    acknowledgement?: DurableInteractionAcknowledgement;
+    createdAt: string;
+    finalizedAt?: string;
+    error?: string;
+}
+interface DurableInteractionAcknowledgement {
+    acknowledged: true;
+    authorityId?: string;
+    status?: string;
+    at?: string;
+}
+type DurableInteractionGuarantee = 'reconciled' | 'best-effort';
+interface DurableInteractionSettlementOptions {
+    /** Caller-created and stable across retries/reconnects. */
+    attemptKey: string;
+    guarantee?: DurableInteractionGuarantee;
+    now?: () => string;
+}
+interface DurableInteractionSettlement {
+    prepare(scope: DurableChatScope, interactionId: string, outcome: 'accepted' | 'declined', data?: Record<string, InteractionAnswerValue>): Promise<DurableAnswerIntentRecord>;
+    acknowledge(scope: DurableChatScope, intentKey: string, acknowledgement?: Omit<DurableInteractionAcknowledgement, 'acknowledged'>): Promise<DurableAnswerIntentRecord>;
+    finalize(scope: DurableChatScope, intentKey: string): Promise<DurableAnswerIntentRecord>;
+    abort(scope: DurableChatScope, intentKey: string, error: string): Promise<DurableAnswerIntentRecord>;
+    reconcile(scope: DurableChatScope, intentKey: string): Promise<DurableAnswerIntentRecord | null>;
+}
+declare function normalizePlanDecision(value: unknown): DurablePlanDecision | null;
+declare function planCommandKey(planId: string, revision: number, decision: DurablePlanDecision): string;
+declare function planAuthorityIdempotencyKey(scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision): string;
+declare function planEffectKey(scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision): string;
+declare function stablePlanReceipt(scope: DurableChatScope, planId: string, revision: number, decision: DurablePlanDecision, result: Pick<DurablePlanAuthorityResult, 'followUp'>): DurableFollowUpReceipt;
+
+/**
+ * Reference adapter for tests and local development. It is intentionally
+ * process-local and non-production: there is no locking across processes,
+ * transaction, or crash recovery. Production adapters should implement the
+ * same port with a database/Workflow primitive and CAS at every claim.
+ */
+declare class InMemoryDurableChatStateStore implements DurablePlanStore {
+    private readonly plans;
+    private readonly currentPlans;
+    private readonly commands;
+    private readonly effects;
+    private readonly interactions;
+    private readonly interactionSemantic;
+    /** Duplicate event ids point at the canonical semantic interaction so all
+     * duplicate asks settle through one terminal row/attempt. */
+    private readonly interactionAliases;
+    private readonly answerIntents;
+    private scopePrefix;
+    private scopedKey;
+    private planKey;
+    private currentKey;
+    private commandKey;
+    private interactionKey;
+    private intentKey;
+    private effectKey;
+    getPlanProjection(scope: DurableChatScope, planId: string, revision?: number): Promise<DurablePlanProjection | null>;
+    listPlanProjections(scope: DurableChatScope, planId?: string): Promise<DurablePlanProjection[]>;
+    putPlanProjection(scope: DurableChatScope, projection: DurablePlanProjection): Promise<void>;
+    getPlanCommand(scope: DurableChatScope, commandKey: DurablePlanCommandKey): Promise<DurablePlanCommandRecord | null>;
+    claimPlanCommand(scope: DurableChatScope, command: DurablePlanCommandRecord): Promise<{
+        status: "conflict";
+        record: DurablePlanCommandRecord;
+        reason: string;
+    } | {
+        status: "claimed";
+        record: DurablePlanCommandRecord;
+        reason?: undefined;
+    } | {
+        status: "existing";
+        record: DurablePlanCommandRecord;
+        reason?: undefined;
+    }>;
+    recordPlanAuthorityResult(scope: DurableChatScope, commandKey: string, result: DurablePlanAuthorityResult, receipt: DurablePlanCommandRecord['receipt']): Promise<void>;
+    finalizePlanCommand(scope: DurableChatScope, commandKey: string): Promise<void>;
+    getPlanEffect(scope: DurableChatScope, effectKey: string): Promise<DurablePlanEffectRecord | null>;
+    claimPlanEffect(scope: DurableChatScope, effect: DurablePlanEffectRecord): Promise<{
+        status: "existing";
+        record: DurablePlanEffectRecord;
+    } | {
+        status: "claimed";
+        record: DurablePlanEffectRecord;
+    }>;
+    completePlanEffect(scope: DurableChatScope, effectKey: string): Promise<void>;
+    failPlanEffect(scope: DurableChatScope, effectKey: string, error: string): Promise<void>;
+    getInteractionProjection(scope: DurableChatScope, interactionId: string): Promise<DurableInteractionProjection | null>;
+    listInteractionProjections(scope: DurableChatScope): Promise<DurableInteractionProjection[]>;
+    upsertInteractionProjection(scope: DurableChatScope, projection: DurableInteractionProjection): Promise<DurableInteractionProjection>;
+    getAnswerIntent(scope: DurableChatScope, intentKey: string): Promise<DurableAnswerIntentRecord | null>;
+    claimAnswerIntent(scope: DurableChatScope, intent: DurableAnswerIntentRecord): Promise<{
+        status: "claimed";
+        record: DurableAnswerIntentRecord;
+        reason?: undefined;
+    } | {
+        status: "existing";
+        record: DurableAnswerIntentRecord;
+        reason?: undefined;
+    } | {
+        status: "conflict";
+        record: DurableAnswerIntentRecord;
+        reason: string;
+    }>;
+    acknowledgeAnswerIntent(scope: DurableChatScope, intentKey: string, acknowledgement: DurableAnswerIntentRecord['acknowledgement']): Promise<void>;
+    finalizeAnswerIntent(scope: DurableChatScope, intentKey: string, guarantee?: DurableAnswerIntentRecord['guarantee']): Promise<void>;
+    abortAnswerIntent(scope: DurableChatScope, intentKey: string, error: string): Promise<void>;
+}
+/** Short aliases retained for adapter authors who call this a durable chat
+ * store rather than a state store. Both names refer to the same non-production
+ * reference implementation. */
+declare const InMemoryDurableChatStore: typeof InMemoryDurableChatStateStore;
+declare function createInMemoryDurableChatStateStore(): InMemoryDurableChatStateStore;
+
+/** Apply an ask event. Event ids and semantic signatures make replays safe;
+ * a prior cancel creates a tombstone and cannot be resurrected by a late ask. */
+declare function upsertDurableInteractionAsk(store: DurablePlanStore, scope: DurableChatScope, request: InteractionRequestWire, options?: {
+    eventId?: string;
+    semanticKey?: string;
+    now?: () => string;
+}): Promise<DurableInteractionProjection>;
+/** Apply a cancel event. It is valid before the ask arrives and leaves a
+ * terminal tombstone so a delayed ask cannot re-open the card. */
+declare function recordDurableInteractionCancel(store: DurablePlanStore, scope: DurableChatScope, interactionId: string, reason?: string, options?: {
+    eventId?: string;
+    now?: () => string;
+}): Promise<DurableInteractionProjection>;
+/** Record an accepted/declined answer in the projection. The terminal
+ * transition is intentionally separate from answer-intent acknowledgement so
+ * callers can choose reconciled or best-effort delivery. */
+declare function recordDurableInteractionAnswer(store: DurablePlanStore, scope: DurableChatScope, interactionId: string, outcome: 'accepted' | 'declined', answers?: Record<string, InteractionAnswerValue>, options?: {
+    eventId?: string;
+    now?: () => string;
+}): Promise<DurableInteractionProjection>;
+interface DurableInteractionSettlementFactoryOptions extends DurableInteractionSettlementOptions {
+    store: DurablePlanStore;
+    /** Optional authority lookup used by `reconcile`; returning null leaves the
+     * intent prepared for a later durable retry. */
+    reconcileAuthority?: (args: {
+        scope: DurableChatScope;
+        intent: DurableAnswerIntentRecord;
+    }) => Promise<DurableInteractionAcknowledgement | null>;
+}
+/** Additive answer settlement primitive for wiring into `/interactions`.
+ * `attemptKey` belongs to the caller and is never generated from user data. */
+declare function createDurableInteractionSettlement(options: DurableInteractionSettlementFactoryOptions): DurableInteractionSettlement;
+/** Stable key helper exported for products implementing their own settlement
+ * loop. */
+declare function durableInteractionIntentKey(scope: DurableChatScope, interactionId: string, attemptKey: string): string;
+declare const applyDurableInteractionAsk: typeof upsertDurableInteractionAsk;
+declare const applyDurableInteractionCancel: typeof recordDurableInteractionCancel;
+declare const applyDurableInteractionAnswer: typeof recordDurableInteractionAnswer;
+
+interface DurableInteractionProjectionAdapter {
+    upsertAsk(request: InteractionRequestWire): Promise<void>;
+    cancel(cancel: InteractionCancelData): Promise<void>;
+    materialize(): Promise<InteractionPersistedPart[]>;
+}
+/** Binds an authorized durable scope/store to interaction lifecycle events. */
+declare function createDurableInteractionProjectionAdapter(options: {
+    store: DurablePlanStore;
+    scope: DurableChatScope;
+    now?: () => string;
+}): DurableInteractionProjectionAdapter;
+interface DurableChatEventProjection {
+    observe(event: unknown): void | Promise<void>;
+    materialize(): Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>;
+}
+/** Event projector usable with any `ChatTurnRouteProducer` through
+ * `withDurableChatProjection`. It tracks this turn's identities so older
+ * thread state is not copied into every assistant message. */
+declare function createDurableChatEventProjection(options: {
+    store: DurablePlanStore;
+    scope: DurableChatScope;
+    now?: () => string;
+}): DurableChatEventProjection;
+interface PreparedDurableInteractionAnswer {
+    scope: DurableChatScope;
+    settlement: DurableInteractionSettlement;
+    intent: DurableAnswerIntentRecord;
+}
+interface DurableInteractionRoutePersistenceBase {
+    store: DurablePlanStore;
+    scope(args: DurableInteractionRouteArgs): DurableChatScope | Promise<DurableChatScope>;
+    now?: () => string;
+}
+type CreateDurableInteractionRoutePersistenceOptions = (DurableInteractionRoutePersistenceBase & {
+    guarantee: 'reconciled';
+    reconcileAuthority(args: {
+        scope: DurableChatScope;
+        intent: DurableAnswerIntentRecord;
+        route: DurableInteractionRouteArgs;
+    }): Promise<DurableInteractionAcknowledgement | null>;
+}) | (DurableInteractionRoutePersistenceBase & {
+    guarantee: 'best-effort';
+    reconcileAuthority?: (args: {
+        scope: DurableChatScope;
+        intent: DurableAnswerIntentRecord;
+        route: DurableInteractionRouteArgs;
+    }) => Promise<DurableInteractionAcknowledgement | null>;
+});
+/** Ready-to-use bridge from `/interactions` to the durable state port. Only
+ * the reconciled variant may claim crash-safe behavior; best-effort is
+ * explicit in both its type and persisted intent. */
+declare function createDurableInteractionRoutePersistence(options: CreateDurableInteractionRoutePersistenceOptions): DurableInteractionRoutePersistence<PreparedDurableInteractionAnswer>;
+
+type DurablePlanAuthorization = DurableChatScope | {
+    scope: DurableChatScope;
+} | Response | null | undefined;
+interface DurablePlanRouteAuthorizeArgs {
+    request: Request;
+    operation: 'current' | 'decide';
+    planId?: string;
+}
+interface DurablePlanRouteOptions {
+    store: DurablePlanStore;
+    authority: DurablePlanAuthority;
+    /** Authentication and resource authorization. Scope must be derived by the
+     * caller from trusted credentials, never from client JSON. */
+    authorize: (args: DurablePlanRouteAuthorizeArgs) => Promise<DurablePlanAuthorization> | DurablePlanAuthorization;
+    /** Required idempotent side effect seam. The route claims `effectKey` before
+     * calling it; a product must make the callback safe to retry by that key. */
+    afterDecision: (args: {
+        scope: DurableChatScope;
+        plan: DurablePlanProjection;
+        receipt: DurableFollowUpReceipt;
+        effectKey: string;
+    }) => Promise<void> | void;
+    now?: () => string;
+    logger?: Pick<Console, 'warn' | 'error'>;
+}
+interface DurablePlanRoutes {
+    current(request: Request): Promise<Response>;
+    decide(request: Request): Promise<Response>;
+}
+declare function createDurablePlanRoutes(options: DurablePlanRouteOptions): DurablePlanRoutes;
+
+export { type CreateDurableInteractionRoutePersistenceOptions, type DurableAnswerIntentJournal, type DurableAnswerIntentRecord, type DurableAnswerIntentState, DurableChatConflictError, DurableChatError, type DurableChatErrorCode, type DurableChatEventProjection, DurableChatGoneError, type DurableChatScope, type DurableChatStateStore, DurableChatUnavailableError, type DurableFollowUpReceipt, type DurableInteractionAcknowledgement, type DurableInteractionGuarantee, type DurableInteractionProjection, type DurableInteractionProjectionAdapter, type DurableInteractionSettlement, type DurableInteractionSettlementFactoryOptions, type DurableInteractionSettlementOptions, type DurablePlanAuthority, type DurablePlanAuthorityCurrentResult, type DurablePlanAuthorityDecision, type DurablePlanAuthorityResult, type DurablePlanAuthorization, type DurablePlanCommandJournal, type DurablePlanCommandKey, type DurablePlanCommandRecord, type DurablePlanCommandState, type DurablePlanDecision, type DurablePlanEffectRecord, type DurablePlanProjection, type DurablePlanRouteAuthorizeArgs, type DurablePlanRouteOptions, type DurablePlanRoutes, type DurablePlanStateStore, type DurablePlanStore, InMemoryDurableChatStateStore, InMemoryDurableChatStore, type PreparedDurableInteractionAnswer, applyDurableInteractionAnswer, applyDurableInteractionAsk, applyDurableInteractionCancel, createDurableChatEventProjection, createDurableChatScope, createDurableInteractionProjectionAdapter, createDurableInteractionRoutePersistence, createDurableInteractionSettlement, createDurablePlanRoutes, createInMemoryDurableChatStateStore, durableChatScopeKey, durableInteractionIntentKey, normalizePlanDecision, planAuthorityIdempotencyKey, planCommandKey, planEffectKey, recordDurableInteractionAnswer, recordDurableInteractionCancel, stablePlanReceipt, upsertDurableInteractionAsk };

package/dist/durable-chat/index.js

@@ -0,0 +1,59 @@
+import {
+  DurableChatConflictError,
+  DurableChatError,
+  DurableChatGoneError,
+  DurableChatUnavailableError,
+  InMemoryDurableChatStateStore,
+  InMemoryDurableChatStore,
+  applyDurableInteractionAnswer,
+  applyDurableInteractionAsk,
+  applyDurableInteractionCancel,
+  createDurableChatEventProjection,
+  createDurableChatScope,
+  createDurableInteractionProjectionAdapter,
+  createDurableInteractionRoutePersistence,
+  createDurableInteractionSettlement,
+  createDurablePlanRoutes,
+  createInMemoryDurableChatStateStore,
+  durableChatScopeKey,
+  durableInteractionIntentKey,
+  normalizePlanDecision,
+  planAuthorityIdempotencyKey,
+  planCommandKey,
+  planEffectKey,
+  recordDurableInteractionAnswer,
+  recordDurableInteractionCancel,
+  stablePlanReceipt,
+  upsertDurableInteractionAsk
+} from "../chunk-ZU5GNSOJ.js";
+import "../chunk-XAWFPMAR.js";
+import "../chunk-SIXYZ2FB.js";
+export {
+  DurableChatConflictError,
+  DurableChatError,
+  DurableChatGoneError,
+  DurableChatUnavailableError,
+  InMemoryDurableChatStateStore,
+  InMemoryDurableChatStore,
+  applyDurableInteractionAnswer,
+  applyDurableInteractionAsk,
+  applyDurableInteractionCancel,
+  createDurableChatEventProjection,
+  createDurableChatScope,
+  createDurableInteractionProjectionAdapter,
+  createDurableInteractionRoutePersistence,
+  createDurableInteractionSettlement,
+  createDurablePlanRoutes,
+  createInMemoryDurableChatStateStore,
+  durableChatScopeKey,
+  durableInteractionIntentKey,
+  normalizePlanDecision,
+  planAuthorityIdempotencyKey,
+  planCommandKey,
+  planEffectKey,
+  recordDurableInteractionAnswer,
+  recordDurableInteractionCancel,
+  stablePlanReceipt,
+  upsertDurableInteractionAsk
+};
+//# sourceMappingURL=index.js.map

package/dist/durable-chat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/file-index-Bw_IQE_G.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Wire contract between the chat client (composer + `streamChatTurn`) and the
+ * assembled server vertical (`createChatTurnRoutes`). Import-free on purpose:
+ * `/web-react` re-exports these types into browser bundles, so nothing here may
+ * reach a Node builtin or an engine package.
+ *
+ * The part shape mirrors the sandbox SDK's `PromptInputPart` structurally
+ * (text | image | file with filename/mediaType/url/path/content) — derived
+ * here, not imported, so the client bundle never touches the SDK.
+ */
+interface ChatTurnTextPartInput {
+    type: 'text';
+    text: string;
+}
+/** A non-text prompt part the upload route hands back and the client echoes
+ *  on send. `url` carries an inline `data:` URI for small files; `path` is a
+ *  sandbox workspace reference for large ones (the >1 MiB gateway body cap
+ *  makes the two-step upload mandatory). */
+interface ChatTurnFilePartInput {
+    type: 'image' | 'file';
+    filename?: string;
+    mediaType?: string;
+    url?: string;
+    path?: string;
+    content?: string;
+}
+type ChatTurnPartInput = ChatTurnTextPartInput | ChatTurnFilePartInput;
+/** POST body for the turn route. `content` may be empty when `parts` carry the
+ *  message (an image-only send). Product routing fields (workspaceId etc.) ride
+ *  alongside and are read by the product's `authorize` seam. */
+interface ChatTurnRequestPayload {
+    threadId: string;
+    content?: string;
+    /** Non-text parts from the upload route, echoed back verbatim. */
+    parts?: ChatTurnFilePartInput[];
+    model?: string;
+    effort?: 'auto' | 'low' | 'medium' | 'high';
+    harness?: string;
+    /** Client-generated idempotency key for the logical turn (retry-safe). */
+    turnId?: string;
+    [key: string]: unknown;
+}
+/** `fetch` init for the turn route — the one place the client wire shape is
+ *  serialized, so composer glue and products never drift from the server's
+ *  parser. */
+declare function chatTurnRequestInit(payload: ChatTurnRequestPayload): RequestInit;
+declare const INLINE_PARTS_MAX_BYTES = 950000;
+declare class ChatTurnInputError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status?: number, code?: string);
+}
+declare function promptPartsByteSize(parts: ChatTurnPartInput[]): number;
+/** Throws `ChatTurnInputError` (413) when the parts' inline payload would blow
+ *  the gateway cap. Path-ref parts are tiny by construction and always pass. */
+declare function assertPromptPartsWithinCap(parts: ChatTurnPartInput[], maxBytes?: number): void;
+/** A file mention resolved from the composer's `@`-picker: the
+ *  workspace-relative path plus enough metadata to build a prompt part and
+ *  pointer text. `path` is the canonical identity — the mention pill's
+ *  `MentionItem.id` for the file kind (`/web-react`'s `useFileMentions`). */
+interface FileMention {
+    path: string;
+    name: string;
+    size?: number;
+}
+/** The `image/*` mime for a mention path by extension, or `undefined` for
+ *  anything not in the known image set (dispatched as `type: 'file'`). */
+declare function mediaTypeForMentionPath(path: string): string | undefined;
+interface FileMentionsToPartsOptions {
+    /** Resolve a mention's workspace-relative path to the absolute path the
+     *  dispatched part should carry (e.g. a host prefixing the in-box vault
+     *  root). Default: identity — the path travels unchanged. */
+    resolvePath?: (path: string) => string;
+}
+/** Maps resolved file mentions to path-only `ChatTurnFilePartInput`s —
+ *  `image` vs `file` by extension, and always a `path`, never a `url` (the
+ *  url/path XOR invariant: a mention is a sandbox path reference, never
+ *  inline bytes). */
+declare function fileMentionsToParts(mentions: readonly FileMention[], opts?: FileMentionsToPartsOptions): ChatTurnFilePartInput[];
+/** The agent-facing pointer block appended to the dispatched prompt — never
+ *  persisted in message `content`. Empty array → `''` so callers can append
+ *  unconditionally. This is the sole producer of that text: the current
+ *  turn's dispatch and any history projection built from the same mention
+ *  list both route through here, so the two can't drift apart. */
+declare function buildMentionPromptBlock(mentions: readonly Pick<FileMention, 'name' | 'path'>[]): string;
+/** Validates the untyped `parts` array off the wire. Returns the typed parts
+ *  or throws `ChatTurnInputError` (400) naming the offending entry. */
+declare function parseChatTurnParts(raw: unknown): ChatTurnFilePartInput[];
+
+/**
+ * `createSandboxFileIndexRoute` — server side of `@`-file-mentions
+ * (companion to sandbox-ui#184's composer mention primitive). Serves a flat,
+ * ignore-filtered listing of the workspace sandbox so `useFileMentions`
+ * (`/web-react`) can filter it client-side without a round trip per
+ * keystroke.
+ *
+ * Same seam style as `createUploadRoute`: `authorize({ request })` resolves a
+ * structural `{ tree(path, opts) }` handle (the shape of the sandbox SDK's
+ * `box.fs.tree`) — no SDK import here. `authorize` also carries the
+ * cold-box signal: a sandbox that isn't running yet answers `{ status:
+ * 'warming' }` directly, never provisions-and-waits inside this route.
+ */
+
+/** One entry from a structural `tree()` scan. Mirrors the sandbox SDK's
+ *  `FileTreeFile` (`path`, `size`, `mtime`) — `mtime` is unused here so it's
+ *  omitted from the structural match. */
+interface SandboxTreeFile {
+    path: string;
+    size: number;
+}
+/** Structural match of the sandbox SDK's `box.fs.tree` result shape
+ *  (`FileTreeResult`). `stats.truncated` is the only stat this route reads;
+ *  the rest ride through unread on the real SDK type. */
+interface SandboxTreeResult {
+    root: string;
+    files: SandboxTreeFile[];
+    stats: {
+        truncated: boolean;
+    };
+}
+/** Structural match of the sandbox SDK's `box.fs` tree surface. */
+interface SandboxFileTreeSource {
+    tree(path: string, options?: {
+        maxDepth?: number;
+    }): Promise<SandboxTreeResult>;
+}
+interface FileIndexReadyResponse {
+    status: 'ready';
+    /** Workspace-relative entries. Same shape as `FileMention` (`./wire`) so a
+     *  client can hand a response entry straight to `fileMentionsToParts` /
+     *  `buildMentionPromptBlock` without remapping. */
+    files: FileMention[];
+    /** True when either the underlying scan truncated (SDK-side cap) or this
+     *  route's own `maxEntries` cap trimmed the filtered list. The client
+     *  should show "showing first N files" rather than imply completeness. */
+    truncated: boolean;
+    generatedAt: string;
+}
+/** Cold-box answer: no provisioning happened, no files were scanned. The
+ *  client shows a warming state and retries — this route never blocks on a
+ *  box coming up. */
+interface FileIndexWarmingResponse {
+    status: 'warming';
+}
+type FileIndexResponse = FileIndexReadyResponse | FileIndexWarmingResponse;
+/** Short-TTL cache seam so repeat popover opens in the same session don't
+ *  re-scan the workspace. Host-provided (e.g. a KV binding); `key` is
+ *  whatever `authorize` returns as `cacheKey` — this route treats it opaquely. */
+interface FileIndexCache {
+    get(key: string): Promise<FileIndexReadyResponse | null> | FileIndexReadyResponse | null;
+    put(key: string, value: FileIndexReadyResponse, options?: {
+        ttlSeconds?: number;
+    }): Promise<void> | void;
+}
+type FileIndexAuthorization = {
+    status: 'ready';
+    /** Structural sandbox `fs` handle, usually `ensureWorkspaceSandbox(...)` → `box.fs`. */
+    fs: SandboxFileTreeSource;
+    /** Workspace root to index (e.g. `/home/agent`). */
+    root: string;
+    /** Extra ignore segments for this request, merged with the route's
+     *  defaults + `CreateSandboxFileIndexRouteOptions.ignore`. */
+    ignore?: string[];
+    /** Opaque cache key for the optional cache seam. Omit to skip caching
+     *  for this request (e.g. a workspace the host chooses not to cache). */
+    cacheKey?: string;
+} | {
+    status: 'warming';
+} | {
+    status: 'denied';
+    response: Response;
+};
+interface CreateSandboxFileIndexRouteOptions {
+    /** Authenticate the caller, resolve the sandbox `fs` handle, and signal a
+     *  cold box — never provisions or waits. */
+    authorize(args: {
+        request: Request;
+    }): Promise<FileIndexAuthorization>;
+    /** Extra ignore segments beyond the route's defaults (node_modules, .git,
+     *  dotfiles/dot-dirs, common build dirs). Matched as exact path-segment
+     *  names, same rule as the defaults. */
+    ignore?: string[];
+    /** Passed to `fs.tree` as `options.maxDepth`. Default 12. */
+    maxDepth?: number;
+    /** Hard cap on entries returned after filtering. Default 5000. */
+    maxEntries?: number;
+    /** Optional host-provided cache seam. */
+    cache?: FileIndexCache;
+    /** Cache TTL in seconds when `cache` is set. Default 20. */
+    cacheTtlSeconds?: number;
+}
+declare function createSandboxFileIndexRoute(options: CreateSandboxFileIndexRouteOptions): (request: Request) => Promise<Response>;
+
+export { type ChatTurnRequestPayload as C, type FileIndexAuthorization as F, INLINE_PARTS_MAX_BYTES as I, type SandboxFileTreeSource as S, type ChatTurnPartInput as a, type ChatTurnFilePartInput as b, ChatTurnInputError as c, type ChatTurnTextPartInput as d, type CreateSandboxFileIndexRouteOptions as e, type FileIndexCache as f, type FileIndexReadyResponse as g, type FileIndexResponse as h, type FileIndexWarmingResponse as i, type FileMention as j, type FileMentionsToPartsOptions as k, type SandboxTreeFile as l, type SandboxTreeResult as m, assertPromptPartsWithinCap as n, buildMentionPromptBlock as o, chatTurnRequestInit as p, createSandboxFileIndexRoute as q, fileMentionsToParts as r, mediaTypeForMentionPath as s, parseChatTurnParts as t, promptPartsByteSize as u };