@sixb/core 0.1.21 → 0.1.22

package/dist/storage/agents/types.d.ts

@@ -1,9 +1,12 @@
+import type { ActionSubject } from "../../actions/types";
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message";
 import type { AgentReasoning } from "../../agents/types";
-import type { Principal } from "../../auth";
+import type { Principal, UserPrincipal } from "../../auth";
+import type { FileRef } from "../../blob-storage/types";
 import type { SixbFailure } from "../../errors/types";
-import type { JsonValue } from "../../json";
-import type { LanguageModelRef } from "../../models";
+import type { JsonObject, JsonValue } from "../../json";
+import type { LanguageModelRef, LanguageModelTier, LanguageModelTierProbabilities } from "../../models";
+import type { ActionRunFailure, ActionRunParams } from "../action-runs/types";
 export type AgentThreadStatus = "active" | "archived";
 /** Immutable, non-secret application input. Never store resolved env or credentials here. */
 export type AgentThreadSandboxParams = Readonly<Record<string, JsonValue>>;
@@ -49,9 +52,24 @@ export type TransitionAgentThreadSandboxInput = {
     readonly expectedSandboxName: string;
     readonly name: string;
 });
+/**
+ * A conversation, or the thread a sub-agent works in. A sub-agent's thread is never listed, and
+ * whoever reads its conversation reads it.
+ */
+export type AgentThreadKind = "conversation" | "subagent";
+/** Where a sub-agent's thread comes from: its conversation, the turn that spawned it, and its key. */
+export interface AgentThreadParent {
+    readonly threadId: string;
+    /** The turn that spawned it. Its later runs work under the turns that go on with it. */
+    readonly spawnedBy: string;
+    readonly key: string;
+}
 export interface AgentThreadRecord {
     readonly id: string;
     readonly projectId: string;
+    readonly kind: AgentThreadKind;
+    /** Set exactly on a sub-agent's thread. */
+    readonly parent?: AgentThreadParent;
     /** Who owns/opened the thread. Reuses the canonical auth principal (gains `agent` later for free). */
     readonly ownerPrincipal: Principal;
     readonly title?: string;
@@ -75,10 +93,51 @@ export interface CreateAgentThreadInput {
     readonly createdAt?: Date;
     readonly updatedAt?: Date;
 }
+/**
+ * A new thread holding a copy of another thread's finished messages. A turn still running is left
+ * behind: what came from its trigger message on is not copied. Copies keep their `seq`, content,
+ * author and `runId`, and get new ids. Runs are not copied, so the fork's runs, usage and cost are
+ * its own; copied answers still show their run's diagnostics.
+ *
+ * Only the latest checkpoint the copy can use comes along, so the markers of earlier compactions
+ * are not in the fork. The fork has no `lastMessageAt` until its first new message, so it sorts
+ * by its creation.
+ */
+export interface ForkAgentThreadInput {
+    readonly projectId: string;
+    /** The thread whose history is copied. */
+    readonly sourceThreadId: string;
+    readonly id: string;
+    readonly ownerPrincipal: Principal;
+    readonly title?: string;
+    readonly sandboxParams?: AgentThreadSandboxParams;
+    /** Provider name of the fork's new sandbox; given exactly when `sandboxParams` is. */
+    readonly sandboxName?: string;
+    /**
+     * The source's shared artifacts, each id mapped to its copy's: the copied messages and summary
+     * name the copies instead.
+     */
+    readonly artifactCopies?: Readonly<Record<string, string>>;
+    readonly createdAt?: Date;
+}
+/** A conversation's sub-agent threads, oldest first. */
+export interface ListAgentThreadChildrenInput {
+    readonly projectId: string;
+    /** The conversation. */
+    readonly parentThreadId: string;
+    /** Only those this turn spawned. */
+    readonly parentRunId?: string;
+    /** At most this many, 100 by default. */
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/** Conversations only: a sub-agent's thread is read through its conversation. */
 export interface ListAgentThreadsInput {
     readonly projectId: string;
     readonly statuses?: readonly AgentThreadStatus[];
     readonly ownerPrincipal?: Principal;
+    /** Only the threads this user takes part in. */
+    readonly participantPrincipal?: UserPrincipal;
     readonly limit?: number;
     readonly offset?: number;
     readonly order?: "asc" | "desc";
@@ -88,6 +147,35 @@ export interface ListAgentThreadsResult {
     readonly hasMore: boolean;
     readonly total: number;
 }
+export interface AgentThreadParticipantRecord {
+    readonly projectId: string;
+    readonly threadId: string;
+    readonly principal: UserPrincipal;
+    readonly addedAt: Date;
+    readonly addedBy: Principal;
+}
+export interface AddAgentThreadParticipantsInput {
+    readonly projectId: string;
+    readonly threadId: string;
+    /**
+     * Distinct users, checked by the caller. Someone already taking part keeps when and by whom they
+     * were first added.
+     */
+    readonly principals: readonly UserPrincipal[];
+    readonly addedBy: Principal;
+    /** Refused with `participant_limit`, adding no one, when the thread would hold more. */
+    readonly maxParticipants: number;
+    readonly addedAt?: Date;
+}
+export interface RemoveAgentThreadParticipantInput {
+    readonly projectId: string;
+    readonly threadId: string;
+    readonly principal: UserPrincipal;
+}
+export interface ListAgentThreadParticipantsInput {
+    readonly projectId: string;
+    readonly threadIds: readonly string[];
+}
 /** Lifecycle shared by every durable agent execution, conversational or workflow-owned. */
 export type AgentExecutionStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
 export type AgentRunStatus = AgentExecutionStatus;
@@ -97,11 +185,13 @@ export declare const AGENT_RUN_FAILURE_CODES: readonly ["internal.unexpected", "
 export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number];
 /**
  * Why a run ended — Sixb's provider-independent vocabulary. It includes model-loop reasons plus
- * platform-level endings such as `timeout`, or `interrupted` for a turn whose worker died before
- * finishing it, so reads remain typed and exhaustive. `other` and `unknown` preserve terminal state
+ * platform-level endings such as `timeout`, `interrupted` for a turn whose worker died before
+ * finishing it, `awaiting_approval` for a succeeded turn that paused on calls waiting for its
+ * requester, or `awaiting_answer` for a succeeded sub-agent that paused on a question its parent
+ * answers in a later turn, so reads remain typed and exhaustive. `other` and `unknown` preserve terminal state
  * when a provider adds a new reason.
  */
-export declare const AGENT_RUN_FINISH_REASONS: readonly ["stop", "length", "content-filter", "tool-calls", "timeout", "interrupted", "error", "other", "unknown"];
+export declare const AGENT_RUN_FINISH_REASONS: readonly ["stop", "length", "content-filter", "tool-calls", "timeout", "interrupted", "awaiting_approval", "awaiting_answer", "error", "other", "unknown"];
 export type AgentRunFinishReason = (typeof AGENT_RUN_FINISH_REASONS)[number];
 /**
  * Coerce an external finish-reason string — a DB column or an SDK value — to {@link
@@ -109,7 +199,7 @@ export type AgentRunFinishReason = (typeof AGENT_RUN_FINISH_REASONS)[number];
  */
 export declare function coerceAgentRunFinishReason(value: string | null | undefined): AgentRunFinishReason | undefined;
 /** Stable, user-facing diagnostics emitted by the platform while executing a run. */
-export declare const AGENT_RUN_DIAGNOSTIC_CODES: readonly ["step_limit_reached"];
+export declare const AGENT_RUN_DIAGNOSTIC_CODES: readonly ["step_limit_reached", "output_limit_reached"];
 /**
  * Closed on purpose, and the wire is closed with it.
  *
@@ -167,28 +257,67 @@ export interface ConversationAgentRunRecord extends AgentRunRecordBase {
 /** Immutable, serialisable model selection and requester settings for one conversational turn. */
 export interface ConversationAgentRunSpec {
     readonly model: LanguageModelRef;
+    /** With tiers, the tier of the model the turn runs on. */
+    readonly tier?: LanguageModelTier;
+    /**
+     * How likely the decision model judged each tier, when Sixb picked the turn's model. Kept to
+     * calibrate the thresholds the tier is picked from (`heavy` from 0.4, `light` from 0.8).
+     */
+    readonly tierProbabilities?: LanguageModelTierProbabilities;
     readonly reasoning?: AgentReasoning;
     /** Canonical IANA time zone of the requester. Absent uses the project time zone. */
     readonly timeZone?: string;
     /** Canonical BCP 47 language of the requester. Absent uses the project locale. */
     readonly locale?: string;
+    /** What the turn may change without asking its requester. Absent on older runs: `auto`. */
+    readonly approvalMode?: AgentApprovalMode;
 }
 /** Immutable, serialisable child configuration captured before dispatch. */
 export interface SubagentRunSpec {
     readonly model: LanguageModelRef;
+    /** With tiers, the tier of the model the child runs on. Absent on children admitted before it. */
+    readonly tier?: LanguageModelTier;
     readonly reasoning?: AgentReasoning;
     /** Focused task supplied by the parent Agent. */
     readonly task: string;
     /** Project tools available when the child was admitted. Runtime tools are injected separately. */
     readonly toolNames: readonly string[];
     readonly maxSteps: number;
+    /** The parent turn's mode, copied when the child was admitted. Absent: `auto`. */
+    readonly approvalMode?: AgentApprovalMode;
+    /**
+     * ISO time the parent turn times out at. The child's wall clock ends there, so its wait in the
+     * queue counts against it. Absent on children admitted before it: the worker's turn timeout.
+     */
+    readonly deadline?: string;
+    /** The parent turn's requester settings. Absent uses the project's. */
+    readonly timeZone?: string;
+    readonly locale?: string;
+    /** Files the parent handed over, copied into the child's sandbox at these paths. */
+    readonly files?: readonly SubagentRunFile[];
+}
+/** A file a parent and its child hand each other, stored once and copied into a sandbox. */
+export interface SubagentRunFile {
+    /** Relative, `/`-separated, without `.` or `..` segments. */
+    readonly path: string;
+    readonly fileRef: FileRef;
 }
 /** Durable child output returned to its parent by `wait_agent`. */
 export interface SubagentRunResult {
+    /** Empty only for a child that paused on its held calls before it answered. */
     readonly text: string;
+    /** What the child wrote under `out/`, by path relative to it. */
+    readonly files?: readonly SubagentRunFile[];
+    /** Why none of what it wrote under `out/` came back, and what to do about it. */
+    readonly filesError?: string;
 }
 export interface SubagentRunRecord extends AgentRunRecordBase {
     readonly kind: "subagent";
+    /** The child's own thread, which holds its task and its work. */
+    readonly threadId: string;
+    /** The message of its thread that started the run. */
+    readonly triggerMessageId: string;
+    /** The conversation turn the child runs under: its deadline, mode and cancellation. */
     readonly parentRunId: string;
     /** Stable parent-selected key that makes repeated tool execution idempotent. */
     readonly spawnKey: string;
@@ -214,6 +343,16 @@ export interface CreateSubagentRunInput {
     readonly parentExecutionToken: string;
     readonly spawnKey: string;
     readonly spec: SubagentRunSpec;
+    /**
+     * The child's thread. Its first run creates it, owned by the conversation's owner; a later run
+     * goes into it, and is refused while another run of the thread is active.
+     */
+    readonly thread: {
+        readonly id: string;
+        readonly create: boolean;
+    };
+    /** The user message that starts the run, appended to the child's thread with the run's id. */
+    readonly trigger: Pick<AppendAgentMessageInput, "id" | "parts" | "metadata">;
     /** Internal safety bound enforced atomically across worker processes. */
     readonly maxActiveChildren: number;
     readonly createdAt?: Date;
@@ -260,7 +399,8 @@ export type FinishAgentRunInput = {
     readonly executionToken: string;
     readonly status: "failed" | "cancelled";
     readonly modelId?: string;
-    readonly finishReason?: AgentRunFinishReason;
+    /** Only a succeeded run pauses. */
+    readonly finishReason?: Exclude<AgentRunFinishReason, "awaiting_approval" | "awaiting_answer">;
     readonly diagnostics?: readonly AgentRunDiagnostic[];
     readonly error?: SixbFailure<AgentRunFailureCode>;
     readonly completedAt?: Date;
@@ -279,6 +419,15 @@ export interface ListAgentRunsInput {
     readonly offset?: number;
     readonly order?: "asc" | "desc";
 }
+export interface ListThreadSubagentsInput {
+    readonly projectId: string;
+    /** The conversation whose turns spawned them. */
+    readonly threadId: string;
+    readonly spawnKey?: string;
+    readonly finishReason?: AgentRunFinishReason;
+    /** At most this many, 100 by default. */
+    readonly limit?: number;
+}
 export interface ListAgentRunsResult {
     readonly runs: readonly AgentRunRecord[];
     readonly hasMore: boolean;
@@ -289,7 +438,11 @@ export interface AgentMessageRecord {
     readonly id: string;
     readonly projectId: string;
     readonly threadId: string;
-    /** The run that produced this message; `null` for user-authored messages. */
+    /**
+     * The run that produced this message; `null` for user-authored messages. In a sub-agent's thread
+     * every message has one, its trigger too, so a run's messages are deleted whole. A message copied
+     * by a fork keeps the run that produced it, which belongs to the thread it was copied from.
+     */
     readonly runId: string | null;
     readonly role: AgentMessageRole;
     /** Principal that authored this persisted message: caller for user messages, agent identity later for assistant messages. */
@@ -346,6 +499,7 @@ export interface AgentContextCheckpointRecord {
     readonly id: string;
     readonly projectId: string;
     readonly threadId: string;
+    /** A fork's copy keeps the run that wrote the summary, in the thread it was copied from. */
     readonly createdByRunId: string;
     readonly previousCheckpointId?: string;
     readonly reason: AgentContextCheckpointReason;
@@ -383,6 +537,11 @@ export interface AgentThreadStore {
     /** Atomic run-fenced transition, or explicit idle-thread recreation. */
     transitionSandbox(input: TransitionAgentThreadSandboxInput): Promise<AgentThreadSandboxState>;
     create(input: CreateAgentThreadInput): Promise<AgentThreadRecord>;
+    /**
+     * Create a thread holding a copy of another's finished history, in one transaction. The source's
+     * sub-agent threads are not copied, and a sub-agent's thread is refused.
+     */
+    fork(input: ForkAgentThreadInput): Promise<AgentThreadRecord>;
     getById(params: {
         projectId: string;
         id: string;
@@ -393,11 +552,29 @@ export interface AgentThreadStore {
         readonly ids: readonly string[];
     }): Promise<readonly AgentThreadRecord[]>;
     list(input: ListAgentThreadsInput): Promise<ListAgentThreadsResult>;
+    /** The sub-agents' threads of a conversation, by creation and id, all of them or one turn's. */
+    listChildren(input: ListAgentThreadChildrenInput): Promise<readonly AgentThreadRecord[]>;
+    /**
+     * Add users atomically and return every participant of the thread afterwards. A sub-agent's
+     * thread has none: its readers are its conversation's.
+     */
+    addParticipants(input: AddAgentThreadParticipantsInput): Promise<readonly AgentThreadParticipantRecord[]>;
+    /** Whether the user took part until now. */
+    removeParticipant(input: RemoveAgentThreadParticipantInput): Promise<boolean>;
+    /** The participants of these threads, oldest first, then by user id and thread id. */
+    listParticipants(input: ListAgentThreadParticipantsInput): Promise<readonly AgentThreadParticipantRecord[]>;
 }
 export interface AgentRunStore {
-    /** Persist a queued run and atomically claim the thread's single-flight slot. */
+    /**
+     * Persist a queued turn and atomically claim the thread's single-flight slot. A sub-agent's
+     * thread takes only child runs.
+     */
     create(input: CreateAgentRunInput): Promise<ConversationAgentRunRecord>;
-    /** Persist or replay one idempotent child run while atomically enforcing parent fan-out. */
+    /**
+     * Persist or replay one idempotent child run while atomically enforcing parent fan-out. In one
+     * transaction it creates the child's thread or takes it (single-flight, as a conversation), then
+     * appends the trigger and the run.
+     */
     createSubagent(input: CreateSubagentRunInput): Promise<SubagentRunRecord>;
     /** Transition a queued run to running and install the first delivery's execution token. */
     start(input: StartAgentRunInput): Promise<AgentRunRecord>;
@@ -410,7 +587,12 @@ export interface AgentRunStore {
      * Implementations must fence by token and must never move the expiration backwards.
      */
     confirmExecutionOwnership(input: ConfirmAgentRunExecutionOwnershipInput): Promise<AgentRunRecord>;
-    /** Finalize a run and release the thread's `activeRunId`. */
+    /**
+     * Finalize a run and release the thread's `activeRunId`. `finishReason: "awaiting_approval"`
+     * needs a call the run holds (see `approvals.holdsRun`). A turn that ends any other way cancels
+     * its pending approvals and stops resuming on the rest; a child that fails or is cancelled
+     * cancels its own pending ones.
+     */
     finish(input: FinishAgentRunInput): Promise<AgentRunRecord>;
     getById(params: {
         projectId: string;
@@ -420,6 +602,11 @@ export interface AgentRunStore {
         projectId: string;
         ids: readonly string[];
     }): Promise<readonly AgentRunRecord[]>;
+    /**
+     * The children of a conversation's turns, the latest turn's first, by its effective start, and
+     * within a turn the latest admitted first. Read by key (one per turn) or by finish reason.
+     */
+    listThreadSubagents(input: ListThreadSubagentsInput): Promise<readonly SubagentRunRecord[]>;
     list(input: ListAgentRunsInput): Promise<ListAgentRunsResult>;
 }
 export interface AgentMessageStore {
@@ -439,9 +626,10 @@ export interface AgentContextCheckpointStore {
      * Repeating the same payload for the same creating run is idempotent.
      */
     create(input: CreateAgentContextCheckpointInput): Promise<AgentContextCheckpointRecord>;
-    /** Return checkpoints created by the requested runs, in first-occurrence input order. */
+    /** The thread's checkpoints created by the requested runs, in first-occurrence input order. */
     getByRunIds(input: {
         readonly projectId: string;
+        readonly threadId: string;
         readonly runIds: readonly string[];
     }): Promise<readonly AgentContextCheckpointRecord[]>;
     getLatest(input: {
@@ -449,10 +637,374 @@ export interface AgentContextCheckpointStore {
         readonly threadId: string;
     }): Promise<AgentContextCheckpointRecord | null>;
 }
+/**
+ * What the Agent may change without asking its requester: `manual` asks for every action and
+ * workflow, `accept-edits` runs the actions that only change Sixb, `auto` runs everything.
+ */
+export declare const AGENT_APPROVAL_MODES: readonly ["manual", "accept-edits", "auto"];
+export type AgentApprovalMode = (typeof AGENT_APPROVAL_MODES)[number];
+/** The modes that hold some calls: the one that held a call is recorded on its approval. */
+export declare const AGENT_HOLDING_APPROVAL_MODES: readonly ["manual", "accept-edits"];
+export type AgentHoldingApprovalMode = (typeof AGENT_HOLDING_APPROVAL_MODES)[number];
+export declare const AGENT_APPROVAL_STATUSES: readonly ["pending", "approved", "denied", "cancelled", "superseded", "expired"];
+export type AgentApprovalStatus = (typeof AGENT_APPROVAL_STATUSES)[number];
+/** The statuses a pending approval is settled to without a decision. */
+export type AgentApprovalSettledStatus = Extract<AgentApprovalStatus, "cancelled" | "superseded" | "expired">;
+/**
+ * The held call, as it runs once approved. An action's params are normalized: what the user
+ * approves is exactly what runs. Its run id is the one the Agent named, so a repeated request finds
+ * the same approval and the same run.
+ */
+export type AgentApprovalCall = {
+    readonly kind: "action";
+    readonly actionId: string;
+    readonly subject: ActionSubject;
+    readonly params: ActionRunParams;
+    readonly actionRunId: string;
+    /** `external` when the action has a writeback or effects: it reaches beyond Sixb. */
+    readonly effect: "ontology" | "external";
+} | {
+    readonly kind: "workflow";
+    readonly workflowId: string;
+    readonly input: JsonObject;
+    readonly workflowRunId: string;
+};
+/** What running an approved call gave. */
+export type AgentApprovalOutcome = {
+    readonly kind: "action-run";
+    readonly runId: string;
+    readonly status: "succeeded" | "failed";
+    readonly error?: ActionRunFailure;
+} | {
+    readonly kind: "workflow-run";
+    readonly runId: string;
+    readonly queuedAt: string;
+}
+/** The call was refused when it ran, for example because its requester lost a grant. */
+ | {
+    readonly kind: "error";
+    readonly error: SixbFailure;
+};
+export interface AgentApprovalRecord {
+    readonly id: string;
+    readonly projectId: string;
+    readonly threadId: string;
+    /** The conversation turn the call belongs to. */
+    readonly runId: string;
+    /** The run that made the call: the turn itself, or one of its children. */
+    readonly callerRunId: string;
+    /** Who asked for the turn: the only one who decides, as the call runs with their rights. */
+    readonly requestedBy: Principal;
+    /** The mode that held the call. */
+    readonly mode: AgentHoldingApprovalMode;
+    /** The call's run id, unique among a thread's pending, approved and denied approvals. */
+    readonly callKey: string;
+    readonly call: AgentApprovalCall;
+    readonly status: AgentApprovalStatus;
+    readonly createdAt: Date;
+    readonly expiresAt: Date;
+    readonly decidedAt?: Date;
+    readonly decidedBy?: Principal;
+    /** Set once an approved call ran. */
+    readonly outcome?: AgentApprovalOutcome;
+    /** The user message that told the model how the approval ended. */
+    readonly reportedInMessageId?: string;
+    /** "Always allow": the mode its requester raised the turn's calls to when deciding this one. */
+    readonly raisedMode?: AgentApprovalMode;
+    /**
+     * The turn will not resume for it: stopped, its requester left, or another of its calls was set
+     * aside. The thread's next message still reports it.
+     */
+    readonly turnStoppedAt?: Date;
+    /** When a process last took the approved call to run it; a stale claim can be taken again. */
+    readonly executionClaimedAt?: Date;
+}
+export interface RequestAgentApprovalInput {
+    readonly id: string;
+    readonly projectId: string;
+    readonly runId: string;
+    readonly callerRunId: string;
+    /** The caller run's current delivery token: a stale delivery holds nothing. */
+    readonly executionToken: string;
+    readonly requestedBy: Principal;
+    readonly mode: AgentHoldingApprovalMode;
+    readonly call: AgentApprovalCall;
+    readonly createdAt?: Date;
+    readonly expiresAt: Date;
+}
+export interface RequestAgentApprovalResult {
+    readonly approval: AgentApprovalRecord;
+    /** `false` when a pending, approved or denied approval of the thread had the same call key. */
+    readonly created: boolean;
+}
+export interface DecideAgentApprovalInput {
+    readonly projectId: string;
+    readonly id: string;
+    readonly decision: "approved" | "denied";
+    readonly decidedBy: Principal;
+    readonly decidedAt?: Date;
+    /** With `approved`: "Always allow" raised the turn's mode to this one. */
+    readonly raisedMode?: AgentApprovalMode;
+}
+export interface DecideAgentApprovalResult {
+    /** The approval afterwards: `expired` when its time ran out before this decision. */
+    readonly approval: AgentApprovalRecord;
+    /** Whether this call moved it out of `pending` with the decision. */
+    readonly decided: boolean;
+}
+export interface SettleAgentApprovalsInput {
+    readonly projectId: string;
+    readonly threadId: string;
+    readonly status: AgentApprovalSettledStatus;
+}
+/** Stop a thread's turn, or a requester's turns there, from resuming on their calls. */
+export interface StopAgentApprovalsInput {
+    readonly projectId: string;
+    readonly threadId: string;
+    /** Only the calls of this conversation turn. */
+    readonly runId?: string;
+    /** Only the calls this principal asked for. */
+    readonly requestedBy?: Principal;
+    readonly stoppedAt?: Date;
+}
+export interface StopAgentApprovalsResult {
+    /** The pending approvals it cancelled. */
+    readonly cancelled: readonly AgentApprovalRecord[];
+    /** How many unreported approvals it stopped, the cancelled ones included. */
+    readonly stopped: number;
+}
+/** Where a keyset listing resumes: after this approval, in the order approvals are listed. */
+export interface AgentApprovalCursor {
+    readonly createdAt: Date;
+    readonly id: string;
+}
+export interface MarkAgentApprovalsReportedInput {
+    readonly projectId: string;
+    readonly threadId: string;
+    readonly ids: readonly string[];
+    readonly messageId: string;
+    /** A resume: an approval whose turn was stopped is not marked. */
+    readonly resuming?: boolean;
+}
+export interface ListAgentApprovalsInput {
+    readonly projectId: string;
+    readonly threadId?: string;
+    readonly runId?: string;
+    readonly requestedBy?: Principal;
+    readonly statuses?: readonly AgentApprovalStatus[];
+    /** `false`: only the approvals no message reported yet. */
+    readonly reported?: boolean;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+export interface ListAgentApprovalsResult {
+    /** Oldest first. */
+    readonly approvals: readonly AgentApprovalRecord[];
+    readonly hasMore: boolean;
+    readonly total: number;
+}
+/**
+ * Held calls and their decisions. `runs.finish` settles a run's approvals in its own transaction:
+ * a turn that pauses keeps them for their decision, any other ending cancels its pending ones.
+ */
+export interface AgentApprovalStore {
+    /**
+     * Fenced like a checkpoint: the caller run is running with `executionToken`, and is the
+     * conversation turn `runId` or one of its children. Returns the thread's pending, approved or
+     * denied approval with the same call key when there is one, and creates one otherwise.
+     */
+    request(input: RequestAgentApprovalInput): Promise<RequestAgentApprovalResult>;
+    /** Compare-and-swap from `pending`; `null` when no such approval exists. */
+    decide(input: DecideAgentApprovalInput): Promise<DecideAgentApprovalResult | null>;
+    /** Record what an approved call gave, once: an approval with an outcome is returned unchanged. */
+    recordOutcome(input: {
+        readonly projectId: string;
+        readonly id: string;
+        readonly outcome: AgentApprovalOutcome;
+    }): Promise<AgentApprovalRecord>;
+    /** Settle the thread's pending approvals, and return the ones it settled. */
+    settle(input: SettleAgentApprovalsInput): Promise<readonly AgentApprovalRecord[]>;
+    /** Expire the project's pending approvals whose time ran out by `now`, and return them. */
+    expireDue(input: {
+        readonly projectId: string;
+        readonly now: Date;
+        readonly limit?: number;
+    }): Promise<readonly AgentApprovalRecord[]>;
+    /**
+     * Cancel the matching pending approvals and mark every matching one no message reported yet as
+     * stopped: their turn never resumes on them.
+     */
+    stop(input: StopAgentApprovalsInput): Promise<StopAgentApprovalsResult>;
+    /** Mark the ones no message reported yet, and return their ids. */
+    markReported(input: MarkAgentApprovalsReportedInput): Promise<readonly string[]>;
+    /**
+     * Whether the run holds a call: one of its approvals, or one it made for its turn, pending, or
+     * decided and not reported yet. `runs.finish` checks the same before `awaiting_approval`.
+     */
+    holdsRun(input: {
+        readonly projectId: string;
+        readonly runId: string;
+    }): Promise<boolean>;
+    /**
+     * Take an approved call without an outcome to run it, unless another process took it after
+     * `staleBefore`; its decision is its first claim. `null` when it is not there to take.
+     */
+    claimExecution(input: {
+        readonly projectId: string;
+        readonly id: string;
+        readonly claimedAt: Date;
+        readonly staleBefore: Date;
+    }): Promise<AgentApprovalRecord | null>;
+    /**
+     * What a repair pass works on, oldest first: approved calls without an outcome whose claim is
+     * older than `claimableBefore`, and decided calls no message reported whose turn is not stopped.
+     */
+    listRepairable(input: {
+        readonly projectId: string;
+        readonly claimableBefore: Date;
+        readonly after?: AgentApprovalCursor;
+        readonly limit: number;
+    }): Promise<readonly AgentApprovalRecord[]>;
+    getById(params: {
+        readonly projectId: string;
+        readonly id: string;
+    }): Promise<AgentApprovalRecord | null>;
+    list(input: ListAgentApprovalsInput): Promise<ListAgentApprovalsResult>;
+}
+/** Each user's approval mode: a default, and their own choice in each thread. */
+export interface AgentApprovalModeStore {
+    getDefault(input: {
+        readonly projectId: string;
+        readonly principal: Principal;
+    }): Promise<AgentApprovalMode | null>;
+    setDefault(input: {
+        readonly projectId: string;
+        readonly principal: Principal;
+        readonly mode: AgentApprovalMode;
+        readonly updatedAt?: Date;
+    }): Promise<void>;
+    getForThread(input: {
+        readonly projectId: string;
+        readonly threadId: string;
+        readonly principal: Principal;
+    }): Promise<AgentApprovalMode | null>;
+    /**
+     * `null` clears the choice: the user's turns in the thread follow their default again. Throws
+     * `thread_not_found` when the thread does not exist.
+     */
+    setForThread(input: {
+        readonly projectId: string;
+        readonly threadId: string;
+        readonly principal: Principal;
+        readonly mode: AgentApprovalMode | null;
+        readonly updatedAt?: Date;
+    }): Promise<void>;
+}
+/** One file of a memory repo, at its path from the repo root. */
+export interface AgentMemoryFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** A memory repo as of its latest revision. */
+export interface AgentMemoryRepoRecord {
+    /** 0 before the first save. */
+    readonly revision: number;
+    /** Ordered by path. */
+    readonly files: readonly AgentMemoryFile[];
+}
+/** One change of a save: the file's new contents, or `null` to delete it. */
+export interface AgentMemoryChange {
+    readonly path: string;
+    readonly contents: string | null;
+}
+export interface SaveAgentMemoryInput {
+    readonly projectId: string;
+    /** `user:<userId>` or `project`. */
+    readonly repoId: string;
+    /** The revision the caller loaded. */
+    readonly baseRevision: number;
+    readonly message: string;
+    readonly author: Principal;
+    /** The conversation the save came from, `/agents/<threadId>`. */
+    readonly source?: string;
+    readonly changes: readonly AgentMemoryChange[];
+    readonly createdAt?: Date;
+}
+export type SaveAgentMemoryResult = {
+    readonly saved: true;
+    readonly revision: number;
+} | {
+    readonly saved: false;
+    /** The repo's latest revision. */
+    readonly revision: number;
+    /** Files in `changes` that another save changed after `baseRevision`, as they are now. */
+    readonly conflicts: readonly AgentMemoryChange[];
+};
+/** One save: who made it, why, and which paths it wrote. A revision never changes. */
+export interface AgentMemoryRevisionRecord {
+    readonly revision: number;
+    readonly message: string;
+    readonly author: Principal;
+    readonly source?: string;
+    /** Ordered by path. */
+    readonly changes: readonly {
+        readonly path: string;
+        readonly deleted: boolean;
+    }[];
+    readonly createdAt: Date;
+}
+export interface ListAgentMemoryRevisionsInput {
+    readonly projectId: string;
+    readonly repoId: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+export interface ListAgentMemoryRevisionsResult {
+    /** Newest first. */
+    readonly revisions: readonly AgentMemoryRevisionRecord[];
+    readonly hasMore: boolean;
+    readonly total: number;
+}
+/**
+ * Memory repos as append-only revisions: a save inserts one revision and the files it wrote, and
+ * never updates a row. Paths, sizes and who may save are decided in Core before a call reaches
+ * storage.
+ */
+export interface AgentMemoryStore {
+    /**
+     * The repo at its latest revision, or with `asOf` at the latest revision saved by then, and with
+     * `revision` at the latest up to that one: revision 0 and no files when none was. File versions
+     * pruned from the history are missing from it.
+     */
+    get(input: {
+        readonly projectId: string;
+        readonly repoId: string;
+        readonly asOf?: Date;
+        readonly revision?: number;
+    }): Promise<AgentMemoryRepoRecord>;
+    /**
+     * In one transaction: reports a conflict when a path in `changes` was written after
+     * `baseRevision`, or when the repo is behind `baseRevision` because it was deleted; otherwise
+     * stores the next revision. The same transaction removes file versions older than
+     * {@link AGENT_MEMORY_HISTORY_DAYS} days that are not their path's latest.
+     */
+    save(input: SaveAgentMemoryInput): Promise<SaveAgentMemoryResult>;
+    listRevisions(input: ListAgentMemoryRevisionsInput): Promise<ListAgentMemoryRevisionsResult>;
+    /** Deletes the repo with its history. */
+    delete(input: {
+        readonly projectId: string;
+        readonly repoId: string;
+    }): Promise<void>;
+}
+/** How long a file version that is not its path's latest stays in a repo's history. */
+export declare const AGENT_MEMORY_HISTORY_DAYS = 90;
 export interface AgentStorage {
     readonly threads: AgentThreadStore;
     readonly runs: AgentRunStore;
     readonly messages: AgentMessageStore;
     readonly checkpoints: AgentContextCheckpointStore;
+    readonly memory: AgentMemoryStore;
+    readonly approvals: AgentApprovalStore;
+    readonly approvalModes: AgentApprovalModeStore;
 }
 //# sourceMappingURL=types.d.ts.map