@agentproto/runtime 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -495,6 +495,23 @@ interface SessionDescriptor {
      *  the daemon's. Lets the UI show "crashed with the daemon" instead of a
      *  bare "killed" that reads as deliberate. */
     endedReason?: "daemon-restart";
+    /** Whether a turn was actually in flight the INSTANT `status` flipped to
+     *  "killed" — captured before anything else runs, because `busy` itself
+     *  cannot be trusted after the fact: `runAgentTurn`'s `finally` is what
+     *  clears `busy`, and that `finally` never fires for a generator that's
+     *  never resumed (a killed child mid-tool-call, or a dead daemon), so a
+     *  post-hoc read of `busy` on a killed session may just be showing you
+     *  whatever it froze at. This field exists because `status: "killed"`
+     *  alone can't tell a human's Stop mid-turn apart from a supervisor
+     *  reaping a child that had already finished — both leave `exitCode:
+     *  null`, and `turnsCompleted` alone is too weak (a session killed
+     *  mid-SECOND-turn also has `turnsCompleted: 1`). `killedMidTurn: true`
+     *  paired with any `turnsCompleted` means interrupted; `false`/absent
+     *  alongside `turnsCompleted > 0` means the work was done before the
+     *  kill — see activityFor in the vscode package for the read. Set by
+     *  `kill()`, `shutdownImpl`'s force-kill, and `loadHistorySnapshot`'s
+     *  wasAlive reclassification; absent for every other terminal path. */
+    killedMidTurn?: boolean;
     /** Last time anything was written to stdout/stderr. Lets the UI
      *  spot stuck sessions ("running for 2h, last output 12min ago"). */
     lastOutputAt?: string;
@@ -514,6 +531,10 @@ interface SessionDescriptor {
     /** Free-text label the spawner can attach (e.g. conversation id,
      *  operator name) so the UI can group/filter. */
     label?: string;
+    /** Derived from the session's FIRST prompt — what this conversation is
+     *  about, for a UI that would otherwise show the adapter's argv. Distinct
+     *  from `label`, which the spawner supplies and which always wins. */
+    title?: string;
     /** True when the session was spawned under a real PTY (node-pty)
      *  instead of `child_process.spawn`. PTY sessions carry raw ANSI
      *  bytes (alt-screen, key bindings, colors); attach goes through
@@ -529,6 +550,25 @@ interface SessionDescriptor {
     argv?: readonly string[];
     /** Working directory the session was spawned in. Cloned by restart. */
     cwd?: string;
+    /** Root of the git worktree the session was spawned in — the session→
+     *  worktree edge, resolved from `cwd` at spawn time
+     *  (`resolveWorktreeIdentity`). Distinct from `cwd`, which may be a
+     *  subdirectory of it. Absent when `cwd` isn't inside a linked worktree (a
+     *  plain checkout, a non-repo dir) and for every session persisted before
+     *  this field existed.
+     *
+     *  Recorded rather than computed at read time because it can't be
+     *  recovered later: a worktree removed after the session ran leaves nothing
+     *  on disk to re-resolve. */
+    worktreePath?: string;
+    /** Generation id of that worktree, read at spawn from the provision marker
+     *  (`agentproto-worktree.json` in the worktree's private gitdir, written by
+     *  `worktree.provision`). Absent whenever `worktreePath` is, and also for a
+     *  worktree created by a bare `git worktree add` — nothing writes a marker
+     *  there. The marker is what distinguishes generations, so a
+     *  `worktreePath` without an id identifies a PATH, which a later worktree
+     *  may reuse; the pair identifies one specific worktree. */
+    worktreeId?: string;
     /** Adapter slug for agent-cli sessions — restart uses this with
      *  `/sessions/agent` to spin up a fresh ACP runtime. Undefined for
      *  pty/command kinds. */
@@ -818,6 +858,22 @@ interface SessionsRegistry {
     enqueuePrompt(id: string, message: unknown, opts?: {
         interrupt?: boolean;
     }): Promise<void>;
+    /** Cancel the in-flight turn on a live agent-cli session and leave the
+     *  session itself alive and idle — the bare "interrupt, no next prompt"
+     *  primitive `sendPrompt`/`enqueuePrompt`'s `opts.interrupt` arm lacks
+     *  on its own, since that arm always exists to redirect onto a NEW
+     *  prompt. Reuses the same `interruptInFlightTurn` helper those two
+     *  share.
+     *
+     *  Idempotent by design: idle, unknown-alive (starting/running only —
+     *  same liveness `validateAgentTurn` checks), or already-terminal
+     *  (exited/killed/error) all resolve `{ wasBusy: false }` rather than
+     *  throwing — a no-op interrupt is not an error. Throws only when the
+     *  id is unknown, or when `cancel()` itself rejects ("does not support
+     *  interrupt", propagated from `interruptInFlightTurn`). */
+    interruptSession(id: string): Promise<{
+        wasBusy: boolean;
+    }>;
     /** Stamp `lastActivityAt` on a live agent-cli session's descriptor
      *  and schedule a debounced persist. Called from the `onActivity`
      *  callback threaded down through the driver → ACP client, which
@@ -1789,6 +1845,19 @@ interface PolicyRunState {
     nextPolicyId?: string;
     error?: string;
 }
+/**
+ * Does `policy` watch `sessionId`? True when the id is the representative
+ * `sessionId` or appears anywhere in the fan-in `sessionIds` group — the two
+ * ways `AttachPolicyInput` can name a session.
+ *
+ * This is the reverse of the policy→session link, and it is deliberately
+ * computed on demand over `list()` rather than persisted: a session→policy
+ * index in policies.json (or a `policies` field on the session record) would
+ * be a second source of truth to keep in sync across attach, fan-in nudges,
+ * `next` chaining, and snapshot reload. A filtered pass is O(policies) on a
+ * set the daemon already holds in memory.
+ */
+declare function policyWatchesSession(policy: PolicyRunState, sessionId: string): boolean;
 interface CompletionPolicySupervisor {
     /**
      * Attach a completion policy to an already-running session.
@@ -2566,6 +2635,158 @@ declare function declaredPresetToProviderPreset(decl: DeclaredAdapterPreset): Pr
  */
 declare function listPresets(env?: Record<string, string | undefined>, adapterPresets?: readonly DeclaredAdapterPreset[]): AdapterEntry<PresetInfo>[];
 
+/**
+ * Per-workspace state buckets — AIP-46 §State partitioning.
+ *
+ * AIP-46's premise is "a single host serve many bound directories", and
+ * §Workspaces delivered the addressing half of it: a slug resolves to a
+ * path. The state those directories generate stayed pooled in one global
+ * `~/.agentproto/sessions.json` with `workspaceSlug` demoted to a column
+ * on each row — a label, not a boundary.
+ *
+ * What that costs is measurable rather than theoretical. `HISTORY_CAP`
+ * bounds retention across the *union* of every workspace, so the cap is
+ * spent by whoever was busiest. A store pooling a few hundred rows from
+ * several workspaces sits at that ceiling in ordinary use, and the
+ * workspace contributing a handful of them is one busy afternoon in a
+ * NEIGHBOUR away from losing all of them — having done nothing itself.
+ * The eviction is silent and lands on the quietest workspace.
+ *
+ * This module is the slug→bucket rule and nothing more:
+ *
+ *   ~/.agentproto/
+ *   ├── workspaces.json          # the registry (workspaces-config.ts)
+ *   └── workspaces/              # one bucket per workspace (here)
+ *       ├── agentik-studio/sessions.json
+ *       └── default/sessions.json
+ *
+ * The registry (a file) and the state (a directory) are deliberate
+ * siblings: one names the workspaces, the other holds what each
+ * accumulated.
+ *
+ * ## Membership is the validation
+ *
+ * `workspaceSlug` arrives on a spawn request — it is caller input
+ * (`session-spawn.ts` passes `input.workspaceSlug` straight through when
+ * an explicit `cwd` accompanies it, so nothing sanitises it on the way
+ * to the descriptor). A bucket is a directory name. Joining the two
+ * without a check hands the caller `../../` under the daemon's own state
+ * root, as the daemon's UID.
+ *
+ * So a slug does not become a directory name by being cleaned up — it
+ * becomes one by coming *back from* the registry lookup. The registry's
+ * slugs were sanitised by `sanitizeSlug` on the way in, so the only
+ * strings that ever reach the filesystem are ones the host itself
+ * minted. An unregistered slug isn't rejected or escaped; it fails to
+ * match and lands in `default` like any other unregistered work. This is
+ * why the rule is membership rather than sanitisation: you cannot forget
+ * to validate a value you never chose.
+ *
+ * ## What this does NOT buy
+ *
+ * Partitioning bounds what a workspace's state *costs* other workspaces.
+ * It does not bound who may read it — every bucket is still served to
+ * every authorised caller, because no workspace-scoped credential
+ * exists to serve them differently (pairings carry no workspace concept
+ * at all; the orchestrator scope-token's `session_list` is daemon-wide
+ * by documented debt, `orchestrator-gateway.ts`). The files moved; the
+ * access did not. AIP-46 §Security Considerations says this in the
+ * negative — do not read this module as an isolation control.
+ */
+/** The bucket every record lands in when its slug doesn't resolve —
+ *  absent, empty, or naming a workspace that isn't registered.
+ *
+ *  A real bucket, not an error state. Refusing to persist an
+ *  unregistered session would make this a breaking change for every
+ *  one-off `cwd` spawn, and the obvious workaround (auto-register)
+ *  turns a registry of the user's intent into a registry of everything
+ *  that ever ran. The cost is stated plainly in the AIP: `default`'s
+ *  occupants get no separation from *each other* — registering a
+ *  workspace is what buys that. */
+declare const DEFAULT_BUCKET = "default";
+/** Root of the per-workspace state buckets. Sibling of the
+ *  `workspaces.json` registry that names them. */
+declare const BUCKETS_ROOT: () => string;
+/** The pre-partition global snapshot. Still read (to migrate from) and
+ *  never written after the split — see `migrateLegacySessionsFile`. */
+declare const LEGACY_SESSIONS_FILE: () => string;
+/** Marker recording that the legacy split already ran. Its presence —
+ *  not the legacy file's absence — is what makes migration
+ *  once-and-only-once, so a user who deletes rows from a bucket doesn't
+ *  get them resurrected on the next boot. */
+declare const migrationMarkerPath: (root: string) => string;
+declare const bucketDir: (root: string, slug: string) => string;
+declare const bucketSessionsFile: (root: string, slug: string) => string;
+/** Per-bucket transcript directory (AIP-46 §Layout).
+ *
+ *  Not yet wired: the registry still writes transcripts to the shared
+ *  `~/.agentproto/sessions/`. Moving them needs the read side to move
+ *  too, and several readers currently ignore the configured base dir
+ *  entirely (`http-server.ts` and `transcript-export.ts` call
+ *  `sessionEventsPath(id)` with no `baseDir`, so they resolve off
+ *  `homedir()` regardless) — a pre-existing bug that a partial move
+ *  would turn into missing transcripts. Exported so the follow-up has
+ *  the path rule in one place. The AIP makes transcripts a SHOULD, not
+ *  a MUST, for exactly this reason. */
+declare const bucketTranscriptDir: (root: string, slug: string) => string;
+declare const isSafeBucketSlug: (slug: string) => boolean;
+/**
+ * The slug→bucket rule (AIP-46 §Bucket resolution).
+ *
+ * 1. non-empty AND registered → that workspace's bucket
+ * 2. otherwise → `default`
+ *
+ * `registered` must come from the workspaces registry. Passing a set
+ * built from caller input defeats the entire point of this function.
+ */
+declare function resolveBucketSlug(workspaceSlug: string | undefined | null, registered: ReadonlySet<string>): string;
+/** Registered slugs, read fresh. Cheap (the registry is <1KB) and read
+ *  per persist rather than cached at boot, so a workspace registered
+ *  while the daemon is up starts bucketing immediately instead of
+ *  silently pooling into `default` until restart. Never throws: a
+ *  missing/corrupt registry degrades to "nothing is registered", i.e.
+ *  everything lands in `default` — today's pooled behaviour, which is
+ *  the right failure direction. */
+declare function readRegisteredSlugs(configPath?: string): ReadonlySet<string>;
+/** Bucket directories that exist on disk. Order is not meaningful. */
+declare function listBuckets(root: string): string[];
+interface MigrationMarker {
+    version: 1;
+    migratedAt: string;
+    /** Absolute path of the legacy artifact this split read from. Left
+     *  untouched on disk — recorded so the provenance survives. */
+    from: string;
+    /** Total records read out of the legacy artifact. */
+    rows: number;
+    /** Records landed, per bucket. Sums to `rows` — the migration never
+     *  drops a record it cannot place; it sends it to `default`. */
+    byBucket: Record<string, number>;
+}
+/**
+ * Split the legacy global snapshot into buckets (AIP-46 §Migration).
+ *
+ * **Additive by mandate.** The legacy file is opened read-only and left
+ * exactly where it is — never deleted, truncated, or rewritten. It is
+ * the user's data and their only rollback; the buckets are a derivative
+ * until they decide otherwise. Reclaiming it is a separate, human-gated
+ * call, and this module deliberately ships no GC: a real store is backed
+ * by a transcript directory that can reach hundreds of megabytes and may
+ * be someone's only copy of months of work — a deleter that guesses
+ * wrong there is unrecoverable.
+ *
+ * Idempotent via the marker, not via the legacy file's absence — the
+ * file stays, so absence would never fire and every boot would re-import
+ * rows the user had since deleted from a bucket.
+ *
+ * Returns the marker it wrote, or `null` when there was nothing to do
+ * (already migrated, or no legacy file).
+ */
+declare function migrateLegacySessionsFile(opts: {
+    root: string;
+    legacyFile: string;
+    registered: ReadonlySet<string>;
+}): MigrationMarker | null;
+
 /** A journal-file StepCache scoped to one cacheKey. Best-effort: read/parse
  *  failures degrade to "no cache" (a miss), never throw into the run. */
 declare function createFileStepCache(cacheKey: string, opts?: {
@@ -2844,6 +3065,30 @@ interface CreateGatewayOptions {
      *  tool family, and the `/sessions/:id/pty` WebSocket. Without it,
      *  those routes return 501 / the MCP tools aren't registered. */
     spawnPty?: PtyFactory;
+    /** Enable filesystem persistence for every store this gateway owns —
+     *  the sessions registry plus the supervisor / routine / cron / workflow
+     *  / inbound-watcher run stores. Defaults to `true`, i.e. production is
+     *  unchanged.
+     *
+     *  Tests pass `false`. Without it, a test gateway writes its fake rows
+     *  into the *developer's real* `~/.agentproto/sessions.json` (and the
+     *  sibling `policies.json` / `routine-runs.json` / `cron-jobs.json` /
+     *  `workflow-runs.json`): those paths resolve off `homedir()`, and the
+     *  gateway opted each store into persistence unconditionally. Since
+     *  `loadHistorySnapshot` re-reads sessions.json at boot, the real daemon
+     *  then restores the fakes and shows them in the dashboard — and against
+     *  `HISTORY_CAP` (200) they evict genuine history.
+     *
+     *  The sibling stores already default to persist-off when constructed
+     *  directly (see `createRoutineRunner`); this knob is what lets a
+     *  gateway stop overriding that on their behalf. */
+    persist?: boolean;
+    /** Override the sessions-registry persistence path — tests pin a tmpdir
+     *  so an assertion can look at the file the gateway would have written
+     *  instead of the developer's real one. Defaults to
+     *  `~/.agentproto/sessions.json`. The structured-transcript dir follows
+     *  this path's parent, so pinning it isolates transcripts too. */
+    persistPath?: string;
     /** Override the per-boot bearer token. Default: `randomUUID()`.
      *  Tests can pin a known value; production should always let
      *  the gateway generate fresh. The token is written into
@@ -2938,4 +3183,4 @@ interface GatewayHandle {
  */
 declare function createGateway(opts: CreateGatewayOptions): Promise<GatewayHandle>;
 
-export { AdapterAuthDescriptor, type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type AttachPolicyInput, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, type CommitSpec, type CompletionPolicySupervisor, type CreateGatewayOptions, type CreateOfferInput, type CreatedOffer, DEFAULT_ORCHESTRATOR_TOOLS, DeclaredAdapterOption, type DeclaredAdapterPreset, type GateSpec, type GatewayHandle, type InboundWatcher, type JudgeGateSpec, type McpCredentialDeps, type OnFailSpec, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, PAIRINGS_VERSION, type PairingChannelContext, type PairingChannelHandle, type PairingChannelMode, type PairingRecord, type PairingRegistry, type PairingRegistryDeps, type PendingPermission, type PermissionRespondInput, type PermissionRespondResult, type PolicyRunState, type PolicyRunStatus, type PresetInfo, type PricingResolver, type RegisterBrowserInput, type RegisterPairingToolsOptions, type RegisterSessionInput, ResolvedAuthSpec, type RuntimeMeta, type SandboxAdapterInfo, type SandboxProviderCapabilities, type SandboxProviderHandle, type SandboxProviderLister, type SandboxProviderResolver, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionObserver, type SessionStatus, type SessionUsage, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, type SpawnSessionInput, type TokenPricing, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type UsageComputeInput, type UsageSource, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createScopeTokenRegistry, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, formatToolCall, formatToolResult, getMcpCredentialDeps, listPresets, makeBrowserAdapterLister, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, projectSessionUsage, readDaemonRegistry, readRuntimeMeta, registerPairingTools, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
+export { AdapterAuthDescriptor, type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type AttachPolicyInput, BUCKETS_ROOT, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, type CommitSpec, type CompletionPolicySupervisor, type CreateGatewayOptions, type CreateOfferInput, type CreatedOffer, DEFAULT_BUCKET, DEFAULT_ORCHESTRATOR_TOOLS, DeclaredAdapterOption, type DeclaredAdapterPreset, type GateSpec, type GatewayHandle, type InboundWatcher, type JudgeGateSpec, LEGACY_SESSIONS_FILE, type McpCredentialDeps, type MigrationMarker, type OnFailSpec, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, PAIRINGS_VERSION, type PairingChannelContext, type PairingChannelHandle, type PairingChannelMode, type PairingRecord, type PairingRegistry, type PairingRegistryDeps, type PendingPermission, type PermissionRespondInput, type PermissionRespondResult, type PolicyRunState, type PolicyRunStatus, type PresetInfo, type PricingResolver, type RegisterBrowserInput, type RegisterPairingToolsOptions, type RegisterSessionInput, ResolvedAuthSpec, type RuntimeMeta, type SandboxAdapterInfo, type SandboxProviderCapabilities, type SandboxProviderHandle, type SandboxProviderLister, type SandboxProviderResolver, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionObserver, type SessionStatus, type SessionUsage, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, type SpawnSessionInput, type TokenPricing, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type UsageComputeInput, type UsageSource, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, bucketDir, bucketSessionsFile, bucketTranscriptDir, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createScopeTokenRegistry, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, formatToolCall, formatToolResult, getMcpCredentialDeps, isSafeBucketSlug, listBuckets, listPresets, makeBrowserAdapterLister, migrateLegacySessionsFile, migrationMarkerPath, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, policyWatchesSession, projectSessionUsage, readDaemonRegistry, readRegisteredSlugs, readRuntimeMeta, registerPairingTools, resolveBucketSlug, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };