Store
View as MarkdownDefined in: core/src/store/store.ts:15
Methods
Section titled “Methods”appendEvent()
Section titled “appendEvent()”appendEvent<K>(e): Promise<EventEnvelope<K>>;Defined in: core/src/store/store.ts:27
Type Parameters
Section titled “Type Parameters”Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
e |
Omit<EventEnvelope<K>, "eventId" | "sequence" | "schemaVersion"> |
Returns
Section titled “Returns”Promise<EventEnvelope<K>>
casApproval()
Section titled “casApproval()”casApproval( id, expect, next): Promise< | { allowedScopes: ("once" | "session")[]; availableDecisions: ("deny" | "allow_once" | "allow_session")[]; category: "file" | "mcp" | "shell" | "network" | "other"; createdAt: string; decision?: "deny" | "allow"; description?: string; expiresAt: string; id: string; runId: string; runtimeId: string; sessionId: string; state: | "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling"; target: { command?: string; cwd?: string; host?: string; path?: string; }; title: string; toolId?: string; version: number;}| null>;Defined in: core/src/store/store.ts:38
Atomic compare-and-swap on (state, version). Returns null when the race was lost.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
id |
string |
expect |
{ state: | "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling"; version: number; } |
expect.state |
| "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling" |
expect.version |
number |
next |
Partial<ApprovalRequest> |
Returns
Section titled “Returns”Promise<
| {
allowedScopes: ("once" | "session")[];
availableDecisions: ("deny" | "allow_once" | "allow_session")[];
category: "file" | "mcp" | "shell" | "network" | "other";
createdAt: string;
decision?: "deny" | "allow";
description?: string;
expiresAt: string;
id: string;
runId: string;
runtimeId: string;
sessionId: string;
state: | "failed"
| "cancelled"
| "pending"
| "submitting"
| "approved"
| "denied"
| "expired"
| "reconciling";
target: {
command?: string;
cwd?: string;
host?: string;
path?: string;
};
title: string;
toolId?: string;
version: number;
}
| null>
close()
Section titled “close()”close(): Promise<void>;Defined in: core/src/store/store.ts:58
Returns
Section titled “Returns”Promise<void>
createApproval()
Section titled “createApproval()”createApproval(a): Promise<void>;Defined in: core/src/store/store.ts:34
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
a |
{ allowedScopes: ("once" | "session")[]; availableDecisions: ("deny" | "allow_once" | "allow_session")[]; category: "file" | "mcp" | "shell" | "network" | "other"; createdAt: string; decision?: "deny" | "allow"; description?: string; expiresAt: string; id: string; runId: string; runtimeId: string; sessionId: string; state: | "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling"; target: { command?: string; cwd?: string; host?: string; path?: string; }; title: string; toolId?: string; version: number; } |
a.allowedScopes |
("once" | "session")[] |
a.availableDecisions |
("deny" | "allow_once" | "allow_session")[] |
a.category |
"file" | "mcp" | "shell" | "network" | "other" |
a.createdAt |
string |
a.decision? |
"deny" | "allow" |
a.description? |
string |
a.expiresAt |
string |
a.id |
string |
a.runId |
string |
a.runtimeId |
string |
a.sessionId |
string |
a.state |
| "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling" |
a.target |
{ command?: string; cwd?: string; host?: string; path?: string; } |
a.target.command? |
string |
a.target.cwd? |
string |
a.target.host? |
string |
a.target.path? |
string |
a.title |
string |
a.toolId? |
string |
a.version |
number |
Returns
Section titled “Returns”Promise<void>
createAttachment()
Section titled “createAttachment()”createAttachment(a): Promise<void>;Defined in: core/src/store/store.ts:43
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
a |
StoredAttachment |
Returns
Section titled “Returns”Promise<void>
createRun()
Section titled “createRun()”createRun(r): Promise<void>;Defined in: core/src/store/store.ts:22
r.attachments is not stored here; runs are hydrated from attachments referenced by them.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
r |
{ attachments?: object[]; createdAt: string; endedAt?: string; error?: { code: | "runtime_unavailable" | "auth_required" | "unsupported_capability" | "invalid_workspace" | "session_busy" | "session_read_only" | "not_found" | "unauthorized" | "forbidden_origin" | "invalid_request" | "approval_expired" | "approval_already_resolved" | "event_replay_unavailable" | "runtime_disconnected" | "policy_denied" | "store_locked" | "attachment_too_large" | "attachment_type_unsupported" | "machine_offline" | "machine_not_found" | "upgrade_required" | "tool_failed" | "device_code_expired" | "rate_limited" | "internal_error"; details?: Record<string, unknown>; hint?: string; message: string; requestId?: string; retryable: boolean; }; id: string; prompt: string; sessionId: string; startedAt?: string; state: | "queued" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled" | "interrupted"; } |
r.attachments? |
object[] |
r.createdAt |
string |
r.endedAt? |
string |
r.error? |
{ code: | "runtime_unavailable" | "auth_required" | "unsupported_capability" | "invalid_workspace" | "session_busy" | "session_read_only" | "not_found" | "unauthorized" | "forbidden_origin" | "invalid_request" | "approval_expired" | "approval_already_resolved" | "event_replay_unavailable" | "runtime_disconnected" | "policy_denied" | "store_locked" | "attachment_too_large" | "attachment_type_unsupported" | "machine_offline" | "machine_not_found" | "upgrade_required" | "tool_failed" | "device_code_expired" | "rate_limited" | "internal_error"; details?: Record<string, unknown>; hint?: string; message: string; requestId?: string; retryable: boolean; } |
r.error.code |
| "runtime_unavailable" | "auth_required" | "unsupported_capability" | "invalid_workspace" | "session_busy" | "session_read_only" | "not_found" | "unauthorized" | "forbidden_origin" | "invalid_request" | "approval_expired" | "approval_already_resolved" | "event_replay_unavailable" | "runtime_disconnected" | "policy_denied" | "store_locked" | "attachment_too_large" | "attachment_type_unsupported" | "machine_offline" | "machine_not_found" | "upgrade_required" | "tool_failed" | "device_code_expired" | "rate_limited" | "internal_error" |
r.error.details? |
Record<string, unknown> |
r.error.hint? |
string |
r.error.message |
string |
r.error.requestId? |
string |
r.error.retryable |
boolean |
r.id |
string |
r.prompt |
string |
r.sessionId |
string |
r.startedAt? |
string |
r.state |
| "queued" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled" | "interrupted" |
Returns
Section titled “Returns”Promise<void>
createSession()
Section titled “createSession()”createSession(s): Promise<void>;Defined in: core/src/store/store.ts:16
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
s |
object & object |
Returns
Section titled “Returns”Promise<void>
deleteOrphanAttachments()
Section titled “deleteOrphanAttachments()”deleteOrphanAttachments(olderThan): Promise<StoredAttachment[]>;Defined in: core/src/store/store.ts:55
Deletes unreferenced attachments created before olderThan; returns the deleted rows.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
olderThan |
Date |
Returns
Section titled “Returns”Promise<StoredAttachment[]>
getApproval()
Section titled “getApproval()”getApproval(id): Promise< | { allowedScopes: ("once" | "session")[]; availableDecisions: ("deny" | "allow_once" | "allow_session")[]; category: "file" | "mcp" | "shell" | "network" | "other"; createdAt: string; decision?: "deny" | "allow"; description?: string; expiresAt: string; id: string; runId: string; runtimeId: string; sessionId: string; state: | "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling"; target: { command?: string; cwd?: string; host?: string; path?: string; }; title: string; toolId?: string; version: number;}| null>;Defined in: core/src/store/store.ts:35
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
id |
string |
Returns
Section titled “Returns”Promise<
| {
allowedScopes: ("once" | "session")[];
availableDecisions: ("deny" | "allow_once" | "allow_session")[];
category: "file" | "mcp" | "shell" | "network" | "other";
createdAt: string;
decision?: "deny" | "allow";
description?: string;
expiresAt: string;
id: string;
runId: string;
runtimeId: string;
sessionId: string;
state: | "failed"
| "cancelled"
| "pending"
| "submitting"
| "approved"
| "denied"
| "expired"
| "reconciling";
target: {
command?: string;
cwd?: string;
host?: string;
path?: string;
};
title: string;
toolId?: string;
version: number;
}
| null>
getAttachment()
Section titled “getAttachment()”getAttachment(id): Promise< | StoredAttachment| null>;Defined in: core/src/store/store.ts:44
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
id |
string |
Returns
Section titled “Returns”Promise<
| StoredAttachment
| null>
getIdempotent()
Section titled “getIdempotent()”getIdempotent(key, scope): Promise< | { requestHash: string; response: unknown;}| null>;Defined in: core/src/store/store.ts:56
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
key |
string |
scope |
string |
Returns
Section titled “Returns”Promise<
| {
requestHash: string;
response: unknown;
}
| null>
getRun()
Section titled “getRun()”getRun(id): Promise< | { attachments?: object[]; createdAt: string; endedAt?: string; error?: { code: | "runtime_unavailable" | "auth_required" | "unsupported_capability" | "invalid_workspace" | "session_busy" | "session_read_only" | "not_found" | "unauthorized" | "forbidden_origin" | "invalid_request" | "approval_expired" | "approval_already_resolved" | "event_replay_unavailable" | "runtime_disconnected" | "policy_denied" | "store_locked" | "attachment_too_large" | "attachment_type_unsupported" | "machine_offline" | "machine_not_found" | "upgrade_required" | "tool_failed" | "device_code_expired" | "rate_limited" | "internal_error"; details?: Record<string, unknown>; hint?: string; message: string; requestId?: string; retryable: boolean; }; id: string; prompt: string; sessionId: string; startedAt?: string; state: | "queued" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled" | "interrupted";}| null>;Defined in: core/src/store/store.ts:23
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
id |
string |
Returns
Section titled “Returns”Promise<
| {
attachments?: object[];
createdAt: string;
endedAt?: string;
error?: {
code: | "runtime_unavailable"
| "auth_required"
| "unsupported_capability"
| "invalid_workspace"
| "session_busy"
| "session_read_only"
| "not_found"
| "unauthorized"
| "forbidden_origin"
| "invalid_request"
| "approval_expired"
| "approval_already_resolved"
| "event_replay_unavailable"
| "runtime_disconnected"
| "policy_denied"
| "store_locked"
| "attachment_too_large"
| "attachment_type_unsupported"
| "machine_offline"
| "machine_not_found"
| "upgrade_required"
| "tool_failed"
| "device_code_expired"
| "rate_limited"
| "internal_error";
details?: Record<string, unknown>;
hint?: string;
message: string;
requestId?: string;
retryable: boolean;
};
id: string;
prompt: string;
sessionId: string;
startedAt?: string;
state: | "queued"
| "running"
| "waiting_approval"
| "completed"
| "failed"
| "cancelled"
| "interrupted";
}
| null>
getSession()
Section titled “getSession()”getSession(id): Promise<object & object | null>;Defined in: core/src/store/store.ts:17
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
id |
string |
Returns
Section titled “Returns”Promise<object & object | null>
listApprovals()
Section titled “listApprovals()”listApprovals(q): Promise<object[]>;Defined in: core/src/store/store.ts:36
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
q |
{ sessionId: string; states?: ( | "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling")[]; } |
q.sessionId |
string |
q.states? |
( | "failed" | "cancelled" | "pending" | "submitting" | "approved" | "denied" | "expired" | "reconciling")[] |
Returns
Section titled “Returns”Promise<object[]>
listAttachments()
Section titled “listAttachments()”listAttachments(ids): Promise<StoredAttachment[]>;Defined in: core/src/store/store.ts:46
Returns the existing rows among ids (missing ids are simply absent).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
ids |
string[] |
Returns
Section titled “Returns”Promise<StoredAttachment[]>
listRuns()
Section titled “listRuns()”listRuns(sessionId): Promise<object[]>;Defined in: core/src/store/store.ts:24
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
Returns
Section titled “Returns”Promise<object[]>
listRunsInState()
Section titled “listRunsInState()”listRunsInState(states): Promise<object[]>;Defined in: core/src/store/store.ts:26
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
states |
( | "queued" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled" | "interrupted")[] |
Returns
Section titled “Returns”Promise<object[]>
listSessions()
Section titled “listSessions()”listSessions(): Promise<object[]>;Defined in: core/src/store/store.ts:18
Returns
Section titled “Returns”Promise<object[]>
markAttachmentsReferenced()
Section titled “markAttachmentsReferenced()”markAttachmentsReferenced(ids, runId): Promise<number>;Defined in: core/src/store/store.ts:51
All or nothing: sets referencedByRun on every one of ids when all exist and are
unreferenced, returning ids.length; otherwise changes nothing and returns 0.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
ids |
string[] |
runId |
string |
Returns
Section titled “Returns”Promise<number>
minRetainedSequence()
Section titled “minRetainedSequence()”minRetainedSequence(sessionId): Promise<number>;Defined in: core/src/store/store.ts:32
0 when nothing was pruned; otherwise the lowest sequence that may still be retained.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
Returns
Section titled “Returns”Promise<number>
pruneEvents()
Section titled “pruneEvents()”pruneEvents(olderThan): Promise<number>;Defined in: core/src/store/store.ts:33
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
olderThan |
Date |
Returns
Section titled “Returns”Promise<number>
putIdempotent()
Section titled “putIdempotent()”putIdempotent( key, scope, requestHash, response): Promise<void>;Defined in: core/src/store/store.ts:57
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
key |
string |
scope |
string |
requestHash |
string |
response |
unknown |
Returns
Section titled “Returns”Promise<void>
readEvents()
Section titled “readEvents()”readEvents( sessionId, afterSequence, limit?): Promise<EventEnvelope< | "session.created" | "session.updated" | "run.started" | "run.updated" | "run.completed" | "run.failed" | "run.cancelled" | "run.interrupted" | "message.started" | "message.delta" | "message.completed" | "tool.started" | "tool.updated" | "tool.completed" | "tool.failed" | "approval.requested" | "approval.updated" | "approval.resolved"| "system.warning">[]>;Defined in: core/src/store/store.ts:30
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
sessionId |
string |
afterSequence |
number |
limit? |
number |
Returns
Section titled “Returns”Promise<EventEnvelope<
| "session.created"
| "session.updated"
| "run.started"
| "run.updated"
| "run.completed"
| "run.failed"
| "run.cancelled"
| "run.interrupted"
| "message.started"
| "message.delta"
| "message.completed"
| "tool.started"
| "tool.updated"
| "tool.completed"
| "tool.failed"
| "approval.requested"
| "approval.updated"
| "approval.resolved"
| "system.warning">[]>
releaseAttachments()
Section titled “releaseAttachments()”releaseAttachments(runId): Promise<void>;Defined in: core/src/store/store.ts:53
Clears referencedByRun for attachments marked for runId (compensates a failed run start).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
runId |
string |
Returns
Section titled “Returns”Promise<void>
updateRun()
Section titled “updateRun()”updateRun(id, patch): Promise<{ attachments?: object[]; createdAt: string; endedAt?: string; error?: { code: | "runtime_unavailable" | "auth_required" | "unsupported_capability" | "invalid_workspace" | "session_busy" | "session_read_only" | "not_found" | "unauthorized" | "forbidden_origin" | "invalid_request" | "approval_expired" | "approval_already_resolved" | "event_replay_unavailable" | "runtime_disconnected" | "policy_denied" | "store_locked" | "attachment_too_large" | "attachment_type_unsupported" | "machine_offline" | "machine_not_found" | "upgrade_required" | "tool_failed" | "device_code_expired" | "rate_limited" | "internal_error"; details?: Record<string, unknown>; hint?: string; message: string; requestId?: string; retryable: boolean; }; id: string; prompt: string; sessionId: string; startedAt?: string; state: | "queued" | "running" | "waiting_approval" | "completed" | "failed" | "cancelled" | "interrupted";}>;Defined in: core/src/store/store.ts:25
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
id |
string |
patch |
Partial<Run> |
Returns
Section titled “Returns”Promise<{
attachments?: object[];
createdAt: string;
endedAt?: string;
error?: {
code: | "runtime_unavailable"
| "auth_required"
| "unsupported_capability"
| "invalid_workspace"
| "session_busy"
| "session_read_only"
| "not_found"
| "unauthorized"
| "forbidden_origin"
| "invalid_request"
| "approval_expired"
| "approval_already_resolved"
| "event_replay_unavailable"
| "runtime_disconnected"
| "policy_denied"
| "store_locked"
| "attachment_too_large"
| "attachment_type_unsupported"
| "machine_offline"
| "machine_not_found"
| "upgrade_required"
| "tool_failed"
| "device_code_expired"
| "rate_limited"
| "internal_error";
details?: Record<string, unknown>;
hint?: string;
message: string;
requestId?: string;
retryable: boolean;
};
id: string;
prompt: string;
sessionId: string;
startedAt?: string;
state: | "queued"
| "running"
| "waiting_approval"
| "completed"
| "failed"
| "cancelled"
| "interrupted";
}>
updateSession()
Section titled “updateSession()”updateSession(id, patch): Promise<{ activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("file" | "mcp" | "shell" | "network" | "other")[]; }; attachments: { files: boolean; images: boolean; maxBytes: number; maxImageBytes?: number; }; diffEvents: boolean; efforts: ("low" | "medium" | "high" | "xhigh" | "max")[]; mcp: boolean; models: object[]; modelsAuthoritative?: boolean; nativeResume: boolean; permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[]; siteTools: boolean; skills: "unknown" | "supported" | "partial" | "prompt"; streaming: boolean; }; createdAt: string; id: string; machineId?: string; readOnly: boolean; runtimeId: string; settings: { effort?: "low" | "medium" | "high" | "xhigh" | "max"; model?: string; permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions"; }; status: "ready" | "busy" | "unavailable" | "closed"; title: string; workspace: string;}>;Defined in: core/src/store/store.ts:20
Keys present in patch with value undefined/null clear nullable fields (activeRunId, nativeSessionRef).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
id |
string |
patch |
Partial<{ activeRunId?: string; capabilities: { approval: { once: boolean; session: boolean; types: ("file" | "mcp" | "shell" | "network" | "other")[]; }; attachments: { files: boolean; images: boolean; maxBytes: number; maxImageBytes?: number; }; diffEvents: boolean; efforts: ("low" | "medium" | "high" | "xhigh" | "max")[]; mcp: boolean; models: object[]; modelsAuthoritative?: boolean; nativeResume: boolean; permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[]; siteTools: boolean; skills: "unknown" | "supported" | "partial" | "prompt"; streaming: boolean; }; createdAt: string; id: string; machineId?: string; readOnly: boolean; runtimeId: string; settings: { effort?: "low" | "medium" | "high" | "xhigh" | "max"; model?: string; permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions"; }; status: "ready" | "busy" | "unavailable" | "closed"; title: string; workspace: string; }> & object |
Returns
Section titled “Returns”Promise<{
activeRunId?: string;
capabilities: {
approval: {
once: boolean;
session: boolean;
types: ("file" | "mcp" | "shell" | "network" | "other")[];
};
attachments: {
files: boolean;
images: boolean;
maxBytes: number;
maxImageBytes?: number;
};
diffEvents: boolean;
efforts: ("low" | "medium" | "high" | "xhigh" | "max")[];
mcp: boolean;
models: object[];
modelsAuthoritative?: boolean;
nativeResume: boolean;
permissionModes: ("default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions")[];
siteTools: boolean;
skills: "unknown" | "supported" | "partial" | "prompt";
streaming: boolean;
};
createdAt: string;
id: string;
machineId?: string;
readOnly: boolean;
runtimeId: string;
settings: {
effort?: "low" | "medium" | "high" | "xhigh" | "max";
model?: string;
permissionMode: "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions";
};
status: "ready" | "busy" | "unavailable" | "closed";
title: string;
workspace: string;
}>