Sessions API

Interfaces

interface AgentSession {
  read(path: string): Promise<Uint8Array>
  write(path: string, bytes: Uint8Array): Promise<void>
  delete(path: string): Promise<void>
  commit(message: string): Promise<string>
  writeAndCommit(opts: { files: Record<string, Uint8Array>; message: string }): Promise<string>
  list(path?: string): Promise<ListEntry[]>
  diff(): Promise<string>
  log(): Promise<CommitEntry[]>
}

interface UserSession extends AgentSession {
  promote(opts: PromoteOpts): Promise<PromoteResult>
  discard(): Promise<void>
  extend(ttlMs: number): Promise<void>
  forAgent(): AgentSession
}

AgentSession has no promote() method by design.

const agent = session.forAgent()

Promotion is type-level enforced. forAgent() returns a narrowed handle with no promote() method.

Promotion types

type PromoteSelector =
  | { mode: 'all' }
  | { mode: 'files'; files: string[] }

type PromoteStrategy = 'auto' | 'commit' | 'branch' | 'pr' | 'patch'

interface PromoteOpts {
  selector: PromoteSelector
  strategy?: PromoteStrategy
  message?: string
}

interface PromoteResult {
  sha: string
  branch: string
  prUrl?: string
}

Current core promotes selected files through the durable adapter’s applyCommit() method. Hunk-level selectors are not implemented.

The strategy type includes auto, commit, branch, pr, and patch, but current core does not implement separate branch, PR, or patch behavior from session.promote().

Current behavior notes

• session.log() currently returns [].
• session.commit() currently returns a synthetic ephemeral-${Date.now()} ID.
• Git-backed ephemeral workspaces can still be used as normal local git directories by external tools.