session

package
v1.2.99 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 4, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const CurrentVersion = 3

Variables

View Source 
var (
	ErrDeliveryLeaseLost       = errors.New("delivery operation lease was lost")
	ErrDeliveryOperationBusy   = errors.New("delivery operation is leased or not ready")
	ErrDeliveryOperationAbsent = errors.New("delivery operation was not found")
)
View Source 
var (
	ErrForkSessionNotFound     = errors.New("source session not found")
	ErrForkSessionActive       = errors.New("source session is active")
	ErrForkNoCompletedTurn     = errors.New("source session has no completed conversation turn")
	ErrForkUnavailable         = errors.New("fork boundary is unavailable")
	ErrForkInvalidBoundary     = errors.New("fork boundary is invalid")
	ErrForkUnsupportedEntry    = errors.New("fork contains unsupported entry")
	ErrForkIdempotencyRequired = errors.New("fork request ID is required")
	ErrForkIdempotencyTooLong  = errors.New("fork request ID is too long")
	ErrForkIdempotencyConflict = errors.New("fork idempotency request conflicts")
)
View Source 
var (
	ErrRuntimeLeaseBusy         = errors.New("session runtime lease is held by another process")
	ErrRuntimeLeaseLost         = errors.New("session runtime lease was lost")
	ErrRuntimeSessionNotFound   = errors.New("session runtime lease requires an existing session")
	ErrSessionRunActive         = errors.New("session has an active durable run")
	ErrSessionRecoveryRequired  = errors.New("session has an active durable run that requires reconciliation")
	ErrSessionRecoveryNotNeeded = errors.New("session has no active durable run to recover")
	ErrRuntimeLeaseRunMismatch  = errors.New("session runtime lease run does not match the active durable run")
	ErrRuntimeLeasePurpose      = errors.New("session runtime lease purpose does not allow this operation")
)
View Source 
var ErrConversationTurnNotOpen = errors.New("conversation turn is not open")
View Source 
var ErrRuntimeSubmissionConflict = errors.New("runtime submission key conflicts with another request")
View Source 
var ErrRuntimeSubmissionExists = errors.New("runtime submission already exists")
View Source 
var ErrSessionIDExists = errors.New("session ID already exists")

ErrSessionIDExists means a new session attempted to reuse an existing ID. A duplicate must be rejected: updating the sessions row would merge the new header with the old entries and create a forked conversation.

View Source 
var ErrSessionModified = errors.New("session was modified by another process")

Functions

func AbandonInterruptedToolExecutionRecords added in v1.1.77 

func AbandonInterruptedToolExecutionRecords(sessionDir, sessionID, localTurnID string) (int64, error)

AbandonInterruptedToolExecutionRecords marks uncertain executions as explicitly abandoned. It never retries a tool or invents a tool output; callers use it only after they have established that no runtime owns the session lock. This makes a subsequent user-submitted run a new operation instead of silently replaying a potentially side-effecting call.

func AnnotateSessionRunError added in v1.2.97 

func AnnotateSessionRunError(sessionDir, runID, message string) (bool, error)

AnnotateSessionRunError records a terminal error reason on a run row that reached a terminal status without one (for example a background run abandoned after interrupted tool execution). It never changes the run status and is a no-op when the run already carries an error, so an earlier finalizer stays authoritative. It reports whether the annotation was applied.

func AppendInputResourceEventTx added in v1.2.96 

func AppendInputResourceEventTx(tx *dao.Tx, event InputResourceEvent) error

AppendInputResourceEventTx records a resource lifecycle event in the caller's transaction. Deterministic event IDs make retries safe after an unknown commit result.

func BindSession added in v1.1.77 

func BindSession(sessionDir, sessionID, channelType, channelID string) error

func CloseDatabases added in v1.1.73 

func CloseDatabases() error

CloseDatabases checkpoints and closes all process-owned session connections.

func CompareAndSwapResponseSessionState added in v1.1.77 

func CompareAndSwapResponseSessionState(sessionDir string, state ResponseSessionState, expectedVersion int64) (bool, error)

CompareAndSwapResponseSessionState advances a session lineage only when the caller observed expectedVersion. It prevents two concurrent turns from silently branching a previous_response_id chain.

func ConsumeESMGuidance added in v1.2.83 

func ConsumeESMGuidance(sessionDir, sessionID string, ids []string) error

func ConvergeSessionRunRecovery added in v1.2.96 

func ConvergeSessionRunRecovery(sessionDir string, run SessionRun, terminalEvent SessionRunEvent, decisionEvents []SessionRunEvent, turnStatus, stopReason string) error

ConvergeSessionRunRecovery atomically records pending Decision resolutions, closes every open ConversationTurn owned by the Run, writes the terminal Run event and state, and completes the recovery record. The exact local purpose=recovery lease is revalidated inside the transaction so a stale recovery worker cannot commit after another owner takes over.

func ConvergeSessionRunRecoveryContext added in v1.2.96 

func ConvergeSessionRunRecoveryContext(ctx context.Context, sessionDir string, run SessionRun, terminalEvent SessionRunEvent, decisionEvents []SessionRunEvent, turnStatus, stopReason string) error

ConvergeSessionRunRecoveryContext is the cancellable form used by the bounded Runtime recovery coordinator.

func CountAll added in v1.1.77 

func CountAll(sessionDir string) (int, error)

func CountWithMessages added in v1.2.83 

func CountWithMessages(sessionDir string, opts ...ListOption) (int, error)

CountWithMessages returns the number of sessions that contain at least one persisted conversation message. Empty sessions can be created transiently during startup or request setup and are not user-visible history.

func CreateDeliveryPlan added in v1.2.96 

func CreateDeliveryPlan(ctx context.Context, sessionDir string, plan DeliveryPlan) error

CreateDeliveryPlan persists a plan outside terminalization only for recovery reconciliation and focused tools. Normal execution must attach the plan to FinishSessionRunAndConversationTurn instead.

func CreateExecutionIntentAndSessionRun added in v1.2.83 

func CreateExecutionIntentAndSessionRun(sessionDir string, intent ExecutionIntent, run SessionRun) error

CreateExecutionIntentAndSessionRun atomically admits an immutable execution intent with its first or linked Run. Runtime-owned callers use this instead of writing the two records independently, so a reconnect can always resolve a durable Run back to the request that created it.

func CreateExecutionIntentAndSessionRunEvent added in v1.2.83 

func CreateExecutionIntentAndSessionRunEvent(sessionDir string, intent ExecutionIntent, run SessionRun, event SessionRunEvent) (string, error)

CreateExecutionIntentAndSessionRunEvent atomically admits an immutable intent, its Run row, and (when supplied) the canonical started event. This prevents a process loss between the intent/run write and event publication from creating an accepted execution with no replay anchor.

func CreateExecutionIntentAndSessionRunEventWithTurn added in v1.2.92 

func CreateExecutionIntentAndSessionRunEventWithTurn(sessionDir string, intent ExecutionIntent, run SessionRun, event SessionRunEvent, turn ConversationTurn) (string, error)

CreateExecutionIntentAndSessionRunEventWithTurn atomically admits an immutable intent, its Run/event, and the conversation turn boundary.

func CreateSessionRun added in v1.2.83 

func CreateSessionRun(sessionDir string, run SessionRun) error

CreateSessionRun inserts one canonical run row. Unlike SaveSessionRun, this method never overwrites an existing identity; Runtime-owned lifecycle code must treat duplicate run IDs as an admission error.

func CreateSessionRunAndEvent added in v1.2.83 

func CreateSessionRunAndEvent(sessionDir string, run SessionRun, event SessionRunEvent) (string, error)

CreateSessionRunAndEvent atomically inserts a new canonical Run and its first event. Retry attempts use this path so a process loss cannot leave a durable attempt without a replay anchor.

func CreateSessionRunAndEventWithTurn added in v1.2.92 

func CreateSessionRunAndEventWithTurn(sessionDir string, run SessionRun, event SessionRunEvent, turn ConversationTurn) (string, error)

CreateSessionRunAndEventWithTurn atomically admits a Run, its first event, and a conversation turn boundary when the Run produces transcript output.

func DeleteProject added in v1.2.83 

func DeleteProject(sessionDir, id string) error

func DeleteSession 

func DeleteSession(path string, sessionDir string) error

DeleteSession deletes a session file if it is under sessionDir.

func EndConversationTurn added in v1.2.92 

func EndConversationTurn(sessionDir, sessionID, turnID, status, stopReason string, endedAt time.Time) error

EndConversationTurn atomically writes turn/end and closes its boundary row.

func EnsureCurrentSchema added in v1.1.73 

func EnsureCurrentSchema(db *sql.DB) error

EnsureCurrentSchema creates the current schema only for an empty database. Existing databases are validated but never migrated or otherwise modified.

func FinishSessionRunAndConversationTurn added in v1.2.92 

func FinishSessionRunAndConversationTurn(sessionDir string, run SessionRun, event SessionRunEvent, turnID, turnStatus, stopReason string) (string, error)

FinishSessionRunAndConversationTurn atomically closes a conversation turn, its Run row, and the terminal Run event. A missing or already-closed turn is tolerated for recovery/idempotent retries because an Agent may already have emitted the boundary before Runtime terminalization.

func GenerateID 

func GenerateID() string

GenerateID generates a random 16-character hex ID. IDs such as entries.id are UNIQUE across the whole shared sessions.db, so the previous 32-bit space made collisions plausible at tens of millions of entries; 64 bits keeps the birthday probability negligible.

func GetChannelToolGeneration added in v1.1.77 

func GetChannelToolGeneration(sessionDir, sessionID string) (int64, error)

func IsNonTerminalSessionRunStatus added in v1.2.96 

func IsNonTerminalSessionRunStatus(status string) bool

IsNonTerminalSessionRunStatus reports whether a durable Run still requires execution, cancellation, or terminal persistence work.

func IsTerminalSessionRunStatus added in v1.2.97 

func IsTerminalSessionRunStatus(status string) bool

IsTerminalSessionRunStatus reports whether a durable Run status is terminal.

func LatestAdditionalDirectoriesByID added in v1.2.90 

func LatestAdditionalDirectoriesByID(sessionDir, sessionID string) ([]string, error)

LatestAdditionalDirectoriesByID reads the replayed directory binding for a session without exposing SQLite details to protocol adapters.

func LatestSessionRunEventSeq added in v1.2.83 

func LatestSessionRunEventSeq(sessionDir, runID string) (int64, error)

LatestSessionRunEventSeq returns the durable replay cursor for one Run. Callers use it to reconcile a disconnected adapter before requesting only the missing portion of the session event stream.

func LatestSessionTitle added in v1.2.83 

func LatestSessionTitle(sessionDir, sessionID string) (string, string, error)

func ListResponseReplayItems added in v1.1.77 

func ListResponseReplayItems(sessionDir, sessionID string, limit int) ([]json.RawMessage, error)

ListResponseReplayItems returns the ordered, sanitized native items from completed Responses turns. Callers can pass this sequence to a provider's native replay path instead of reconstructing prior assistant output from plain transcript text.

func LockRuntime added in v1.1.77 

func LockRuntime(sessionDir, sessionID string) func()

LockRuntime waits for the single-session lease. It is intentionally implemented as retrying TryLockRuntime so no database transaction remains open while an execution is running.

func LockSessionData added in v1.1.77 

func LockSessionData(sessionDir, sessionID string) func()

LockSessionData serializes short persistence mutations inside one process. Cross-process data consistency still comes from SQLite transactions.

func MarkSessionRunRecoveryComplete added in v1.2.96 

func MarkSessionRunRecoveryComplete(sessionDir, sessionID, runID string) error

MarkSessionRunRecoveryComplete records successful fenced convergence.

func MarkSessionRunRecoveryCompleteContext added in v1.2.96 

func MarkSessionRunRecoveryCompleteContext(ctx context.Context, sessionDir, sessionID, runID string) error

func MarkSessionRunRecoveryDetached added in v1.2.96 

func MarkSessionRunRecoveryDetached(sessionDir, sessionID, runID string) error

MarkSessionRunRecoveryDetached records that a canonical remote record was retained. The response record, not this marker, remains the evidence used to decide whether the provider execution is still recoverable.

func MarkSessionRunRecoveryDetachedContext added in v1.2.96 

func MarkSessionRunRecoveryDetachedContext(ctx context.Context, sessionDir, sessionID, runID string) error

func MarkSessionRunRecoveryFailed added in v1.2.96 

func MarkSessionRunRecoveryFailed(sessionDir, sessionID, runID, message string, nextRetryAt time.Time) error

MarkSessionRunRecoveryFailed persists a retryable failure under the same fenced recovery owner. A zero nextRetryAt means retry as soon as a Runtime coordinator observes the row again.

func MarkSessionRunRecoveryFailedContext added in v1.2.96 

func MarkSessionRunRecoveryFailedContext(ctx context.Context, sessionDir, sessionID, runID, message string, nextRetryAt time.Time) error

func NextSessionRunAttempt added in v1.2.83 

func NextSessionRunAttempt(sessionDir, sessionID, intentID string) (int, error)

NextSessionRunAttempt returns the next ordered user-visible attempt for an ExecutionIntent. Callers must hold their Runtime admission lock while using the returned value and creating the Run, so two retry commands cannot select the same attempt number.

func NonTerminalSessionRunStatuses added in v1.2.96 

func NonTerminalSessionRunStatuses() []string

NonTerminalSessionRunStatuses returns the canonical durable statuses that keep a Session busy. Callers receive a copy so the shared definition cannot be mutated outside this package.

func NotifyRuntimeStateChanged added in v1.2.95 

func NotifyRuntimeStateChanged(sessionID, origin string)

NotifyRuntimeStateChanged wakes local observers after a durable Run state transition. It never carries Run content and never changes ownership.

func OpenBunDatabase added in v1.2.96 

func OpenBunDatabase(path string) (*dao.Database, error)

OpenBunDatabase returns the process-wide Bun connection for path. New data access code should use this entry point and put queries in a DAO.

func OpenRootDB added in v1.1.61 

func OpenRootDB(sessionDir string) (*dao.Database, error)

OpenRootDB opens the shared sessions.db through the DAO-owned database handle. Callers must not close it; use CloseDatabases for lifecycle control.

func OpenStandaloneDB added in v1.1.73 

func OpenStandaloneDB(path string) (*dao.Database, error)

OpenStandaloneDB opens a configured standalone Bun connection. It is only intended for offline integrity checks; normal runtime code uses OpenRootDB.

func QueryRootDatabase added in v1.1.77 

func QueryRootDatabase(sessionDir string, fn func(*dao.Database) error) error

QueryRootDatabase runs a read operation against a session root's DAO-owned database. The callback must not retain the handle after it returns.

func ReclaimInterruptedToolExecution added in v1.1.78 

func ReclaimInterruptedToolExecution(sessionDir, executionKey string) (bool, error)

ReclaimInterruptedToolExecution atomically reopens a tool record after a process interruption. Read-only running/interrupted records are eligible automatically; side-effecting records require the explicit retry_requested state set by the confirmation API.

func RefreshDeliveryIntentStatus added in v1.2.96 

func RefreshDeliveryIntentStatus(ctx context.Context, sessionDir, intentID string) error

RefreshDeliveryIntentStatus recomputes the intent aggregate after an operation result. An intent is delivered only when all operations are delivered/unsupported; failed and uncertain operations remain visible.

func RequestToolExecutionRecovery added in v1.1.78 

func RequestToolExecutionRecovery(sessionDir, sessionID, localTurnID string, providerCallIDs []string) (int64, error)

RequestToolExecutionRecovery marks selected interrupted tool calls for an explicit user-confirmed retry. It never changes completed records and does not itself execute any tool.

func RequeueDeliveryOperation added in v1.2.96 

func RequeueDeliveryOperation(ctx context.Context, sessionDir, operationID, owner string, epoch int64, nextAttemptAt time.Time, failureCode string) error

RequeueDeliveryOperation releases a fenced lease for an explicit retry. It is used by recovery when a provider call did not yield a trustworthy result.

func RootDatabasePath added in v1.2.96 

func RootDatabasePath(sessionDir string) string

RootDatabasePath returns the shared sessions.db path for a session root. Keeping path derivation here prevents adapters and DAOs from duplicating session directory rules.

func RunAssistantEntryID added in v1.2.96 

func RunAssistantEntryID(runID string) string

RunAssistantEntryID is the deterministic transcript identity for the final assistant entry committed by a Runtime-owned conversation Run. Keeping the identity tied to the Run makes terminal retries and recovery idempotent.

func RunAssistantMessageFingerprint added in v1.2.96 

func RunAssistantMessageFingerprint(runID string, message provider.Message) string

RunAssistantMessageFingerprint returns a stable digest for an assistant message. It is useful to validate a recovery payload without persisting the message in a separate adapter-owned table.

func RunTerminalEventID added in v1.2.96 

func RunTerminalEventID(runID, eventType string) string

RunTerminalEventID is the deterministic lifecycle event identity for a terminal Run. Event type is included so a cancelled recovery cannot collide with a previously selected terminal outcome.

func RunUserEntryID added in v1.2.96 

func RunUserEntryID(runID string) string

RunUserEntryID is the deterministic transcript identity for a Run's admitted user message. Retries do not create another user entry.

func RuntimeDatabaseIdentity added in v1.2.96 

func RuntimeDatabaseIdentity(sessionDir string) string

RuntimeDatabaseIdentity returns the normalized SQLite identity used to scope process-local execution and recovery registries.

func RuntimeLeaseLost added in v1.2.92 

func RuntimeLeaseLost(sessionDir, sessionID string) <-chan struct{}

RuntimeLeaseLost returns the loss signal for the current process lease. It is intentionally read-only; callers use it to cancel work while every durable write still performs its own epoch/token fence check.

func SaveESMGuidance added in v1.2.83 

func SaveESMGuidance(sessionDir string, g ESMGuidance) error

func SaveExecutionIntent added in v1.2.83 

func SaveExecutionIntent(sessionDir string, intent ExecutionIntent) error

func SaveInputResourceEvent added in v1.2.96 

func SaveInputResourceEvent(ctx context.Context, sessionDir string, event InputResourceEvent) error

SaveInputResourceEvent appends a resource lifecycle event outside a larger transaction. Runtime admission paths should use AppendInputResourceEventTx.

func SaveResponseItem added in v1.1.77 

func SaveResponseItem(sessionDir string, item ResponseItemArchive) error

func SaveResponseRun added in v1.1.77 

func SaveResponseRun(sessionDir string, run ResponseRun) error

func SaveResponseTurn added in v1.1.77 

func SaveResponseTurn(sessionDir string, turn ResponseTurn) error

func SaveSessionCapabilities added in v1.1.61 

func SaveSessionCapabilities(sessionDir string, caps SessionCapabilities) error

SaveSessionCapabilities persists per-session runtime capability state.

func SaveSessionCapabilityEvent added in v1.1.61 

func SaveSessionCapabilityEvent(sessionDir string, ev SessionCapabilityEvent) (string, error)

SaveSessionCapabilityEvent appends a capability transition event to the independent event table.

func SaveSessionRun added in v1.1.77 

func SaveSessionRun(sessionDir string, run SessionRun) error

func SaveSessionRunEvent added in v1.1.61 

func SaveSessionRunEvent(sessionDir string, ev SessionRunEvent) (string, error)

SaveSessionRunEvent appends a run lifecycle event to the independent run event table.

func SetChannelTools added in v1.1.77 

func SetChannelTools(sessionDir, sessionID string, tools []ChannelToolConfig) error

func SetSessionMetadata added in v1.2.83 

func SetSessionMetadata(sessionDir, sessionID string, metadata SessionMetadata) error

func StartConversationTurn added in v1.2.92 

func StartConversationTurn(sessionDir string, turn ConversationTurn) error

StartConversationTurn atomically writes turn/start and its boundary row.

func SubscribeRuntimeLeaseLogs added in v1.2.95 

func SubscribeRuntimeLeaseLogs(sink func(string)) func()

SubscribeRuntimeLeaseLogs receives UDP diagnostics without writing them to the process-wide logger. Serve uses this to expose the messages in WebUI; TUI, CLI, and channel transports must not receive protocol diagnostics.

func SubscribeRuntimeLeaseNotifications added in v1.2.95 

func SubscribeRuntimeLeaseNotifications(handler func(RuntimeLeaseNotification)) func()

SubscribeRuntimeLeaseNotifications receives best-effort notifications from other local processes. It is deliberately optional: a bind failure simply leaves durable SQLite replay as the synchronization path.

func TerminalSessionRunStatuses added in v1.2.97 

func TerminalSessionRunStatuses() []string

TerminalSessionRunStatuses returns the canonical terminal Run statuses. Callers receive a copy so the shared definition cannot be mutated.

func TransferBinding added in v1.1.77 

func TransferBinding(sessionDir, channelType, channelID, fromSessionID, toSessionID string) error

TransferBinding atomically moves a channel identity from one session to another.

func TryLockRuntime added in v1.1.77 

func TryLockRuntime(sessionDir, sessionID string) (func(), bool)

TryLockRuntime serializes one session across all processes. The process-local mutex remains a fast path, while the SQLite lease is the authority and is automatically renewed until release or lease loss.

func TryLockRuntimes added in v1.1.77 

func TryLockRuntimes(sessionDir string, sessionIDs []string) (func(), bool)

TryLockRuntimes acquires multiple session leases in sorted order. Different sessions remain independently concurrent; ordering only applies to an operation that explicitly spans more than one session.

func UnbindSession added in v1.1.77 

func UnbindSession(sessionDir, sessionID string) error

UnbindSession makes a channel-bound session local while retaining its history.

func UpdateDeliveryOperation added in v1.2.96 

func UpdateDeliveryOperation(ctx context.Context, sessionDir, operationID, owner string, epoch int64, status, providerAssetID, providerMessageID string, providerState json.RawMessage, failureCode string, nextAttemptAt *time.Time) error

UpdateDeliveryOperation applies a fenced provider result. Terminal updates are idempotent when a retry repeats the same result after an unknown commit.

func UpdateDeliveryOperationProgress added in v1.2.96 

func UpdateDeliveryOperationProgress(ctx context.Context, sessionDir, operationID, owner string, epoch int64, status, providerAssetID, providerMessageID string, providerState json.RawMessage, failureCode string) error

UpdateDeliveryOperationProgress persists an in-flight provider phase while retaining the current lease. A subsequent terminal update must use the same owner and epoch, so a stale worker remains fenced throughout upload/send.

func UpdateSessionRunErrorInfo added in v1.2.83 

func UpdateSessionRunErrorInfo(sessionDir, runID string, info json.RawMessage) error

UpdateSessionRunErrorInfo stores the structured terminal/recovery error independently of the compatibility Error summary column.

func UpdateSessionRunProgress added in v1.2.83 

func UpdateSessionRunProgress(sessionDir, runID string, progress json.RawMessage) error

UpdateSessionRunProgress persists the latest non-terminal retry/recovery projection. Terminal callers should clear it with an empty object.

func UpdateSessionRunStatus added in v1.1.77 

func UpdateSessionRunStatus(sessionDir, runID, status, message string, finishedAt *time.Time) error

func UpdateSessionRunUsage added in v1.2.83 

func UpdateSessionRunUsage(sessionDir, runID string, usage, contextUsage json.RawMessage) error

UpdateSessionRunUsage persists token and context-window usage independently from terminalization so reconnects can inspect partial or recovered runs.

func UpdateToolExecutionRecord added in v1.1.77 

func UpdateToolExecutionRecord(sessionDir string, record ToolExecutionRecord) error

func ValidateRuntimeLease added in v1.2.96 

func ValidateRuntimeLease(sessionDir, sessionID, runID string, purpose RuntimeLeasePurpose) error

ValidateRuntimeLease is the context-free compatibility wrapper.

func ValidateRuntimeLeaseContext added in v1.2.96 

func ValidateRuntimeLeaseContext(ctx context.Context, sessionDir, sessionID, runID string, purpose RuntimeLeasePurpose) error

ValidateRuntimeLeaseContext rechecks the process-owned lease binding in a fresh SQLite transaction. It is the final Runtime fence before a side effect; callers must not treat client-provided identity as authority.

func WriteRootDatabase added in v1.1.77 

func WriteRootDatabase(ctx context.Context, sessionDir string, fn func(*dao.Tx) error) error

WriteRootDatabase runs a write transaction against a session root's DAO-owned database. The callback receives the Bun transaction wrapper.

Types

type AdditionalDirectoriesEntry added in v1.2.90 

type AdditionalDirectoriesEntry struct {
	EntryBase
	Directories []string `json:"directories"`
}

AdditionalDirectoriesEntry records the complete ordered directory set granted to a session. Replacements are replayable session entries.

type Binding added in v1.1.77 

type Binding struct {
	SessionID   string `json:"sessionId"`
	ChannelType string `json:"channelType"`
	ChannelID   string `json:"channelId"`
}

Binding describes a current external channel binding.

func FindBinding added in v1.1.77 

func FindBinding(sessionDir, channelType, channelID string) (*Binding, error)

func FindBindingBySessionID added in v1.1.77 

func FindBindingBySessionID(sessionDir, sessionID string) (*Binding, error)

FindBindingBySessionID returns the current external binding for a session.

func ListBindings added in v1.1.77 

func ListBindings(sessionDir string) ([]Binding, error)

type BranchSummaryEntry 

type BranchSummaryEntry struct {
	EntryBase
	Summary string `json:"summary"`
	FromID  string `json:"fromId"`
}

BranchSummaryEntry records a branch switch summary.

type ChannelToolConfig added in v1.1.77 

type ChannelToolConfig struct {
	ToolName string `json:"toolName"`
	Enabled  bool   `json:"enabled"`
}

ChannelToolConfig describes one persisted tool selection for a channel session.

func ListChannelTools added in v1.1.77 

func ListChannelTools(sessionDir, sessionID string) ([]ChannelToolConfig, error)

type CompactionEntry 

type CompactionEntry struct {
	EntryBase
	Summary              string `json:"summary"`
	FirstKeptEntry       string `json:"firstKeptEntryId"`
	TokensBefore         int    `json:"tokensBefore"`
	SummaryVersion       int    `json:"summaryVersion,omitempty"`
	PreviousCompactionID string `json:"previousCompactionId,omitempty"`
	LastSummarizedEntry  string `json:"lastSummarizedEntryId,omitempty"`
}

CompactionEntry records a context compaction.

type ConversationTurn added in v1.2.92 

type ConversationTurn struct {
	ID        string
	SessionID string
	IntentID  string
	RunID     string
	Attempt   int
	Kind      string
	Status    string
	StartSeq  int64
	EndSeq    *int64
	StartedAt time.Time
	EndedAt   *time.Time
}

ConversationTurn is the durable boundary index used by Session fork resolution. It is intentionally separate from SessionRun because a Run may execute tools or maintenance work without producing a conversation turn.

func ListConversationTurns added in v1.2.92 

func ListConversationTurns(sessionDir, sessionID string) ([]ConversationTurn, error)

ListConversationTurns returns boundary rows in transcript order.

type DeliveryIntent added in v1.2.96 

type DeliveryIntent struct {
	ID               string
	SessionID        string
	RunID            string
	Platform         string
	TargetID         string
	ReplyMessageID   string
	TransportContext json.RawMessage
	Status           string
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

DeliveryIntent is the run-level durable outbox identity. TransportContext is opaque Runtime-owned state and must never be projected into prompts or ordinary logs.

type DeliveryOperation added in v1.2.96 

type DeliveryOperation struct {
	ID                string
	IntentID          string
	OperationKey      string
	ArtifactID        string
	OperationKind     string
	Sequence          int
	DependsOn         string
	IdempotencyKey    string
	PayloadDigest     string
	Status            string
	ProviderAssetID   string
	ProviderMessageID string
	ProviderState     json.RawMessage
	AttemptCount      int
	NextAttemptAt     *time.Time
	FailureCode       string
	LeaseOwner        string
	LeaseEpoch        int64
	LeaseExpiresAt    *time.Time
	CreatedAt         time.Time
	UpdatedAt         time.Time
}

DeliveryOperation is one ordered, independently recoverable outbox step.

func ClaimDeliveryOperation added in v1.2.96 

func ClaimDeliveryOperation(ctx context.Context, sessionDir, operationID, owner string, now time.Time, lease time.Duration) (*DeliveryOperation, error)

ClaimDeliveryOperation atomically claims the next due operation. The lease epoch is incremented on every claim, so a delayed worker cannot overwrite a later retry after its lease expires.

func GetDeliveryOperation added in v1.2.96 

func GetDeliveryOperation(ctx context.Context, sessionDir, operationID string) (*DeliveryOperation, error)

GetDeliveryOperation loads one operation without exposing transport credentials or requiring callers to know its parent intent ID.

func ListDueDeliveryOperations added in v1.2.96 

func ListDueDeliveryOperations(ctx context.Context, sessionDir string, now time.Time) ([]DeliveryOperation, error)

ListDueDeliveryOperations returns recoverable operations whose retry time is due or whose previous worker lease has expired. It is intentionally a read; callers must claim each row through ClaimDeliveryOperation before executing.

type DeliveryPlan added in v1.2.96 

type DeliveryPlan struct {
	Intent     DeliveryIntent
	Operations []DeliveryOperation
}

DeliveryPlan is created in the same transaction that terminalizes its Run.

func GetDeliveryPlan added in v1.2.96 

func GetDeliveryPlan(ctx context.Context, sessionDir, intentID string) (*DeliveryPlan, error)

GetDeliveryPlan loads one intent and its operations in execution order.

type ESMGuidance added in v1.2.83 

type ESMGuidance struct {
	ID               string     `json:"id"`
	SessionID        string     `json:"sessionId"`
	ObjectiveVersion string     `json:"objectiveVersion,omitempty"`
	Guidance         string     `json:"guidance"`
	Status           string     `json:"status"`
	CreatedAt        time.Time  `json:"createdAt"`
	ConsumedAt       *time.Time `json:"consumedAt,omitempty"`
}

func ListESMGuidance added in v1.2.83 

func ListESMGuidance(sessionDir, sessionID, status string, limit int) ([]ESMGuidance, error)

type EntryBase 

type EntryBase struct {
	Type      EntryType `json:"type"`
	ID        string    `json:"id"`
	ParentID  *string   `json:"parentId"`
	Timestamp time.Time `json:"timestamp"`
}

EntryBase contains common fields for all session entries.

type EntryType 

type EntryType string

EntryType identifies the type of a session entry. 

const (
	EntrySession               EntryType = "session"
	EntryMessage               EntryType = "message"
	EntryModelChange           EntryType = "model_change"
	EntryModeChange            EntryType = "mode_change"
	EntryThinkingChange        EntryType = "thinking_level_change"
	EntryAdditionalDirectories EntryType = "additional_directories"
	EntryCompaction            EntryType = "compaction"
	EntryBranchSummary         EntryType = "branch_summary"
	EntryCustom                EntryType = "custom"
	EntryCustomMessage         EntryType = "custom_message"
	EntryLabel                 EntryType = "label"
	EntrySessionInfo           EntryType = "session_info"
	EntryTurnStart             EntryType = "turn_start"
	EntryTurnEnd               EntryType = "turn_end"
)

type ExecutionIntent added in v1.2.83 

type ExecutionIntent struct {
	ID                 string
	SessionID          string
	Source             string
	Model              string
	Mode               string
	WorkDir            string
	RequestFingerprint string
	Request            json.RawMessage
	Policy             json.RawMessage
	CreatedAt          time.Time
}

ExecutionIntent is the durable, adapter-neutral record of an accepted user request. Request and policy snapshots are opaque to session storage; the shared Runtime owns their interpretation.

func GetExecutionIntent added in v1.2.83 

func GetExecutionIntent(sessionDir, intentID string) (*ExecutionIntent, error)

type ForkKind added in v1.2.92 

type ForkKind string
const (
	ForkKindSession ForkKind = "session"
	ForkKindMessage ForkKind = "message"
	ForkKindUnknown ForkKind = ""
)

type ForkOptions added in v1.2.92 

type ForkOptions struct {
	SourceSessionID string
	AtSeq           *int64
	RequestID       string
	TitleMode       string
}

type ForkResult added in v1.2.92 

type ForkResult struct {
	SessionID       string   `json:"sessionId"`
	ParentSessionID string   `json:"parentSessionId"`
	ForkKind        ForkKind `json:"forkKind"`
	BoundarySeq     int64    `json:"boundarySeq"`
	SeedLength      int64    `json:"seedLength"`
}

func ForkSession added in v1.2.92 

func ForkSession(ctx context.Context, sessionDir string, options ForkOptions) (ForkResult, error)
type Header struct {
	Type            EntryType `json:"type"`
	Version         int       `json:"version"`
	ID              string    `json:"id"`
	Timestamp       time.Time `json:"timestamp"`
	Cwd             string    `json:"cwd"`
	ParentSession   string    `json:"parentSession,omitempty"`
	ChannelType     string    `json:"channelType,omitempty"`
	ChannelID       string    `json:"channelId,omitempty"`
	ForkBoundarySeq int64     `json:"forkBoundarySeq,omitempty"`
	SeedLength      int64     `json:"seedLength,omitempty"`
	ForkKind        string    `json:"forkKind,omitempty"`
}

Header is the first line of a session file.

type IdentityLocks added in v1.1.77 

type IdentityLocks struct {
	// contains filtered or unexported fields
}

IdentityLocks serializes operations for one external channel identity. It is shared by inbound dispatch and session lifecycle management. Entries are evicted once the last holder releases them so the map does not grow without bound in long-running processes.

func NewIdentityLocks added in v1.1.77 

func NewIdentityLocks() *IdentityLocks

func (*IdentityLocks) Lock added in v1.1.77 

func (s *IdentityLocks) Lock(channelType, channelID string) func()

type InputResourceEvent added in v1.2.96 

type InputResourceEvent struct {
	ID         string
	SessionID  string
	ResourceID string
	RunID      string
	EventType  string
	Status     string
	Timestamp  time.Time
	Data       json.RawMessage
}

InputResourceEvent is the canonical lifecycle projection for one Runtime materialized resource. Transport references are intentionally absent.

func ListInputResourceEvents added in v1.2.96 

func ListInputResourceEvents(ctx context.Context, sessionDir, sessionID string) ([]InputResourceEvent, error)

ListInputResourceEvents returns resource lifecycle events in durable order.

type LabelEntry 

type LabelEntry struct {
	EntryBase
	TargetID string  `json:"targetId"`
	Label    *string `json:"label,omitempty"`
}

LabelEntry records a user-defined label on an entry.

type ListOption added in v1.1.77 

type ListOption func(*listOptions)

func WithLimit added in v1.1.77 

func WithLimit(limit int) ListOption

func WithMessagesOnly added in v1.2.83 

func WithMessagesOnly() ListOption

WithMessagesOnly limits session listings to sessions containing at least one persisted conversation message. This avoids loading transient empty sessions during history pagination.

func WithOffset added in v1.1.77 

func WithOffset(offset int) ListOption

func WithSearch added in v1.2.83 

func WithSearch(search string) ListOption

WithSearch filters sessions by ID, work directory, channel metadata, or persisted message/session-info content. It is intended for session listings.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages a single session's state and persistence.

func ContinueRecent 

func ContinueRecent(cwd, sessionDir string) (*Manager, error)

ContinueRecent continues the most recent session for a directory, or creates new.

func CreateBound added in v1.1.77 

func CreateBound(workDir, sessionDir, channelType, channelID string) (*Manager, error)

func New 

func New(cwd, sessionDir string) *Manager

New creates a new session manager for a new session.

func NewSubAgent added in v1.1.62 

func NewSubAgent(cwd, sessionDir string) *Manager

NewSubAgent creates a session manager whose records are stored separately from user-continuable sessions.

func Open 

func Open(path string) (*Manager, error)

Open opens an existing session file.

func OpenByID 

func OpenByID(cwd, sessionDir, sessionID string) (*Manager, error)

OpenByID opens the session for cwd whose session ID matches sessionID. Supports prefix matching — if sessionID matches multiple sessions, an error is returned.

func OpenByIDExact 

func OpenByIDExact(sessionDir, sessionID string) (*Manager, error)

OpenByIDExact opens a session by exact session ID regardless of cwd.

func OpenByPathOrID 

func OpenByPathOrID(cwd, sessionDir, value string) (*Manager, error)

OpenByPathOrID opens a session using either an explicit file path or a session ID for the supplied working directory.

func RotateBoundSession added in v1.1.77 

func RotateBoundSession(workDir, sessionDir, channelType, channelID, oldSessionID string) (*Manager, error)

RotateBoundSession atomically creates a new bound session and clears the old one.

func (*Manager) AppendAdditionalDirectories added in v1.2.90 

func (m *Manager) AppendAdditionalDirectories(directories []string) (string, error)

AppendAdditionalDirectories records a complete replacement of the session's additional directory roots.

func (*Manager) AppendCompaction 

func (m *Manager) AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

AppendCompaction records a context compaction.

func (*Manager) AppendMessage 

func (m *Manager) AppendMessage(msg provider.Message) (string, error)

AppendMessage adds a message entry.

func (*Manager) AppendModeChange added in v1.2.90 

func (m *Manager) AppendModeChange(mode string) (string, error)

AppendModeChange records a session execution mode change.

func (*Manager) AppendModelChange 

func (m *Manager) AppendModelChange(providerName, modelID string) (string, error)

AppendModelChange records a model change.

func (*Manager) AppendSessionInfo 

func (m *Manager) AppendSessionInfo(name string) (string, error)

AppendSessionInfo records a session display name. It is retained for compatibility; new callers should use AppendSessionTitle with a source.

func (*Manager) AppendSessionTitle added in v1.2.83 

func (m *Manager) AppendSessionTitle(name, source string) (string, error)

AppendSessionTitle records a session display name and its origin.

func (*Manager) AppendThinkingLevelChange 

func (m *Manager) AppendThinkingLevelChange(level string) (string, error)

AppendThinkingLevelChange records a thinking level change.

func (*Manager) EndConversationTurn added in v1.2.92 

func (m *Manager) EndConversationTurn(turnID, status, stopReason string) error

EndConversationTurn closes the durable boundary used by Session fork resolution. It is safe for callers to report failed, cancelled and incomplete outcomes; all are terminal turn states.

func (*Manager) GetFile 

func (m *Manager) GetFile() string

GetFile returns the session file path.

func (*Manager) GetHeader 

func (m *Manager) GetHeader() *Header

GetHeader returns the session header.

func (*Manager) GetLatestAdditionalDirectories added in v1.2.90 

func (m *Manager) GetLatestAdditionalDirectories() (AdditionalDirectoriesEntry, bool)

GetLatestAdditionalDirectories returns the latest complete directory-root binding persisted in this session.

func (*Manager) GetLatestCompaction 

func (m *Manager) GetLatestCompaction() (CompactionEntry, bool)

GetLatestCompaction returns the newest compaction entry in the current session.

func (*Manager) GetLatestModeChange added in v1.2.90 

func (m *Manager) GetLatestModeChange() (ModeChangeEntry, bool)

GetLatestModeChange returns the newest session mode in the session.

func (*Manager) GetLatestModelChange added in v1.2.90 

func (m *Manager) GetLatestModelChange() (ModelChangeEntry, bool)

GetLatestModelChange returns the newest model binding in the session.

func (*Manager) GetLatestThinkingLevelChange added in v1.2.90 

func (m *Manager) GetLatestThinkingLevelChange() (ThinkingLevelChangeEntry, bool)

GetLatestThinkingLevelChange returns the newest thinking level in the session.

func (*Manager) GetLeafID 

func (m *Manager) GetLeafID() *string

GetLeafID returns the current leaf entry ID.

func (*Manager) GetMessages 

func (m *Manager) GetMessages() []provider.Message

GetMessages extracts all messages from the current branch.

func (*Manager) GetReplayState 

func (m *Manager) GetReplayState() ReplayState

GetReplayState returns the current branch after applying compaction entries.

func (*Manager) GetSessionDir added in v1.1.77 

func (m *Manager) GetSessionDir() string

GetSessionDir returns the root directory containing this manager's shared sessions database. Runtime extensions use it for auxiliary session tables.

func (*Manager) Init 

func (m *Manager) Init() error

Init initializes a new session with an auto-generated session ID. Must be called before appending entries.

func (*Manager) InitWithBinding added in v1.1.77 

func (m *Manager) InitWithBinding(channelType, channelID string) error

InitWithBinding initializes a new session with a channel binding.

func (*Manager) InitWithID 

func (m *Manager) InitWithID(id string) error

InitWithID initializes a new session using the provided session ID. If id is empty, a new random ID is generated.

func (*Manager) InitWithIDAndBinding added in v1.1.77 

func (m *Manager) InitWithIDAndBinding(id, channelType, channelID string) error

InitWithIDAndBinding initializes a session with a specific ID and channel binding.

func (*Manager) RecordUsage 

func (m *Manager) RecordUsage(provider, protocol, model string, inputTokens, outputTokens, totalTokens, durationMs int) error

RecordUsage records a single LLM request's token usage and timing.

func (*Manager) RecordUsageFromProviderUsage 

func (m *Manager) RecordUsageFromProviderUsage(provider, protocol, model string, usage *provider.Usage, durationMs int) error

RecordUsageFromProviderUsage records usage from a provider.Usage struct.

func (*Manager) Reload added in v1.1.77 

func (m *Manager) Reload() error

Reload refreshes a manager from the shared SQLite session database. Serve entry points may retain a Manager while another UI writes the same session; reload after acquiring the session runtime lock so the next append uses the current leaf instead of an old optimistic-lock parent.

func (*Manager) SetSessionBinding added in v1.1.77 

func (m *Manager) SetSessionBinding(channelType, channelID string) error

SetSessionBinding updates a Manager's in-memory header after a binding change.

func (*Manager) StartConversationTurn added in v1.2.92 

func (m *Manager) StartConversationTurn(turnID, intentID, runID string) error

StartConversationTurn opens the durable boundary used by Session fork resolution. It is intentionally optional on session.Store so transient and in-memory agents do not need a SQLite turn index.

type MemoryStore 

type MemoryStore struct {
	// contains filtered or unexported fields
}

MemoryStore is an in-memory implementation of Store for testing. It does not persist data to disk.

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

NewMemoryStore creates a new in-memory session store.

func (*MemoryStore) AppendAdditionalDirectories added in v1.2.90 

func (m *MemoryStore) AppendAdditionalDirectories(directories []string) (string, error)

func (*MemoryStore) AppendCompaction 

func (m *MemoryStore) AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

func (*MemoryStore) AppendMessage 

func (m *MemoryStore) AppendMessage(msg provider.Message) (string, error)

func (*MemoryStore) AppendModeChange added in v1.2.90 

func (m *MemoryStore) AppendModeChange(mode string) (string, error)

func (*MemoryStore) AppendModelChange 

func (m *MemoryStore) AppendModelChange(providerName, modelID string) (string, error)

func (*MemoryStore) AppendSessionInfo 

func (m *MemoryStore) AppendSessionInfo(name string) (string, error)

func (*MemoryStore) AppendThinkingLevelChange 

func (m *MemoryStore) AppendThinkingLevelChange(level string) (string, error)

func (*MemoryStore) GetFile 

func (m *MemoryStore) GetFile() string

func (*MemoryStore) GetHeader 

func (m *MemoryStore) GetHeader() *Header

func (*MemoryStore) GetLatestAdditionalDirectories added in v1.2.90 

func (m *MemoryStore) GetLatestAdditionalDirectories() (AdditionalDirectoriesEntry, bool)

func (*MemoryStore) GetLatestCompaction 

func (m *MemoryStore) GetLatestCompaction() (CompactionEntry, bool)

func (*MemoryStore) GetLatestModeChange added in v1.2.90 

func (m *MemoryStore) GetLatestModeChange() (ModeChangeEntry, bool)

func (*MemoryStore) GetLatestModelChange added in v1.2.90 

func (m *MemoryStore) GetLatestModelChange() (ModelChangeEntry, bool)

func (*MemoryStore) GetLatestThinkingLevelChange added in v1.2.90 

func (m *MemoryStore) GetLatestThinkingLevelChange() (ThinkingLevelChangeEntry, bool)

func (*MemoryStore) GetLeafID 

func (m *MemoryStore) GetLeafID() *string

func (*MemoryStore) GetMessages 

func (m *MemoryStore) GetMessages() []provider.Message

func (*MemoryStore) GetReplayState 

func (m *MemoryStore) GetReplayState() ReplayState

func (*MemoryStore) Init 

func (m *MemoryStore) Init() error

func (*MemoryStore) InitWithID 

func (m *MemoryStore) InitWithID(id string) error

type MessageEntry 

type MessageEntry struct {
	EntryBase
	Message provider.Message `json:"message"`
}

MessageEntry contains a conversation message.

type ModeChangeEntry added in v1.2.90 

type ModeChangeEntry struct {
	EntryBase
	Mode string `json:"mode"`
}

ModeChangeEntry records a session execution mode change.

type ModelChangeEntry 

type ModelChangeEntry struct {
	EntryBase
	Provider string `json:"provider"`
	ModelID  string `json:"modelId"`
}

ModelChangeEntry records a model switch.

func LatestModelChangeByID added in v1.2.95 

func LatestModelChangeByID(sessionDir, sessionID string) (ModelChangeEntry, bool, error)

LatestModelChangeByID reads the replayed provider/model binding for a session without exposing SQLite details to protocol adapters.

type Project added in v1.2.83 

type Project struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

func CreateProject added in v1.2.83 

func CreateProject(sessionDir, name string) (Project, error)

func ListProjects added in v1.2.83 

func ListProjects(sessionDir string) ([]Project, error)

func RenameProject added in v1.2.83 

func RenameProject(sessionDir, id, name string) (Project, error)

type ReplayState 

type ReplayState struct {
	Messages []provider.Message
	EntryIDs []string
}

ReplayState is the reconstructed conversation state after applying compactions.

type ResponseItemArchive added in v1.1.77 

type ResponseItemArchive struct {
	ID            int64
	SessionID     string
	LocalTurnID   string
	ResponseID    string
	ItemID        string
	OutputIndex   int
	ItemType      string
	ItemStatus    string
	ItemKey       string
	SanitizedJSON json.RawMessage
	CreatedAt     time.Time
}

ResponseItemArchive stores one sanitized normalized item. Raw provider request/response bodies must not be passed here.

func ListResponseItems added in v1.1.77 

func ListResponseItems(sessionDir, sessionID, localTurnID string) ([]ResponseItemArchive, error)

type ResponseReplayTurn added in v1.1.77 

type ResponseReplayTurn struct {
	LocalTurnID string
	Items       []json.RawMessage
}

ResponseReplayTurn groups the native output items belonging to one local Responses turn. It lets callers place those items at the corresponding assistant position while rebuilding a complete local conversation.

func ListResponseReplayTurns added in v1.1.77 

func ListResponseReplayTurns(sessionDir, sessionID string, limit int) ([]ResponseReplayTurn, error)

ListResponseReplayTurns returns completed native output grouped by local turn, ordered by their original completion order.

type ResponseRun added in v1.1.77 

type ResponseRun struct {
	ID                int64     `json:"id"`
	SessionID         string    `json:"sessionId"`
	LocalRunID        string    `json:"localRunId"`
	LocalTurnID       string    `json:"localTurnId,omitempty"`
	MessageID         *int64    `json:"messageId,omitempty"`
	ResponseID        string    `json:"responseId,omitempty"`
	Provider          string    `json:"provider"`
	API               string    `json:"api"`
	State             string    `json:"state"`
	PollingURL        string    `json:"pollingUrl,omitempty"`
	LastEventSequence *int64    `json:"lastEventSequence,omitempty"`
	CancelRequested   bool      `json:"cancelRequested,omitempty"`
	CreatedAt         time.Time `json:"createdAt"`
	UpdatedAt         time.Time `json:"updatedAt"`
}

ResponseRun is the durable state for a Responses background run.

func GetResponseRun added in v1.1.77 

func GetResponseRun(sessionDir, sessionID, localRunID string) (*ResponseRun, error)

func ListResponseRuns added in v1.1.77 

func ListResponseRuns(sessionDir, sessionID string, limit int) ([]ResponseRun, error)

type ResponseSessionState added in v1.1.77 

type ResponseSessionState struct {
	SessionID          string
	StateMode          string
	PreviousResponseID string
	ConversationID     string
	Provider           string
	API                string
	Model              string
	Version            int64
	UpdatedAt          time.Time
}

ResponseSessionState is the compare-and-swap protected remote lineage for a single local session. Provider config supplies defaults; this record keeps concurrent sessions and concurrent turns from sharing mutable remote state.

func GetResponseSessionState added in v1.1.77 

func GetResponseSessionState(sessionDir, sessionID string) (*ResponseSessionState, error)

GetResponseSessionState returns the durable remote lineage for a local session. A missing record means the caller must use its configured default, normally replay mode.

type ResponseTurn added in v1.1.77 

type ResponseTurn struct {
	ID                 int64
	SessionID          string
	LocalTurnID        string
	MessageID          *int64
	RequestID          string
	ResponseID         string
	PreviousResponseID string
	ConversationID     string
	Provider           string
	API                string
	Model              string
	StateMode          string
	Status             string
	IncompleteReason   string
	RequestSummary     json.RawMessage
	ResponseSummary    json.RawMessage
	CreatedAt          time.Time
	CompletedAt        *time.Time
}

ResponseTurn is the durable lineage and lifecycle summary for one Responses API turn. It intentionally contains summaries, not a second transcript.

func GetResponseTurn added in v1.1.77 

func GetResponseTurn(sessionDir, sessionID, localTurnID string) (*ResponseTurn, error)

type RuntimeLeaseBinding added in v1.2.96 

type RuntimeLeaseBinding struct {
	DatabaseIdentity string
	SessionID        string
	RunID            string
	OwnerInstanceID  string
	TokenHash        string
	Epoch            int64
	Purpose          RuntimeLeasePurpose
}

RuntimeLeaseBinding is the Runtime-owned identity of an acquired Session lease. It is safe to expose to trusted in-process code for diagnostics and matching, but must never be accepted from an adapter or client as authority.

func BindRuntimeLeaseToExistingRun added in v1.2.96 

func BindRuntimeLeaseToExistingRun(sessionDir, sessionID, runID string) (RuntimeLeaseBinding, error)

BindRuntimeLeaseToExistingRun promotes a recovery/legacy lease to execution only while the expected Run is still the Session's sole non-terminal Run. Reattach paths call this before registering an in-memory execution.

func CurrentRuntimeLeaseBinding added in v1.2.96 

func CurrentRuntimeLeaseBinding(sessionDir, sessionID string) (RuntimeLeaseBinding, bool)

CurrentRuntimeLeaseBinding returns the lease identity held by this process. It is intended for internal/agentruntime registration and diagnostics only; durable control operations must still revalidate the database row.

func RetainRuntimeLease added in v1.2.96 

func RetainRuntimeLease(sessionDir, sessionID, runID string) (RuntimeLeaseBinding, func(), bool, error)

RetainRuntimeLease adds a Runtime-owned reference to the current execution lease. The caller-owned RuntimeLeaseGuard may be released independently; the durable lease remains active until the returned release function is called. This is intentionally an in-process handoff primitive, never a client-facing authorization mechanism.

type RuntimeLeaseGroup added in v1.2.96 

type RuntimeLeaseGroup struct {
	// contains filtered or unexported fields
}

RuntimeLeaseGroup owns an ordered set of Session leases acquired for one multi-Session mutation.

func AcquireMutations added in v1.2.96 

func AcquireMutations(sessionDir string, sessionIDs []string) (*RuntimeLeaseGroup, error)

AcquireMutations reserves multiple idle Sessions in stable order so a cross-Session mutation cannot deadlock another caller taking the same set.

func (*RuntimeLeaseGroup) Release added in v1.2.96 

func (g *RuntimeLeaseGroup) Release()

Release relinquishes grouped leases in reverse acquisition order.

type RuntimeLeaseGuard added in v1.2.96 

type RuntimeLeaseGuard struct {
	// contains filtered or unexported fields
}

RuntimeLeaseGuard owns both the process-local mutex and the durable SQLite lease. Release is idempotent and must be called after every successful acquisition.

func AcquireExecutionAdmission added in v1.2.96 

func AcquireExecutionAdmission(sessionDir, sessionID string) (*RuntimeLeaseGuard, error)

AcquireExecutionAdmission reserves an existing idle Session for a new Run. The durable admission transaction must subsequently bind the new run ID and transition this same lease to purpose=execution.

func AcquireFork added in v1.2.96 

func AcquireFork(sessionDir, sessionID string) (*RuntimeLeaseGuard, error)

AcquireFork reserves an idle source Session while a child snapshot is made.

func AcquireMutation added in v1.2.96 

func AcquireMutation(sessionDir, sessionID string) (*RuntimeLeaseGuard, error)

AcquireMutation reserves an idle Session for a short non-execution change.

func AcquireRecovery added in v1.2.96 

func AcquireRecovery(sessionDir, sessionID, expectedRunID string) (*RuntimeLeaseGuard, error)

AcquireRecovery claims an unowned or expired active Run for fenced recovery.

func AcquireRecoveryContext added in v1.2.96 

func AcquireRecoveryContext(ctx context.Context, sessionDir, sessionID, expectedRunID string) (*RuntimeLeaseGuard, error)

AcquireRecoveryContext bounds the lease acquisition transaction by the recovery attempt deadline.

func (*RuntimeLeaseGuard) Binding added in v1.2.96 

func (g *RuntimeLeaseGuard) Binding() RuntimeLeaseBinding

Binding returns the exact identity acquired by this process.

func (*RuntimeLeaseGuard) Lost added in v1.2.96 

func (g *RuntimeLeaseGuard) Lost() <-chan struct{}

Lost reports when the durable lease can no longer be renewed.

func (*RuntimeLeaseGuard) Release added in v1.2.96 

func (g *RuntimeLeaseGuard) Release()

Release relinquishes the durable lease and then the process-local mutex.

type RuntimeLeaseNotification added in v1.2.95 

type RuntimeLeaseNotification struct {
	Version          int    `json:"version"`
	MessageID        string `json:"messageId"`
	Type             string `json:"type"`
	SessionID        string `json:"sessionId"`
	Origin           string `json:"origin,omitempty"`
	OriginInstanceID string `json:"originInstanceId"`
	OwnerInstanceID  string `json:"ownerInstanceId,omitempty"`
	Epoch            int64  `json:"epoch,omitempty"`
	ExpiresAt        int64  `json:"expiresAt,omitempty"`
}

RuntimeLeaseNotification is a best-effort local-process wake-up signal. SQLite leases and durable Run rows remain the sole authority: receivers must always re-read the database before projecting any state to a client.

Threat model: the UDP bus is unauthenticated. Any process on the same host can send spoofed notifications (only the loopback source address is checked). This is acceptable because notifications are advisory only; every receiver re-validates against the authoritative SQLite lease and Run rows before acting, so a forged packet can at most trigger a redundant database re-read, never an ownership change.

type RuntimeLeasePurpose added in v1.2.96 

type RuntimeLeasePurpose string

RuntimeLeasePurpose describes why a process owns the Session-wide lease. Legacy rows use RuntimeLeasePurposeLegacyRun until all callers have migrated to an explicit purpose. 

const (
	RuntimeLeasePurposeLegacyRun RuntimeLeasePurpose = "run"
	RuntimeLeasePurposeAdmission RuntimeLeasePurpose = "admission"
	RuntimeLeasePurposeExecution RuntimeLeasePurpose = "execution"
	RuntimeLeasePurposeRecovery  RuntimeLeasePurpose = "recovery"
	RuntimeLeasePurposeMutation  RuntimeLeasePurpose = "mutation"
	RuntimeLeasePurposeFork      RuntimeLeasePurpose = "fork"
)

type RuntimeLeaseSnapshot added in v1.2.96 

type RuntimeLeaseSnapshot struct {
	SessionID       string
	OwnerInstanceID string
	OwnerPID        int
	OwnerKind       string
	TokenHash       string
	Epoch           int64
	RunID           string
	Purpose         RuntimeLeasePurpose
	State           string
	AcquiredAt      time.Time
	HeartbeatAt     time.Time
	ExpiresAt       time.Time
	UpdatedAt       time.Time
	Valid           bool
}

RuntimeLeaseSnapshot is an immutable database view of one Session lease. TokenHash is an internal identity component used only for matching a Runtime-owned binding; callers must never accept it back as authorization.

type RuntimeSubmission added in v1.2.96 

type RuntimeSubmission struct {
	ID                 string
	SessionID          string
	Scope              string
	KeyHash            string
	RequestFingerprint string
	IntentID           string
	RunID              string
	CreatedAt          time.Time
}

RuntimeSubmission is the durable admission identity for one original or retry submission. Only a digest of the transport key is persisted.

func GetRuntimeSubmission added in v1.2.96 

func GetRuntimeSubmission(ctx context.Context, sessionDir, sessionID, scope, keyHash string) (*RuntimeSubmission, error)

type RuntimeSubmissionError added in v1.2.96 

type RuntimeSubmissionError struct {
	Existing RuntimeSubmission
	Conflict bool
}

RuntimeSubmissionError carries the canonical Run identity selected by a competing or replayed admission.

func (*RuntimeSubmissionError) Error added in v1.2.96 

func (e *RuntimeSubmissionError) Error() string

func (*RuntimeSubmissionError) Unwrap added in v1.2.96 

func (e *RuntimeSubmissionError) Unwrap() error

type SequencedMessage added in v1.1.61 

type SequencedMessage struct {
	Seq     int64
	EntryID string
	Message provider.Message
}

SequencedMessage is a persisted conversation message with its entries.seq cursor.

func ListSessionMessagesAfter added in v1.1.61 

func ListSessionMessagesAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedMessage, error)

ListSessionMessagesAfter returns persisted message rows after entries.seq.

func ListSessionMessagesBefore added in v1.1.77 

func ListSessionMessagesBefore(sessionDir, sessionID string, beforeSeq int64, limit int) ([]SequencedMessage, error)

ListSessionMessagesBefore returns messages with seq < beforeSeq, newest first limited to `limit`.

func ListSessionMessagesLatest added in v1.1.77 

func ListSessionMessagesLatest(sessionDir, sessionID string, limit int) ([]SequencedMessage, error)

ListSessionMessagesLatest returns the latest N message entries (highest seq first).

func ListSessionMessagesWithSeq added in v1.1.61 

func ListSessionMessagesWithSeq(sessionDir, sessionID string) ([]SequencedMessage, error)

ListSessionMessagesWithSeq returns the visible replay messages for a session, preserving each message row's entries.seq cursor.

type SequencedSessionCapabilityEvent added in v1.1.61 

type SequencedSessionCapabilityEvent struct {
	Seq   int64
	Event SessionCapabilityEvent
}

SequencedSessionCapabilityEvent is a capability event with its table cursor.

func ListSessionCapabilityEventsAfter added in v1.1.61 

func ListSessionCapabilityEventsAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedSessionCapabilityEvent, error)

ListSessionCapabilityEventsAfter returns capability events after session_capability_events.seq.

func ListSessionCapabilityEventsWithSeq added in v1.1.61 

func ListSessionCapabilityEventsWithSeq(sessionDir, sessionID string) ([]SequencedSessionCapabilityEvent, error)

ListSessionCapabilityEventsWithSeq returns capability events with their seq cursor.

type SequencedSessionRunEvent added in v1.1.61 

type SequencedSessionRunEvent struct {
	Seq   int64
	Event SessionRunEvent
}

SequencedSessionRunEvent is a run lifecycle event with its table cursor.

func ListSessionRunEventsAfter added in v1.1.61 

func ListSessionRunEventsAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedSessionRunEvent, error)

ListSessionRunEventsAfter returns run events after session_run_events.seq.

func ListSessionRunEventsWithSeq added in v1.1.61 

func ListSessionRunEventsWithSeq(sessionDir, sessionID string) ([]SequencedSessionRunEvent, error)

ListSessionRunEventsWithSeq returns run events with their session_run_events.seq cursor.

type SessionCapabilities added in v1.1.61 

type SessionCapabilities struct {
	SessionID    string
	Mode         string
	DisplayMode  string
	DelegateMode bool
	MultiAgent   bool
	Workflows    bool
	WebSearch    bool
	Browser      bool
	A2AMaster    bool
	UpdatedAt    time.Time
}

SessionCapabilities stores persisted per-session runtime capability state.

func LoadSessionCapabilities added in v1.1.61 

func LoadSessionCapabilities(sessionDir, sessionID string) (*SessionCapabilities, bool, error)

LoadSessionCapabilities loads persisted capabilities for a session.

type SessionCapabilityEvent added in v1.1.61 

type SessionCapabilityEvent struct {
	ID         string
	SessionID  string
	RunID      string
	EventType  string
	Source     string
	Actor      string
	Capability string
	OldValue   string
	NewValue   string
	Timestamp  time.Time
	Data       json.RawMessage
}

SessionCapabilityEvent records one capability state transition.

func ListSessionCapabilityEvents added in v1.1.61 

func ListSessionCapabilityEvents(sessionDir, sessionID string) ([]SessionCapabilityEvent, error)

ListSessionCapabilityEvents returns capability events for a session, ordered by insertion.

type SessionDetail 

type SessionDetail struct {
	SessionInfo
	ID           string
	MessageCount int
	Preview      string // first user message (truncated)
}

SessionDetail contains detailed metadata about a session for display.

func ListAllDetailed added in v1.1.61 

func ListAllDetailed(sessionDir string, opts ...ListOption) ([]SessionDetail, error)

ListAllDetailed lists sessions with details across all working directories.

func ListForDirDetailed 

func ListForDirDetailed(cwd, sessionDir string) ([]SessionDetail, error)

ListForDirDetailed lists sessions with details (ID, message count, preview).

type SessionExecutionFacts added in v1.2.96 

type SessionExecutionFacts struct {
	DatabaseIdentity string
	SessionID        string
	SessionExists    bool
	DatabaseNow      time.Time
	ActiveRuns       []SessionRun
	Lease            *RuntimeLeaseSnapshot
	Recovery         *SessionRunRecovery
	RemoteRun        *ResponseRun
}

SessionExecutionFacts contains the durable Run and lease rows observed from one SQLite read transaction and one SQLite clock sample. ActiveRuns normally contains at most one row; retaining the slice lets Runtime surface corrupted or legacy databases with multiple active rows as inconsistent.

func ReadSessionExecutionFacts added in v1.2.96 

func ReadSessionExecutionFacts(sessionDir, sessionID string) (SessionExecutionFacts, error)

ReadSessionExecutionFacts reads the durable execution facts for one Session from a single transaction. It deliberately does not consult process-local runtime state; internal/agentruntime combines this immutable view with its own registered execution bindings.

func ReadSessionExecutionFactsContext added in v1.2.96 

func ReadSessionExecutionFactsContext(ctx context.Context, sessionDir, sessionID string) (SessionExecutionFacts, error)

ReadSessionExecutionFactsContext is the cancellable form used by bounded recovery attempts. The transaction and every query in the snapshot share the caller's deadline.

type SessionInfo 

type SessionInfo struct {
	Path            string
	ModTime         time.Time
	Name            string
	Cwd             string
	ChannelType     string
	ChannelID       string
	ParentSession   string
	ForkBoundarySeq int64
	SeedLength      int64
	ForkKind        string
}

SessionInfo contains metadata about a session file.

func ListAll added in v1.1.61 

func ListAll(sessionDir string, opts ...ListOption) ([]SessionInfo, error)

ListAll lists session files across all working directories.

func ListForDir 

func ListForDir(cwd, sessionDir string) ([]SessionInfo, error)

ListForDir lists session files for a given working directory.

type SessionInfoEntry 

type SessionInfoEntry struct {
	EntryBase
	Name   string `json:"name"`
	Source string `json:"source,omitempty"` // "manual" or "auto"
}

SessionInfoEntry stores session metadata.

type SessionMetadata added in v1.2.83 

type SessionMetadata struct {
	ProjectID string `json:"projectId,omitempty"`
	Pinned    bool   `json:"pinned"`
}

func GetSessionMetadata added in v1.2.83 

func GetSessionMetadata(sessionDir, sessionID string) (SessionMetadata, error)

type SessionRun added in v1.1.77 

type SessionRun struct {
	ID           string
	SessionID    string
	IntentID     string
	RetryOf      string
	Attempt      int
	WorkDir      string
	Source       string
	Model        string
	Mode         string
	Status       string
	StartedAt    time.Time
	UpdatedAt    time.Time
	FinishedAt   *time.Time
	Error        string
	ErrorInfo    json.RawMessage
	Progress     json.RawMessage
	Usage        json.RawMessage
	ContextUsage json.RawMessage
	// InputResourceIDs are Runtime-prepared resources admitted with this Run.
	// They are bound by the same transaction as the intent/run/start event.
	InputResourceIDs []string
	// Submission fields are admission-only digests. They are reserved in the
	// same transaction as the intent, Run, turn, resources, and start event.
	SubmissionKeyHash     string
	SubmissionScope       string
	SubmissionFingerprint string
	// UserMessage is the canonical user entry admitted with a conversation
	// Run. It is admission-only; transcript replay remains the source of truth.
	UserEntryID string
	UserMessage *provider.Message
	// AssistantMessage is the final assistant entry held by the Runtime until
	// terminalization. It is intentionally transient and is committed together
	// with the terminal Run/turn and delivery plan.
	AssistantEntryID string
	AssistantMessage *provider.Message
	// DeliveryPlan is terminal-only. The terminal transaction creates its
	// outbox rows together with the Run, turn, and terminal event transition.
	DeliveryPlan *DeliveryPlan
}

SessionRun is the durable lifecycle record for one agent execution.

func GetActiveSessionRun added in v1.1.77 

func GetActiveSessionRun(sessionDir, sessionID string) (*SessionRun, error)

func GetActiveSessionRunContext added in v1.2.96 

func GetActiveSessionRunContext(ctx context.Context, sessionDir, sessionID string) (*SessionRun, error)

func GetSessionRun added in v1.1.77 

func GetSessionRun(sessionDir, runID string) (*SessionRun, error)

func GetSessionRunContext added in v1.2.96 

func GetSessionRunContext(ctx context.Context, sessionDir, runID string) (*SessionRun, error)

func LatestSessionRunForIntent added in v1.2.83 

func LatestSessionRunForIntent(sessionDir, sessionID, intentID string) (*SessionRun, error)

LatestSessionRunForIntent returns the highest-attempt Run in an immutable intent chain. Retry admission uses it to prevent two callers from retrying an older terminal attempt after a newer attempt already exists.

func ListOrphanedSessionRuns added in v1.1.77 

func ListOrphanedSessionRuns(sessionDir string) ([]SessionRun, error)

ListOrphanedSessionRuns returns all runs that are in a non-terminal state. This is used during server startup to recover runs that were active when the previous server instance stopped.

func ListOrphanedSessionRunsContext added in v1.2.96 

func ListOrphanedSessionRunsContext(ctx context.Context, sessionDir string) ([]SessionRun, error)

func ListSessionRuns added in v1.1.77 

func ListSessionRuns(sessionDir, sessionID string, limit int) ([]SessionRun, error)

type SessionRunEvent added in v1.1.61 

type SessionRunEvent struct {
	ID        string
	SessionID string
	RunID     string
	EventType string
	Source    string
	Status    string
	Model     string
	Mode      string
	Timestamp time.Time
	Data      json.RawMessage
}

SessionRunEvent records one lifecycle event for a single chat/run execution.

func ListSessionRunEvents added in v1.1.61 

func ListSessionRunEvents(sessionDir, sessionID string) ([]SessionRunEvent, error)

ListSessionRunEvents returns run events for a session, ordered by insertion.

func ListSessionRunEventsContext added in v1.2.96 

func ListSessionRunEventsContext(ctx context.Context, sessionDir, sessionID string) ([]SessionRunEvent, error)

ListSessionRunEventsContext is the cancellable event replay query used by bounded recovery and reconnect paths.

type SessionRunRecovery added in v1.2.96 

type SessionRunRecovery struct {
	RunID              string
	SessionID          string
	State              SessionRunRecoveryState
	TriggerSource      string
	ReasonCode         string
	Attempt            int
	PreviousLeaseEpoch int64
	LastError          string
	NextRetryAt        *time.Time
	StartedAt          time.Time
	UpdatedAt          time.Time
	CompletedAt        *time.Time
}

SessionRunRecovery is the durable diagnostic and retry state for orphan reconciliation. It never grants ownership; the recovery lease remains the sole authority for changing a Run.

func BeginSessionRunRecovery added in v1.2.96 

func BeginSessionRunRecovery(sessionDir, sessionID, runID, triggerSource, reasonCode string, previousLeaseEpoch int64) (*SessionRunRecovery, error)

BeginSessionRunRecovery records an attempt while verifying the exact purpose=recovery lease and target Run in the same transaction.

func BeginSessionRunRecoveryContext added in v1.2.96 

func BeginSessionRunRecoveryContext(ctx context.Context, sessionDir, sessionID, runID, triggerSource, reasonCode string, previousLeaseEpoch int64) (*SessionRunRecovery, error)

BeginSessionRunRecoveryContext is the cancellable form used by the bounded Runtime recovery coordinator.

func GetSessionRunRecovery added in v1.2.96 

func GetSessionRunRecovery(sessionDir, runID string) (*SessionRunRecovery, error)

GetSessionRunRecovery returns the last durable recovery disposition for a Run. A missing row is represented by (nil, nil).

type SessionRunRecoveryState added in v1.2.96 

type SessionRunRecoveryState string
const (
	SessionRunRecoveryRunning  SessionRunRecoveryState = "recovering"
	SessionRunRecoveryFailed   SessionRunRecoveryState = "failed"
	SessionRunRecoveryComplete SessionRunRecoveryState = "completed"
	SessionRunRecoveryDetached SessionRunRecoveryState = "detached_remote"
)

type Store 

type Store interface {
	// Init initializes the session store, creating the underlying
	// database or storage if needed.
	Init() error

	// InitWithID initializes the session with a specific ID.
	// An empty id generates a new one.
	InitWithID(id string) error

	// AppendMessage persists a conversation message and returns its entry ID.
	AppendMessage(msg provider.Message) (string, error)

	// AppendCompaction records a context compaction event.
	AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

	// AppendModelChange records a model switch.
	AppendModelChange(providerName, modelID string) (string, error)

	// AppendModeChange records a session execution mode change.
	AppendModeChange(mode string) (string, error)

	// AppendThinkingLevelChange records a thinking level change.
	AppendThinkingLevelChange(level string) (string, error)
	AppendAdditionalDirectories(directories []string) (string, error)

	// AppendSessionInfo records session metadata.
	AppendSessionInfo(name string) (string, error)

	// GetMessages returns all messages in the current branch,
	// with compaction summaries applied.
	GetMessages() []provider.Message

	// GetReplayState returns the full replay state including
	// messages and their entry IDs.
	GetReplayState() ReplayState

	// GetLeafID returns the current leaf entry ID, or nil if empty.
	GetLeafID() *string

	// GetLatestCompaction returns the most recent compaction entry,
	// or (zero, false) if none exists.
	GetLatestCompaction() (CompactionEntry, bool)

	// GetLatestModelChange returns the most recent persisted model binding.
	GetLatestModelChange() (ModelChangeEntry, bool)

	// GetLatestModeChange returns the most recent persisted session mode.
	GetLatestModeChange() (ModeChangeEntry, bool)

	// GetLatestThinkingLevelChange returns the most recent persisted thinking level.
	GetLatestThinkingLevelChange() (ThinkingLevelChangeEntry, bool)
	GetLatestAdditionalDirectories() (AdditionalDirectoriesEntry, bool)

	// GetFile returns the session file path (handle file for SQLite).
	GetFile() string

	// GetHeader returns the session header with metadata.
	GetHeader() *Header
}

Store is the interface for session persistence backends. Manager implements this interface using SQLite. Alternative backends (in-memory for testing, cloud storage, etc.) can implement Store to swap the persistence layer without changing agent or UI code.

type ThinkingLevelChangeEntry 

type ThinkingLevelChangeEntry struct {
	EntryBase
	ThinkingLevel string `json:"thinkingLevel"`
}

ThinkingLevelChangeEntry records a thinking level change.

type ToolExecutionRecord added in v1.1.77 

type ToolExecutionRecord struct {
	ID               int64
	SessionID        string
	LocalTurnID      string
	ExecutionKey     string
	Provider         string
	API              string
	ResponseID       string
	ProviderCallID   string
	ToolKind         string
	ToolName         string
	ArgsHash         string
	ExecutionState   string
	ResultSummary    json.RawMessage
	ProviderMetadata json.RawMessage
	SideEffecting    bool
	CreatedAt        time.Time
	CompletedAt      *time.Time
}

ToolExecutionRecord is the cross-protocol idempotency record for a tool invocation. ExecutionKey is local and remains the deduplication authority.

func ClaimToolExecutionRecord added in v1.1.77 

func ClaimToolExecutionRecord(sessionDir string, record ToolExecutionRecord) (*ToolExecutionRecord, bool, error)

ClaimToolExecutionRecord atomically claims an execution key. A false created result means another request already owns the key and its record must be consulted before executing a side effect.

func RequestToolExecutionRecoveryRecords added in v1.2.99 

func RequestToolExecutionRecoveryRecords(sessionDir, sessionID, localTurnID string, providerCallIDs []string) ([]ToolExecutionRecord, int64, error)

RequestToolExecutionRecoveryRecords records explicit user confirmation and returns only matching interrupted calls. The records are retained as audit evidence while recovery starts as a fresh execution; terminal Runs are never reactivated to consume these records.

type TurnEndEntry added in v1.2.92 

type TurnEndEntry struct {
	EntryBase
	TurnID     string `json:"turnId"`
	IntentID   string `json:"intentId,omitempty"`
	RunID      string `json:"runId,omitempty"`
	Status     string `json:"status"`
	StopReason string `json:"stopReason,omitempty"`
}

TurnEndEntry marks the durable terminal boundary of a logical conversation turn. It is persisted for fork resolution and recovery, not model replay.

type TurnStartEntry added in v1.2.92 

type TurnStartEntry struct {
	EntryBase
	TurnID   string `json:"turnId"`
	IntentID string `json:"intentId,omitempty"`
	RunID    string `json:"runId,omitempty"`
	Attempt  int    `json:"attempt,omitempty"`
}

TurnStartEntry marks the durable beginning of a logical conversation turn. It is persisted for boundary recovery but is excluded from provider replay.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.