@tangle-network/agent-app 0.45.54 → 0.45.55

package/dist/interactions/index.d.ts

@@ -1,258 +1,18 @@
-import { e as InteractionRequestWire } from '../contract-OxG_jVMx.js';
-export { f as ChatFreeTextField, b as ChatInteraction, C as ChatInteractionField, a as ChatInteractionStatus, d as ChatSelectField, g as ComposerAnswerDelivery, h as INTERACTION_CANCEL_EVENT, i as INTERACTION_EVENT, j as INTERACTION_RESOLVED_EVENT, k as InteractionAnswerValue, I as InteractionAnswers, c as InteractionCancelData, l as InteractionPersistedPart, N as NoticeKind, m as NoticePersistedPart, P as ParseInteractionAnswersResult, n as ParseInteractionResult, o as canTransitionInteractionStatus, p as cancelStatusFor, q as composerAnswerData, r as composerAnswerDeliveries, s as dedupeQuestionInteractionsByContent, t as fieldAcceptsFreeText, u as interactionFromWireRequest, v as interactionPartKey, w as interactionToPersistedPart, x as isRenderableInteractionKind, y as isSafeInteractionFieldKey, z as isTerminalInteractionStatus, A as noticePart, B as noticePartKey, D as parseInteractionAnswers, E as parseInteractionCancel, F as parseInteractionRequest, G as persistedPartToInteraction, H as questionInteractionContentSignature, J as stampInteractionAnswers } from '../contract-OxG_jVMx.js';
-import { InteractionOutcome, InteractionData } from '@tangle-network/agent-interface';
-export { InteractionData, InteractionOutcome, InteractionRequest } from '@tangle-network/agent-interface';
-
 /**
- * Server-side client for the sandbox sidecar's generic interaction routes
- * (`GET/POST {runtimeUrl}/agents/sessions/{sessionId}/interactions`). The
- * pinned sandbox SDK exposes only the question-specific `session().answer()`
- * convenience; these raw calls are backend-agnostic (question/permission/plan,
- * any harness) and carry explicit outcomes (accepted/declined).
- *
- * Server-only: the sidecar bearer must never reach browser code. The caller
- * supplies the connection as a structural value (runtime URL + bearer +
- * session id) — no sandbox-SDK import, so any box-resolution strategy works.
- */
-
-/** Describe error details including code, message, and upstream HTTP status for sidecar interactions */
-interface SidecarInteractionsError {
-    code: string;
-    message: string;
-    /** Upstream HTTP status; 0 when the sidecar was unreachable. */
-    status: number;
-}
-/** Represent the outcome of sidecar interactions with success or error details */
-type SidecarInteractionsResult<T> = {
-    succeeded: true;
-    value: T;
-} | {
-    succeeded: false;
-    error: SidecarInteractionsError;
-};
-/** Where and how to reach one session's interaction registry. */
-interface SidecarInteractionsConnection {
-    runtimeUrl: string;
-    authToken?: string;
-    /** The sidecar agent-session id (the chat thread's session). */
-    sessionId: string;
-    /** Request deadline. A pending interaction means the box is up and the
-     *  sidecar responsive; a short default keeps a wedged runtime from stalling
-     *  the answering request. */
-    timeoutMs?: number;
-    /** Injection seam for tests; defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-}
-/** Outstanding (unanswered) interactions for the session — the sidecar's
- *  registry is authoritative, so this is the reconnect/reload source of truth. */
-declare function listSessionInteractions(connection: SidecarInteractionsConnection): Promise<SidecarInteractionsResult<InteractionRequestWire[]>>;
-/** Resolves one interaction. `data` is required by the sidecar only for
- *  `accepted` outcomes and is validated fail-closed against the answerSpec
- *  (400 INVALID_INTERACTION_ANSWER on mismatch). */
-declare function respondToSessionInteraction(connection: SidecarInteractionsConnection, response: {
-    id: string;
-    outcome: InteractionOutcome;
-    data?: InteractionData;
-}): Promise<SidecarInteractionsResult<void>>;
-/**
- * A sandbox session's lifecycle as the sidecar reports it.
- *
- * Every field is optional because the sidecar's payload has grown over time and
- * an older box answers with a subset. A reader that assumes a field is present
- * mis-reads an old box as terminal; the shapes below are read defensively for
- * that reason, not out of caution about types.
- */
-interface SidecarSessionState {
-    state?: string;
-    activeExecutionId?: string | null;
-    activeExecutionStatus?: string | null;
-    reconnectable?: boolean;
-    registryAuthority?: string | null;
-    terminalReason?: string | null;
-    lastEventAt?: string | number | null;
-    outstandingInteractions?: unknown[];
-}
-interface SidecarAbortResult {
-    cancelled: boolean;
-    reason?: string;
-    session?: SidecarSessionState;
-}
-/**
- * Whether a session has finished and will not produce more events.
- *
- * The three early returns are the ones that matter: a session with a live
- * execution, one the platform says is reconnectable, or one holding an
- * unanswered interaction is NOT terminal however its `state` string reads. An
- * app that treats such a session as finished abandons a turn mid-flight, or
- * leaves an agent blocked on an answer nobody will send.
- */
-declare function isTerminalSidecarState(state: {
-    state?: string;
-    activeExecutionId?: string | null;
-    reconnectable?: boolean;
-    outstandingInteractions?: unknown[];
-}): boolean;
-/** The session's current lifecycle, for reconnect and resume decisions. */
-declare function getSessionState(connection: SidecarInteractionsConnection): Promise<SidecarInteractionsResult<SidecarSessionState>>;
-/**
- * Cancel a running session.
- *
- * A 404 is reported as a SUCCESSFUL no-op rather than an error: the caller's
- * intent is "this session must not be running", and a session the sidecar has
- * never heard of already satisfies that. Surfacing it as a failure makes every
- * cancel-after-completion look like an outage.
- */
-declare function abortSession(connection: SidecarInteractionsConnection): Promise<SidecarInteractionsResult<SidecarAbortResult>>;
-
-/**
- * Framework-neutral interaction-answer endpoints, lifted out of the per-app
- * route files (gtm `api.chat.interactions`, legal `api.chat.interactions`,
- * tax `api.sessions.$id.interactions` — three byte-similar forks):
- *
- *   list(request)   — GET: outstanding asks for a live turn (reload restore)
- *   answer(request) — POST `{ id, outcome, data? }`: resolve one ask
- *
- * The product supplies ONE seam, `resolveConnection`: authenticate the caller,
- * authorize the thread/session, and resolve the sidecar connection. Everything
- * behind the seam is mechanism the forks kept re-fixing:
- *
- *   - body validation (safe field keys, typed values),
- *   - sidecar error → client contract mapping (every "the ask is gone" shape
- *     becomes 410 so the card flips to its expired state),
- *   - duplicate resolution: after answering, every other outstanding ask with
- *     the same content signature (a re-emitted duplicate) gets the same answer,
- *   - unblock verification: re-list and fail loud (503 INTERACTION_STILL_PENDING)
- *     when the sidecar accepted the POST but the ask is still open,
- *   - best-effort list: sidecar failures return `{ interactions: [],
- *     unavailable }` so a reload restore never breaks the live stream.
- *
- * Handlers return web-standard `Response`s (Workers, Node 18+, Deno) — no
- * router import anywhere.
+ * `@tangle-network/agent-app/interactions` — the human-in-the-loop interaction
+ * channel, both halves:
+ *
+ *   - the shared wire/persisted-part contract (`contract.ts`) a chat producer
+ *     and a chat client agree on (also re-exported from `./web-react` so
+ *     existing imports keep working),
+ *   - the server side (`sidecar.ts` + `route.ts`): a structural client for the
+ *     sidecar's `/agents/sessions/{id}/interactions` REST channel and
+ *     `createInteractionAnswerRoute()`, the list/answer endpoint factory that
+ *     retires the per-app route forks.
+ *
+ * The only shared-package peer is `@tangle-network/agent-interface` (schema +
+ * types). The sidecar connection is a structural value, never an SDK import.
  */
-
-/** Define possible outcomes for an interaction client as accepted or declined */
-type InteractionClientOutcome = 'accepted' | 'declined';
-/** Validate interaction answer body and return success with data or failure with error message */
-type InteractionAnswerBodyValidation = {
-    ok: true;
-    id: string;
-    outcome: InteractionClientOutcome;
-    data?: InteractionData;
-} | {
-    ok: false;
-    error: string;
-};
-/** Validates the client POST body: `{ id, outcome, data? }` with
- *  identifier-safe field keys and primitive/string-array values only. */
-declare function validateInteractionAnswerBody(body: Record<string, unknown>): InteractionAnswerBodyValidation;
-/** Provide logging methods for warnings and errors in interaction routes */
-type InteractionRouteLogger = Pick<Console, 'warn' | 'error'>;
-/** Sidecar error → the client-actionable contract. Every "the ask is gone"
- *  shape maps to 410 so the card flips to its expired state — a raw 404/409
- *  must never surface. */
-declare function mapInteractionRespondFailure(error: SidecarInteractionsError, logger?: InteractionRouteLogger): Response;
-/** The product seam's verdict for one request. `response` short-circuits with
- *  a product-authored Response (401/404/429…); `unavailable` means the caller
- *  is fine but the sandbox runtime is not reachable — the factory shapes that
- *  per intent (empty list for `list`, 503 for `answer`). */
-type InteractionConnectionResolution = {
-    ok: true;
-    connection: SidecarInteractionsConnection;
-} | {
-    ok: false;
-    response: Response;
-} | {
-    ok: false;
-    unavailable: string;
-};
-/** Define arguments required to resolve interaction connections based on request and intent */
-interface ResolveInteractionConnectionArgs {
-    request: Request;
-    intent: 'list' | 'answer';
-    /** The parsed, validated POST body (answer intent only) so the resolver can
-     *  read product routing fields (workspaceId/threadId) without re-parsing. */
-    body?: Record<string, unknown>;
-}
-/** Describe the arguments provided before processing an interaction answer including request, body, and connection details */
-interface BeforeInteractionAnswerArgs {
-    request: Request;
-    /** Original parsed body, including product routing fields. */
-    body: Record<string, unknown>;
-    /** Shared validation result; products never need to parse the answer again. */
-    answer: Extract<InteractionAnswerBodyValidation, {
-        ok: true;
-    }>;
-    connection: SidecarInteractionsConnection;
-    /** The route's single authoritative pre-answer sidecar snapshot. */
-    outstanding: InteractionRequestWire[];
-    answeredRequest?: InteractionRequestWire;
-    /** Content-identical questions that the shared route will also answer. */
-    duplicateRequests: InteractionRequestWire[];
-}
-/** Define arguments for durable interaction routes including a stable caller-created attempt key */
-interface DurableInteractionRouteArgs extends BeforeInteractionAnswerArgs {
-    /** Caller-created opaque identifier, stable across an ambiguous retry. */
-    attemptKey: string;
-}
-/** Crash-recoverable persistence lifecycle for the answer route. The product
- * binds this structural port to its OWN durable store — agent-app ships no
- * implementation (the `/durable-chat` module that used to provide one was
- * removed in 0.44.0 after nine repos produced zero imports of it). Existing
- * `beforeAnswer` behavior remains independent and unchanged. */
-interface DurableInteractionRoutePersistence<TPrepared = unknown> {
-    guarantee: 'reconciled' | 'best-effort';
-    prepare(args: DurableInteractionRouteArgs): TPrepared | Promise<TPrepared>;
-    /** Resolve an ambiguous retry (for example, the sidecar says the ask is
-     * already gone). Only `settled:true` permits the route to report success. */
-    reconcile(args: DurableInteractionRouteArgs & {
-        prepared: TPrepared;
-    }): {
-        settled: boolean;
-    } | Promise<{
-        settled: boolean;
-    }>;
-    /** Record the authority acknowledgement before terminal projection. */
-    acknowledge(args: DurableInteractionRouteArgs & {
-        prepared: TPrepared;
-        duplicateIds: string[];
-    }): void | Promise<void>;
-    /** Idempotently materialize terminal status and accepted values. */
-    finalize(args: DurableInteractionRouteArgs & {
-        prepared: TPrepared;
-        duplicateIds: string[];
-    }): void | Promise<void>;
-    fail?(args: DurableInteractionRouteArgs & {
-        prepared: TPrepared;
-        error: unknown;
-    }): void | Promise<void>;
-}
-/** Define options to authenticate, authorize, and manage persistence for interaction answer routes */
-interface InteractionAnswerRouteOptions {
-    /** Authenticate + authorize the caller and resolve the sidecar connection.
-     *  This is the only product-supplied step: session auth, workspace/thread
-     *  access, rate limiting, and box resolution all live here. */
-    resolveConnection: (args: ResolveInteractionConnectionArgs) => Promise<InteractionConnectionResolution>;
-    /** Product persistence seam that runs before the answer can unblock and
-     * finalize the agent turn. A throw aborts the request before any answer POST. */
-    beforeAnswer?: (args: BeforeInteractionAnswerArgs) => void | Promise<void>;
-    /** Additive crash-recoverable settlement. When configured, POST requires an
-     * `attemptKey`; accepted values are finalized only after sidecar ack. */
-    durable?: DurableInteractionRoutePersistence;
-    logger?: InteractionRouteLogger;
-}
-/** Define routes to list outstanding interactions and resolve answers for live turns */
-interface InteractionAnswerRoute {
-    /** GET — outstanding interactions for a live turn. Failures return an empty
-     *  list with an explicit `unavailable` code: the caller is a best-effort
-     *  reload restore, and the live/replayed stream must stay untouched when the
-     *  sidecar cannot answer. */
-    list: (request: Request) => Promise<Response>;
-    /** POST `{ id, outcome, data?, ...productFields }` — resolve one ask, answer
-     *  content-identical duplicates the same way, then re-list to prove the run
-     *  actually unblocked. */
-    answer: (request: Request) => Promise<Response>;
-}
-/** Create an interaction answer route that handles listing and resolving interaction requests */
-declare function createInteractionAnswerRoute(options: InteractionAnswerRouteOptions): InteractionAnswerRoute;
-
-export { type BeforeInteractionAnswerArgs, type DurableInteractionRouteArgs, type DurableInteractionRoutePersistence, type InteractionAnswerBodyValidation, type InteractionAnswerRoute, type InteractionAnswerRouteOptions, type InteractionClientOutcome, type InteractionConnectionResolution, InteractionRequestWire, type InteractionRouteLogger, type ResolveInteractionConnectionArgs, type SidecarAbortResult, type SidecarInteractionsConnection, type SidecarInteractionsError, type SidecarInteractionsResult, type SidecarSessionState, abortSession, createInteractionAnswerRoute, getSessionState, isTerminalSidecarState, listSessionInteractions, mapInteractionRespondFailure, respondToSessionInteraction, validateInteractionAnswerBody };
+export * from './contract';
+export * from './sidecar';
+export * from './route';

package/dist/interactions/route.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Framework-neutral interaction-answer endpoints, lifted out of the per-app
+ * route files (gtm `api.chat.interactions`, legal `api.chat.interactions`,
+ * tax `api.sessions.$id.interactions` — three byte-similar forks):
+ *
+ *   list(request)   — GET: outstanding asks for a live turn (reload restore)
+ *   answer(request) — POST `{ id, outcome, data? }`: resolve one ask
+ *
+ * The product supplies ONE seam, `resolveConnection`: authenticate the caller,
+ * authorize the thread/session, and resolve the sidecar connection. Everything
+ * behind the seam is mechanism the forks kept re-fixing:
+ *
+ *   - body validation (safe field keys, typed values),
+ *   - sidecar error → client contract mapping (every "the ask is gone" shape
+ *     becomes 410 so the card flips to its expired state),
+ *   - duplicate resolution: after answering, every other outstanding ask with
+ *     the same content signature (a re-emitted duplicate) gets the same answer,
+ *   - unblock verification: re-list and fail loud (503 INTERACTION_STILL_PENDING)
+ *     when the sidecar accepted the POST but the ask is still open,
+ *   - best-effort list: sidecar failures return `{ interactions: [],
+ *     unavailable }` so a reload restore never breaks the live stream.
+ *
+ * Handlers return web-standard `Response`s (Workers, Node 18+, Deno) — no
+ * router import anywhere.
+ */
+import { type InteractionData, type InteractionRequestWire } from './contract';
+import { type SidecarInteractionsConnection, type SidecarInteractionsError } from './sidecar';
+/** Define possible outcomes for an interaction client as accepted or declined */
+export type InteractionClientOutcome = 'accepted' | 'declined';
+/** Validate interaction answer body and return success with data or failure with error message */
+export type InteractionAnswerBodyValidation = {
+    ok: true;
+    id: string;
+    outcome: InteractionClientOutcome;
+    data?: InteractionData;
+} | {
+    ok: false;
+    error: string;
+};
+/** Validates the client POST body: `{ id, outcome, data? }` with
+ *  identifier-safe field keys and primitive/string-array values only. */
+export declare function validateInteractionAnswerBody(body: Record<string, unknown>): InteractionAnswerBodyValidation;
+/** Provide logging methods for warnings and errors in interaction routes */
+export type InteractionRouteLogger = Pick<Console, 'warn' | 'error'>;
+/** Sidecar error → the client-actionable contract. Every "the ask is gone"
+ *  shape maps to 410 so the card flips to its expired state — a raw 404/409
+ *  must never surface. */
+export declare function mapInteractionRespondFailure(error: SidecarInteractionsError, logger?: InteractionRouteLogger): Response;
+/** The product seam's verdict for one request. `response` short-circuits with
+ *  a product-authored Response (401/404/429…); `unavailable` means the caller
+ *  is fine but the sandbox runtime is not reachable — the factory shapes that
+ *  per intent (empty list for `list`, 503 for `answer`). */
+export type InteractionConnectionResolution = {
+    ok: true;
+    connection: SidecarInteractionsConnection;
+} | {
+    ok: false;
+    response: Response;
+} | {
+    ok: false;
+    unavailable: string;
+};
+/** Define arguments required to resolve interaction connections based on request and intent */
+export interface ResolveInteractionConnectionArgs {
+    request: Request;
+    intent: 'list' | 'answer';
+    /** The parsed, validated POST body (answer intent only) so the resolver can
+     *  read product routing fields (workspaceId/threadId) without re-parsing. */
+    body?: Record<string, unknown>;
+}
+/** Describe the arguments provided before processing an interaction answer including request, body, and connection details */
+export interface BeforeInteractionAnswerArgs {
+    request: Request;
+    /** Original parsed body, including product routing fields. */
+    body: Record<string, unknown>;
+    /** Shared validation result; products never need to parse the answer again. */
+    answer: Extract<InteractionAnswerBodyValidation, {
+        ok: true;
+    }>;
+    connection: SidecarInteractionsConnection;
+    /** The route's single authoritative pre-answer sidecar snapshot. */
+    outstanding: InteractionRequestWire[];
+    answeredRequest?: InteractionRequestWire;
+    /** Content-identical questions that the shared route will also answer. */
+    duplicateRequests: InteractionRequestWire[];
+}
+/** Define arguments for durable interaction routes including a stable caller-created attempt key */
+export interface DurableInteractionRouteArgs extends BeforeInteractionAnswerArgs {
+    /** Caller-created opaque identifier, stable across an ambiguous retry. */
+    attemptKey: string;
+}
+/** Crash-recoverable persistence lifecycle for the answer route. The product
+ * binds this structural port to its OWN durable store — agent-app ships no
+ * implementation (the `/durable-chat` module that used to provide one was
+ * removed in 0.44.0 after nine repos produced zero imports of it). Existing
+ * `beforeAnswer` behavior remains independent and unchanged. */
+export interface DurableInteractionRoutePersistence<TPrepared = unknown> {
+    guarantee: 'reconciled' | 'best-effort';
+    prepare(args: DurableInteractionRouteArgs): TPrepared | Promise<TPrepared>;
+    /** Resolve an ambiguous retry (for example, the sidecar says the ask is
+     * already gone). Only `settled:true` permits the route to report success. */
+    reconcile(args: DurableInteractionRouteArgs & {
+        prepared: TPrepared;
+    }): {
+        settled: boolean;
+    } | Promise<{
+        settled: boolean;
+    }>;
+    /** Record the authority acknowledgement before terminal projection. */
+    acknowledge(args: DurableInteractionRouteArgs & {
+        prepared: TPrepared;
+        duplicateIds: string[];
+    }): void | Promise<void>;
+    /** Idempotently materialize terminal status and accepted values. */
+    finalize(args: DurableInteractionRouteArgs & {
+        prepared: TPrepared;
+        duplicateIds: string[];
+    }): void | Promise<void>;
+    fail?(args: DurableInteractionRouteArgs & {
+        prepared: TPrepared;
+        error: unknown;
+    }): void | Promise<void>;
+}
+/** Define options to authenticate, authorize, and manage persistence for interaction answer routes */
+export interface InteractionAnswerRouteOptions {
+    /** Authenticate + authorize the caller and resolve the sidecar connection.
+     *  This is the only product-supplied step: session auth, workspace/thread
+     *  access, rate limiting, and box resolution all live here. */
+    resolveConnection: (args: ResolveInteractionConnectionArgs) => Promise<InteractionConnectionResolution>;
+    /** Product persistence seam that runs before the answer can unblock and
+     * finalize the agent turn. A throw aborts the request before any answer POST. */
+    beforeAnswer?: (args: BeforeInteractionAnswerArgs) => void | Promise<void>;
+    /** Additive crash-recoverable settlement. When configured, POST requires an
+     * `attemptKey`; accepted values are finalized only after sidecar ack. */
+    durable?: DurableInteractionRoutePersistence;
+    logger?: InteractionRouteLogger;
+}
+/** Define routes to list outstanding interactions and resolve answers for live turns */
+export interface InteractionAnswerRoute {
+    /** GET — outstanding interactions for a live turn. Failures return an empty
+     *  list with an explicit `unavailable` code: the caller is a best-effort
+     *  reload restore, and the live/replayed stream must stay untouched when the
+     *  sidecar cannot answer. */
+    list: (request: Request) => Promise<Response>;
+    /** POST `{ id, outcome, data?, ...productFields }` — resolve one ask, answer
+     *  content-identical duplicates the same way, then re-list to prove the run
+     *  actually unblocked. */
+    answer: (request: Request) => Promise<Response>;
+}
+/** Create an interaction answer route that handles listing and resolving interaction requests */
+export declare function createInteractionAnswerRoute(options: InteractionAnswerRouteOptions): InteractionAnswerRoute;

package/dist/interactions/sidecar.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Server-side client for the sandbox sidecar's generic interaction routes
+ * (`GET/POST {runtimeUrl}/agents/sessions/{sessionId}/interactions`). The
+ * pinned sandbox SDK exposes only the question-specific `session().answer()`
+ * convenience; these raw calls are backend-agnostic (question/permission/plan,
+ * any harness) and carry explicit outcomes (accepted/declined).
+ *
+ * Server-only: the sidecar bearer must never reach browser code. The caller
+ * supplies the connection as a structural value (runtime URL + bearer +
+ * session id) — no sandbox-SDK import, so any box-resolution strategy works.
+ */
+import type { InteractionData, InteractionOutcome, InteractionRequestWire } from './contract';
+/** Describe error details including code, message, and upstream HTTP status for sidecar interactions */
+export interface SidecarInteractionsError {
+    code: string;
+    message: string;
+    /** Upstream HTTP status; 0 when the sidecar was unreachable. */
+    status: number;
+}
+/** Represent the outcome of sidecar interactions with success or error details */
+export type SidecarInteractionsResult<T> = {
+    succeeded: true;
+    value: T;
+} | {
+    succeeded: false;
+    error: SidecarInteractionsError;
+};
+/** Where and how to reach one session's interaction registry. */
+export interface SidecarInteractionsConnection {
+    runtimeUrl: string;
+    authToken?: string;
+    /** The sidecar agent-session id (the chat thread's session). */
+    sessionId: string;
+    /** Request deadline. A pending interaction means the box is up and the
+     *  sidecar responsive; a short default keeps a wedged runtime from stalling
+     *  the answering request. */
+    timeoutMs?: number;
+    /** Injection seam for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/** Outstanding (unanswered) interactions for the session — the sidecar's
+ *  registry is authoritative, so this is the reconnect/reload source of truth. */
+export declare function listSessionInteractions(connection: SidecarInteractionsConnection): Promise<SidecarInteractionsResult<InteractionRequestWire[]>>;
+/** Resolves one interaction. `data` is required by the sidecar only for
+ *  `accepted` outcomes and is validated fail-closed against the answerSpec
+ *  (400 INVALID_INTERACTION_ANSWER on mismatch). */
+export declare function respondToSessionInteraction(connection: SidecarInteractionsConnection, response: {
+    id: string;
+    outcome: InteractionOutcome;
+    data?: InteractionData;
+}): Promise<SidecarInteractionsResult<void>>;
+/**
+ * A sandbox session's lifecycle as the sidecar reports it.
+ *
+ * Every field is optional because the sidecar's payload has grown over time and
+ * an older box answers with a subset. A reader that assumes a field is present
+ * mis-reads an old box as terminal; the shapes below are read defensively for
+ * that reason, not out of caution about types.
+ */
+export interface SidecarSessionState {
+    state?: string;
+    activeExecutionId?: string | null;
+    activeExecutionStatus?: string | null;
+    reconnectable?: boolean;
+    registryAuthority?: string | null;
+    terminalReason?: string | null;
+    lastEventAt?: string | number | null;
+    outstandingInteractions?: unknown[];
+}
+export interface SidecarAbortResult {
+    cancelled: boolean;
+    reason?: string;
+    session?: SidecarSessionState;
+}
+/**
+ * Whether a session has finished and will not produce more events.
+ *
+ * The three early returns are the ones that matter: a session with a live
+ * execution, one the platform says is reconnectable, or one holding an
+ * unanswered interaction is NOT terminal however its `state` string reads. An
+ * app that treats such a session as finished abandons a turn mid-flight, or
+ * leaves an agent blocked on an answer nobody will send.
+ */
+export declare function isTerminalSidecarState(state: {
+    state?: string;
+    activeExecutionId?: string | null;
+    reconnectable?: boolean;
+    outstandingInteractions?: unknown[];
+}): boolean;
+/** The session's current lifecycle, for reconnect and resume decisions. */
+export declare function getSessionState(connection: SidecarInteractionsConnection): Promise<SidecarInteractionsResult<SidecarSessionState>>;
+/**
+ * Cancel a running session.
+ *
+ * A 404 is reported as a SUCCESSFUL no-op rather than an error: the caller's
+ * intent is "this session must not be running", and a session the sidecar has
+ * never heard of already satisfies that. Surfacing it as a failure makes every
+ * cancel-after-completion look like an outage.
+ */
+export declare function abortSession(connection: SidecarInteractionsConnection): Promise<SidecarInteractionsResult<SidecarAbortResult>>;

package/dist/knowledge/index.d.ts

@@ -1,5 +1,3 @@
-import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement } from '@tangle-network/agent-eval';
-
 /**
  * Declarative knowledge-requirement gate.
  *
@@ -18,9 +16,9 @@ import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImport
  * — implements. Emits `@tangle-network/agent-eval`'s `KnowledgeRequirement[]`,
  * exactly what the agent-runtime control loop consumes.
  */
-
+import type { KnowledgeAcquisitionMode, KnowledgeFreshness, KnowledgeImportance, KnowledgeRequirement, KnowledgeRequirementCategory, KnowledgeSensitivity } from '@tangle-network/agent-eval';
 /** A declarative rule for satisfying a requirement from workspace state. */
-type SatisfiedByRule = 
+export type SatisfiedByRule = 
 /** A workspace-config field (dot-path) is set. `nonEmpty` requires a
  *  non-empty array/string rather than mere presence. */
 {
@@ -41,7 +39,7 @@ type SatisfiedByRule =
     allOf: SatisfiedByRule[];
 };
 /** Define the criteria and conditions required to satisfy a specific knowledge requirement */
-interface KnowledgeRequirementSpec {
+export interface KnowledgeRequirementSpec {
     id: string;
     description: string;
     category: KnowledgeRequirementCategory;
@@ -61,7 +59,7 @@ interface KnowledgeRequirementSpec {
 }
 /** The single seam a backend implements. `preset-cloudflare` provides a D1
  *  implementation; a custom stack supplies its own. */
-interface KnowledgeStateAccessor {
+export interface KnowledgeStateAccessor {
     /** Resolve a workspace-config field value (dot-path), or undefined. */
     config: (path: string) => unknown;
     /** Count rows in `table` for the active workspace, optionally status-filtered. */
@@ -72,7 +70,7 @@ interface KnowledgeStateAccessor {
     }) => number | Promise<number>;
 }
 /** Define a signal representing knowledge with confidence level and optional supporting evidence */
-interface KnowledgeSignal {
+export interface KnowledgeSignal {
     confidence: number;
     evidence?: string;
 }
@@ -81,12 +79,10 @@ interface KnowledgeSignal {
  * confidence from `signals` (default 0). Pure + sync: an eval harness can pass
  * hand-authored signals; production passes the output of {@link deriveSignals}.
  */
-declare function buildKnowledgeRequirements(specs: KnowledgeRequirementSpec[], signals?: Record<string, KnowledgeSignal>): KnowledgeRequirement[];
+export declare function buildKnowledgeRequirements(specs: KnowledgeRequirementSpec[], signals?: Record<string, KnowledgeSignal>): KnowledgeRequirement[];
 /**
  * Score every spec from workspace state. `derive` (code) wins; otherwise the
  * declarative `satisfiedBy` rule is evaluated through the accessor; a spec with
  * neither scores 0 (an acquisition gate, e.g. `search_web`).
  */
-declare function deriveSignals(specs: KnowledgeRequirementSpec[], ctx: KnowledgeStateAccessor): Promise<Record<string, KnowledgeSignal>>;
-
-export { type KnowledgeRequirementSpec, type KnowledgeSignal, type KnowledgeStateAccessor, type SatisfiedByRule, buildKnowledgeRequirements, deriveSignals };
+export declare function deriveSignals(specs: KnowledgeRequirementSpec[], ctx: KnowledgeStateAccessor): Promise<Record<string, KnowledgeSignal>>;