@prismshadow/penguin-server 0.2.16 → 0.2.18

package/dist/plugin/index.d.ts

@@ -1,10 +1,10 @@
-import { SpawnConfiner, OmniMessage, ThinkingLevelName, ToolCallPayload, ApprovalDecision, ProjectConfig, ModelRef, PluginTables, ListEndpointModelsOptions, ModelRequestContext, ProxyEnvPolicy, ControlEnvContext, AgentAssembly, ApproveFn, StopReason, CompactAvailability, SessionTitleResult, BackgroundCommandInfo, ToolDetachResult, BackgroundSubagentInfo, SubagentMessageOptions, SubagentMessageOutcome } from '@prismshadow/penguin-core';
+import { SpawnConfiner, AmspRecord, ThinkingLevelName, ToolCallPayload, ApprovalDecision, ProjectConfig, ModelRef, PluginTables, ListEndpointModelsOptions, ModelRequestContext, ProxyEnvPolicy, ControlEnvContext, AgentAssembly, ApproveFn, StopReason, CompactAvailability, SessionTitleResult, BackgroundCommandInfo, ToolDetachResult, BackgroundSubagentInfo, SubagentMessageOptions, SubagentMessageOutcome } from '@prismshadow/penguin-core';
 import { SandboxProviderSource, SandboxSettings, SandboxDimension, SandboxLimit } from '@prismshadow/penguin-core/plugin';
-import { Slot, Opaque } from '@prismshadow/penguin-core/kernel';
-import { ApprovalMode, ModelRefDto, ChatDefaultsDto, CommandPolicyDto, ModelVisionDetectRequest, ModelVisionDetectResponse, ModelTestRequest, ModelTestResponse, ModelProtocolDetectRequest, ModelProtocolDetectResponse, EndpointModelListRequest, EndpointModelListResponse, ModelsResponse, ModelsUpdateRequest, ProviderConnectionUpdate, PresetSyncMode, PresetSyncResponse, ServerEvent, MessagingChannel, UnavailableSandboxBackend, SessionSandboxPreset, SessionSandbox, SessionInfo, SessionCategory, SessionCategoryCounts, ModelScopeAuthFlowStatusResponse, SessionStatus, PendingSteeringInfo, SessionBackgroundTasks, PendingFollowUpInfo, AgentConfigDto, AgentConfigUpdateRequest, AgentKernelUpdateResponse, VaultResponse, VaultUpdateRequest, PluginUpdateRef, MessagingRuntimeStatus, PluginConfiguration, ContributionsResponse, RendererRef } from '../api/types.js';
+import { Slot, Opaque, ClassCtx } from '@prismshadow/penguin-core/kernel';
+import { ApprovalMode, ModelRefDto, ChatDefaultsDto, CommandPolicyDto, ModelVisionDetectRequest, ModelVisionDetectResponse, ModelTestRequest, ModelTestResponse, ModelProtocolDetectRequest, ModelProtocolDetectResponse, EndpointModelListRequest, EndpointModelListResponse, ModelsResponse, ModelsUpdateRequest, ProviderConnectionUpdate, PresetSyncMode, PresetSyncResponse, ServerEvent, MessagingChannel, UnavailableSandboxBackend, SessionSandboxPreset, SessionSandbox, SessionInfo, SessionCategory, SessionCategoryCounts, ModelScopeAuthFlowStatusResponse, SessionStatus, PendingSteeringInfo, SessionBackgroundTasks, PendingFollowUpInfo, AgentConfigDto, AgentConfigUpdateRequest, AgentKernelUpdateResponse, VaultResponse, VaultUpdateRequest, AgentDeletionInfo, PluginUpdateRef, MessagingRuntimeStatus, PluginConfiguration, ContributionsResponse, RendererRef } from '../api/types.js';
 export { PluginConfigField } from '../api/types.js';
 import { ThinkingLevelName as ThinkingLevelName$1 } from '@prismshadow/penguin-core/interfaces';
-import { SessionSource } from '@prismshadow/penguin-core/omnimessage';
+import { SessionSource } from '@prismshadow/amsp';
 import { Hono } from 'hono';
 import '@prismshadow/penguin-hmr';
 
@@ -23,12 +23,13 @@ interface UserRow {
 
 /**
  * "desktop" and "setup" may set a password without the old one (theirs is random and was never
- * shown); desktop-only routes open to "desktop" alone. "token" is the local API token's
- * authority, whether presented as a Bearer header or exchanged for a Remote cookie.
- * Exchanging the credential must not grant the person's privileges. Anything else reads as
- * "password".
+ * shown); desktop-only routes open to "desktop" alone. "remote" is the one-hour browser session
+ * Penguin Remote exchanges the local API token for: it counts as the person wherever a check
+ * tells a person from the token (human-only writes, identity claims, who drives a run), opens
+ * no desktop-only route, and changes the password only with the old one. "token" is the local
+ * API token presented as a Bearer header, and nothing else. Anything else reads as "password".
  */
-type SessionVia = "password" | "desktop" | "setup" | "token";
+type SessionVia = "password" | "desktop" | "setup" | "remote" | "token";
 
 declare class SandboxService {
     private mounted;
@@ -197,6 +198,12 @@ interface CreateTerminalSessionOptions {
     cwd: string;
     /** Owning user id — a shell is the most privileged thing this server hands out. */
     ownerUserId: string;
+    /**
+     * The conversation (PenguinHarness Session) this shell was opened for — not this object's own
+     * id. A label the Web App files the shell under, so each conversation lists only its own; null
+     * for a shell no conversation asked for (the API, the CLI, the standalone /terminal page).
+     */
+    sessionId?: string | null;
     /**
      * Stable per-user display number (tmux-style), assigned by the manager at creation. It
      * travels with the terminal for its whole life — UI numbering must never depend on list
@@ -256,6 +263,8 @@ interface TerminalSessionInfo {
     name: string;
     cwd: string;
     ownerUserId: string;
+    /** The conversation the shell belongs to, or null (see CreateTerminalSessionOptions.sessionId). */
+    sessionId: string | null;
     title: string | null;
     cols: number;
     rows: number;
@@ -274,6 +283,8 @@ declare class TerminalSession {
     readonly ownerUserId: string;
     readonly createdAt: Date;
     private name;
+    /** The conversation this shell belongs to; changes only when that conversation's id does. */
+    private owningSession;
     private readonly terminal;
     private readonly ptyProcess;
     private readonly inputMode;
@@ -293,6 +304,8 @@ declare class TerminalSession {
     get exit(): TerminalExitInfo | null;
     info(): TerminalSessionInfo;
     rename(name: string): void;
+    /** Files the shell under another conversation — the same one, once its id has self-healed. */
+    setSession(sessionId: string | null): void;
     write(data: string): void;
     /**
      * Applies a size request under the claim/update ownership rule, resizing both the pty and
@@ -324,6 +337,8 @@ declare class TerminalSession {
 interface CreateTerminalRequest {
     cwd: string;
     ownerUserId: string;
+    /** The conversation the shell is opened for; absent or null for none. */
+    sessionId?: string | null;
     name?: string;
     cols?: number;
     rows?: number;
@@ -372,8 +387,8 @@ interface RecallableFile {
 
 /** The open streaming fragments of running sessions, as their holder uses them — what {@link LiveTailTracker} implements. */
 interface LiveTail {
-    observe(sessionId: string, msg: OmniMessage): void;
-    fragments(sessionId: string): OmniMessage[];
+    observe(sessionId: string, msg: AmspRecord): void;
+    fragments(sessionId: string): AmspRecord[];
     clear(sessionId: string): void;
 }
 
@@ -527,14 +542,14 @@ interface SessionRow {
  */
 
 interface PendingApproval {
-    toolCall: OmniMessage<ToolCallPayload>;
+    toolCall: AmspRecord<ToolCallPayload>;
     origin?: string[];
 }
 /** A Session runtime's pending approvals, as its holder uses them — what {@link ApprovalRegistry} implements. */
 interface Approvals {
     readonly size: number;
     list(): PendingApproval[];
-    wait(toolCall: OmniMessage<ToolCallPayload>): Promise<ApprovalDecision>;
+    wait(toolCall: AmspRecord<ToolCallPayload>): Promise<ApprovalDecision>;
     decide(toolCallId: string, decision: ApprovalDecision): boolean;
     denyAll(): void;
     denyMain(): void;
@@ -543,7 +558,7 @@ interface Approvals {
 /** A numbered channel event; `id` is `<epoch>-<seq>`, `data` is serialized single-line JSON. */
 interface ChannelEvent {
     id: string;
-    /** SSE event name; omitted (OmniMessage) means no `event:` line. */
+    /** SSE event name; omitted (a record) means no `event:` line. */
     event?: string;
     data: string;
 }
@@ -768,6 +783,13 @@ interface TitleNotifier {
  * written before the source was required, which records none.
  */
 type RecordedSource = SessionSource | null;
+/**
+ * Who is reading a list, as far as the listing rule cares: a server that adopted this one as a
+ * machine at `adoptedAt` (read from {@link ADOPTED_AT_HEADER}), or anyone else (`{}`).
+ */
+interface ListingView {
+    adoptedAt?: string;
+}
 
 /** One indexed Trace shard. */
 interface TraceFileRow {
@@ -834,7 +856,7 @@ declare abstract class TraceIndex {
         fileIndex: number;
         date: string;
         sizeBytes: number;
-        records: OmniMessage[];
+        records: AmspRecord[];
     }): void;
     abstract removeSession(projectId: string, agentId: string, sessionId: string): void;
     abstract removeAgent(projectId: string, agentId: string): void;
@@ -868,7 +890,7 @@ interface PlatformModelCatalog {
     models: PlatformCatalogModel[];
 }
 /**
- * Catalog merge result. `updated` counts route migrations; existing metadata is preserved.
+ * Catalog merge result. `updated` counts changes to existing prices, promotions or routes.
  */
 interface PlatformModelApplyResult {
     added: number;
@@ -896,6 +918,8 @@ type UtilityCompletion = {
 /** ProjectConfigStore: the mechanism ProjectConfigService implements. */
 declare abstract class ProjectConfigStore {
     abstract readRaw(projectId: string): Promise<RawTable>;
+    /** Reads every Project's config once, so what the read path's one-time migrations write back (core's and the server's) is on disk before any Session opens one. */
+    abstract migrateStoredConfigs(): Promise<void>;
     abstract loadConfig(projectId: string): Promise<ProjectConfig>;
     abstract writeRaw(projectId: string, data: RawTable): Promise<void>;
     abstract writeInitialConfig(projectId: string, name: string): Promise<void>;
@@ -943,9 +967,8 @@ declare abstract class ProjectConfigStore {
     abstract getModelApiKey(projectId: string, provider: string, modelId: string): Promise<string | undefined>;
     /**
      * The key a group's account balance is read with: the group key (never a row's own), or
-     * else the environment key a Session on one of the group's rows would use on its effective
-     * endpoint, when that variable's official endpoint is the balance endpoint's own host.
-     * Server-side only.
+     * else the vendor's environment key where MMSP's vendor client reads it for the group's base
+     * URL (none, or the vendor's own default endpoint). Server-side only.
      */
     abstract getGroupBalanceKey(projectId: string, provider: string): Promise<string | undefined>;
     abstract setModelApiKeyResolver(resolver: (context: ModelRequestContext) => Promise<string | undefined>): void;
@@ -1103,9 +1126,11 @@ declare class SessionService {
      * Session the user never kept reads archived, and a subagent with a stray mark does not.
      *
      * `orgIds` is the list flow's one-query organization map (see listSessions); without it the
-     * organization is a point lookup, which is what the single-Session paths want.
+     * organization is a point lookup, which is what the single-Session paths want. `view` is who
+     * is reading (sourceSeenBy): a server that adopted this one sees its earlier Sessions as CLI
+     * tasks, in `source` and `archived` alike.
      */
-    toInfo(row: SessionRow, hasTrace: boolean, orgIds?: ReadonlyMap<string, string>): Promise<SessionInfo>;
+    toInfo(row: SessionRow, hasTrace: boolean, orgIds?: ReadonlyMap<string, string>, view?: ListingView): Promise<SessionInfo>;
     /**
      * A Session's source, with session_meta as the single source of truth: the in-process
      * registry answers first (populated at creation / subagent registration / forks / adoption /
@@ -1115,9 +1140,11 @@ declare class SessionService {
      * no source is read with the row's client (readRecordedSource). A Session with no Trace yet
      * is NOT cached — its meta appears with the first run — and reads as its row says
      * (unrunSource): the organization runtime's as `company`, the Agent API's as `api`, any other
-     * as unknown.
+     * as unknown. What the reader sees of it (sourceSeenBy) is applied last and never cached.
      */
     private sourceOf;
+    /** The source as recorded (see sourceOf), whoever reads it. */
+    private recordedSourceOf;
     /** Whether this Session already has a Trace record (a Task has been run): answered by the index (reconciled first). */
     hasTrace(row: SessionRow): Promise<boolean>;
     /**
@@ -1132,7 +1159,7 @@ declare class SessionService {
      * through the trace index once (hasTrace reconciles the Agent), so a subagent Session is
      * known for one even before any list has walked it.
      */
-    listingOf(row: SessionRow): Promise<SessionCategory | null>;
+    listingOf(row: SessionRow, view?: ListingView): Promise<SessionCategory | null>;
     /**
      * List, sorted by createdAt descending — or, with `order: "activity"`, by lastActiveAt
      * descending (ties by sessionId, see {@link compareActivityDesc}). Every row is served
@@ -1189,6 +1216,9 @@ declare class SessionService {
      * stays `user`, and a row the organization caches name before the reconcile pass stamps it
      * reads as `user`. Without the flag every row is served, whichever client created it, but
      * for that rule.
+     *
+     * `view` is who reads the list (sourceSeenBy): every row is classified and served as that
+     * reader sees it.
      */
     listSessions(projectId: string, agentId: string, opts?: {
         paging?: SessionListPaging;
@@ -1197,6 +1227,7 @@ declare class SessionService {
         workspaceGroup?: string;
         withCounts?: boolean;
         excludeOrg?: boolean;
+        view?: ListingView;
     }): Promise<{
         sessions: SessionInfo[];
         counts?: SessionCategoryCounts;
@@ -1210,9 +1241,9 @@ declare class SessionService {
      * and `excludeOrg`, classified the same way — with the source each was classified by and
      * whether it has a Trace. It builds no SessionInfo: the page makes one (toInfo) only for the
      * rows a response carries, so a request costs a classification per archived row, not a full
-     * row view per archived row.
+     * row view per archived row. `view` is who reads it, as for listSessions.
      */
-    archivedRows(projectId: string, agentId: string): Promise<ArchivedRow[]>;
+    archivedRows(projectId: string, agentId: string, view?: ListingView): Promise<ArchivedRow[]>;
     /**
      * The rows a list walk starts from: the Agent's index rows, an organization's left out when
      * `excludeOrg` asks (see listSessions), with the Project's organization map; and when any row
@@ -1382,7 +1413,7 @@ declare class ModelScopeAuthService {
     private sweep;
     private evictOldest;
 }
-declare const ModelScopeAuth_base: (abstract new () => Pick<ModelScopeAuthService, "status" | "start" | "retryApply" | "cancel" | "ensureFresh">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+declare const ModelScopeAuth_base: (abstract new () => Pick<ModelScopeAuthService, "status" | "start" | "cancel" | "retryApply" | "ensureFresh">) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /** The per-App ModelScope key authorization capability consumed by Project model routes. */
 declare abstract class ModelScopeAuth extends ModelScopeAuth_base {
 }
@@ -1395,10 +1426,10 @@ type RunOpts = {
 };
 interface RuntimeSession {
     readonly sessionId: string;
-    run(newMessages: OmniMessage[], opts: RunOpts): AsyncGenerator<OmniMessage>;
+    run(newMessages: AmspRecord[], opts: RunOpts): AsyncGenerator<AmspRecord>;
     compact(opts: {
         signal: AbortSignal;
-    }): AsyncGenerator<OmniMessage>;
+    }): AsyncGenerator<AmspRecord>;
     /**
      * The running context's model (core `Session.provider` / `Session.modelId`, getters over
      * the context's session_meta): the row's pair at creation, moved by each in-session switch
@@ -1419,7 +1450,7 @@ interface RuntimeSession {
         provider: string;
         modelId: string;
         signal: AbortSignal;
-    }): AsyncGenerator<OmniMessage, StopReason>;
+    }): AsyncGenerator<AmspRecord, StopReason>;
     /**
      * The Session's thinking level (core `Session.thinkingLevel`, plain state): soft-limited —
      * an assignment applies from the Session's very next LLM request. Optional: test fakes may
@@ -1429,14 +1460,14 @@ interface RuntimeSession {
     /** Whether compaction is possible and why; when not ok, compact() yields no messages (see core ContextEngine.compactability). */
     compactability(): CompactAvailability;
     /** Queues a mid-run steering input (core `Session.steer`); false when no Task is running. */
-    steer(input: OmniMessage[]): boolean;
+    steer(input: AmspRecord[]): boolean;
     /**
      * Withdraws a steering input queued via `steer` before core delivers it (core
      * `Session.unsteer`, matched by input-list identity); false when it is no longer queued —
      * already delivered, or the run exited. Optional: test fakes may omit it, in which case
      * every recall reports "already delivered".
      */
-    unsteer?(input: OmniMessage[]): boolean;
+    unsteer?(input: AmspRecord[]): boolean;
     /** Skips the in-progress reconnect backoff, firing the next retry immediately (core `Session.skipReconnectWait`); false when no wait is in progress. */
     skipReconnectWait(): boolean;
     /**
@@ -1446,6 +1477,13 @@ interface RuntimeSession {
      * Optional: test fakes may omit it, reading as nothing held.
      */
     hasPendingInput?(): boolean;
+    /**
+     * Whether the next Task opens a new Trace file (core `Session.contextOpenPending`): a
+     * compaction left the next context's file to its first write, so that Task streams the new
+     * `session_meta` behind its `task_begin`, and the input echo waits for it (see InputEcho).
+     * Optional: test fakes may omit it, reading as no.
+     */
+    contextOpenPending?(): boolean;
     /**
      * Runs the named package's `user_prompt` hook (core `Session.runUserPromptHook` — hooks
      * run in core and nowhere else); null = the package is not installed or names no such
@@ -1477,13 +1515,13 @@ interface RuntimeSession {
      */
     onBackgroundNotice?(listener: () => void): void;
     /** Takes the queued background completion notices as task input (core `Session.takeBackgroundNotices`). Optional, like onBackgroundNotice. */
-    takeBackgroundNotices?(): OmniMessage[];
+    takeBackgroundNotices?(): AmspRecord[];
     /** Whether completion notices are still queued (core `Session.hasPendingBackgroundNotices`); pins the entry against idle eviction. Optional, like onBackgroundNotice. */
     hasPendingBackgroundNotices?(): boolean;
     /** Refreshes the listen-port probes behind the process list's `serviceUrl` (core `Session.probeBackgroundCommandServices`). Optional: test fakes may omit it. */
     probeBackgroundCommandServices?(): Promise<void>;
     /** Subscribes live-forwarded background-subagent messages (core `Session.onBackgroundMessage`); the manager publishes them to the session channel. Optional: test fakes may omit it. */
-    onBackgroundMessage?(listener: (msg: OmniMessage) => void): void;
+    onBackgroundMessage?(listener: (msg: AmspRecord) => void): void;
     /** Background command processes owned by the Session's environment (core `Session.listBackgroundCommands`). Optional: test fakes may omit it. */
     listBackgroundCommands?(): BackgroundCommandInfo[];
     /** Kills one background command process (core `Session.killBackgroundCommand`); false when the id is unknown. Optional, like listBackgroundCommands. */
@@ -1495,7 +1533,7 @@ interface RuntimeSession {
     /** All live subagent child sessions of the Session's environment (core `Session.listBackgroundSubagents`). Optional, like listBackgroundCommands. */
     listBackgroundSubagents?(): BackgroundSubagentInfo[];
     /** Host message to one child session — steering mid-run, a follow-up run when idle, a revival when released (core `Session.sendToBackgroundSubagent`). Optional. */
-    sendToBackgroundSubagent?(childSessionId: string, messages: OmniMessage[], opts?: SubagentMessageOptions): Promise<SubagentMessageOutcome>;
+    sendToBackgroundSubagent?(childSessionId: string, messages: AmspRecord[], opts?: SubagentMessageOptions): Promise<SubagentMessageOutcome>;
     /** Subscribes the host's session-lifetime fallback approval sink for child sessions (core `Session.setSubagentApprovalFallback`). Optional. */
     setSubagentApprovalFallback?(approve: ApproveFn): void;
     /** Aborts one child session's current run, keeping the session (core `Session.abortBackgroundSubagentRun`); false when unknown or idle. Optional. */
@@ -1513,13 +1551,13 @@ interface RuntimeSession {
 interface SessionLoader {
     /**
      * Load a runtime Session from an index row: recover (with a Trace) or self-heal
-     * rebuild (no Trace, session_id will change). Throws HttpError(409) for unrecoverable
+     * rebuild (no Trace, under the row's session_id). Throws HttpError(409) for unrecoverable
      * cases such as a missing Workspace.
      */
     load(row: SessionRow): Promise<RuntimeSession>;
 }
 interface UsageRecorderLike {
-    record(ctx: UsageContext, msg: OmniMessage): Promise<void>;
+    record(ctx: UsageContext, msg: AmspRecord): Promise<void>;
 }
 interface SessionManagerDeps {
     /** The in-memory state this manager works on (see agent-state.ts). Optional: a manager built without one — unit tests — gets an empty state of its own. */
@@ -1530,6 +1568,12 @@ interface SessionManagerDeps {
     /** Session-origin registry (session_meta is the single source of truth; subagent registration records the forwarded meta's source here). */
     sources: SessionOrigins;
     recorder: UsageRecorderLike;
+    /**
+     * The data root, for what is read off an Agent's state on disk before a Session is loaded
+     * (startGoal's goal-plugin check). Optional: a manager built without one — unit tests on a
+     * fake loader — skips those reads, and the loaded Session's own answer decides.
+     */
+    root?: string;
     /** Automatic Session title generation (optional: not injected in tests or when disabled). */
     titles?: TitleNotifier;
     /** Error persistence (optional: without it, only logs — same as before this was wired up). */
@@ -1576,7 +1620,7 @@ interface RecallStore {
 interface QueuedFollowUp {
     /** Recall handle (PendingFollowUpInfo.id), assigned at queue time. */
     id: string;
-    input: OmniMessage[];
+    input: AmspRecord[];
     /**
      * Original content for recall, and the content `task_state` shows on the queued line.
      * Always present: a caller that knows more than the input carries (the HTTP route, which
@@ -1589,7 +1633,7 @@ interface QueuedFollowUp {
 /** One undelivered steering entry: the display info broadcast on task_state, plus what a recall needs — the exact input list core queued (its unsteer handle) and the original content. */
 interface PendingSteeringEntry {
     info: PendingSteeringInfo;
-    input: OmniMessage[];
+    input: AmspRecord[];
     recall: RecallStore;
 }
 /** Active-table entry: a loaded runtime Session plus its running state. */
@@ -1631,7 +1675,7 @@ interface RuntimeEntry {
      * the input publish, so the live channel cannot backfill it either. GET /messages
      * appends the ones the Trace has not caught up to yet (exact-envelope dedup).
      */
-    pendingInputs: OmniMessage[];
+    pendingInputs: AmspRecord[];
     /**
      * The running Task's streamed bootstrap records (mcp_connect begin/end,
      * tool_list_ready), held until the run ends. Their Trace writes are deferred by the
@@ -1640,7 +1684,7 @@ interface RuntimeEntry {
      * otherwise show nothing at all (a silent blank while a slow server times out).
      * GET /messages appends whichever of them the Trace has not caught up to.
      */
-    pendingBootstrap: OmniMessage[];
+    pendingBootstrap: AmspRecord[];
     /**
      * Steering messages queued on core but not yet delivered to the model — a display mirror
      * of core's steering queue (same FIFO order), so the composer's "steering queued" hint and
@@ -1736,7 +1780,7 @@ declare class SessionManager {
      * the resume fallback names the child's owning Agent from its own session row, which must
      * belong to the parent's project.
      */
-    sendToSubagent(sessionId: string, childSessionId: string, messages: OmniMessage[]): Promise<SubagentMessageOutcome>;
+    sendToSubagent(sessionId: string, childSessionId: string, messages: AmspRecord[]): Promise<SubagentMessageOutcome>;
     /**
      * Sets a Session's thinking level on its loaded runtime (core `Session.thinkingLevel`,
      * plain state): the row's value is what the loader applies at load, so this only needs to
@@ -1752,12 +1796,12 @@ declare class SessionManager {
     /** Queued follow-up tasks awaiting auto-start, as their display/recall info (id + content summary). */
     pendingFollowUpsOf(sessionId: string): PendingFollowUpInfo[];
     /**
-     * Live tail of a running session: one synthetic `partial_* start` OmniMessage per open
+     * Live tail of a running session: one synthetic `partial_* start` AmspRecord per open
      * streaming fragment, carrying the full accumulated content so far (see live-tail.ts).
      * Empty when idle or when nothing is streaming. GET /messages attaches this (with a
      * channel cursor) so a client joining mid-stream can render the in-progress message.
      */
-    liveFragments(sessionId: string): OmniMessage[];
+    liveFragments(sessionId: string): AmspRecord[];
     /**
      * The running Task's input messages as published at launch; empty when idle. The engine
      * writes these exact envelopes to the Trace only after the first run's bootstrap (MCP
@@ -1765,9 +1809,9 @@ declare class SessionManager {
      * not caught up to yet — without this, a client rebuilding history during the connect
      * (the draft flow subscribes only after the input publish) loses the user's own message.
      */
-    pendingInputs(sessionId: string): OmniMessage[];
+    pendingInputs(sessionId: string): AmspRecord[];
     /** The running Task's streamed bootstrap records (see RuntimeEntry.pendingBootstrap); empty when idle. */
-    pendingBootstrap(sessionId: string): OmniMessage[];
+    pendingBootstrap(sessionId: string): AmspRecord[];
     /** Number of Sessions for this Agent that are currently running / compacting. */
     activeCountForAgent(projectId: string, agentId: string): number;
     /** Add a newly created Session to the active table (status idle), avoiding a redundant load on the next Task. */
@@ -1855,7 +1899,7 @@ declare class SessionManager {
      * caller's store is read off the input, so a queued follow-up is recallable and shows
      * its content whichever path queued it.
      */
-    startTask(sessionId: string, input: OmniMessage[], opts?: {
+    startTask(sessionId: string, input: AmspRecord[], opts?: {
         queueIfBusy?: boolean;
         recall?: RecallStore;
     }): Promise<{
@@ -1885,13 +1929,15 @@ declare class SessionManager {
      * `user_prompt` hook (hooks run in core and nowhere else — `Session.runUserPromptHook`)
      * writes the Session's goal file and answers the round-1 protocol message; it runs under
      * the session lock AFTER the idle check, since it overwrites the goal file a running goal
-     * is reading. Not installed (null) is the route's 409; an empty answer a 500. Round inputs
+     * is reading. An Agent without the goal plugin's hook package is refused with the route's
+     * 409 before the Session is even loaded (goal-plugin.ts); a loaded Session whose hook
+     * answers null is the same 409, and an empty answer a 500. Round inputs
      * are yielded by core and published like any streamed message; progress additionally goes
      * out as goal_* server events (the run state itself is the goal file the plugin maintains).
      */
     startGoal(sessionId: string, args: {
         /** The user's own message(s) exactly as submitted — text and images, no wrapping. */
-        messages: OmniMessage[];
+        messages: AmspRecord[];
         /** The user's own objective text (leading marker blocks stripped): what the plugin records, the goal_started event and the title material. */
         objective: string;
         budget: number;
@@ -1901,7 +1947,7 @@ declare class SessionManager {
     /**
      * Taps a goal run's stream for `drive`: round boundaries become goal_round events —
      * round 1 from the seeded input (core never yields a run's initial input, so it is
-     * counted here, where startGoal published it), later rounds from the stop-hook continues
+     * counted here, from what startGoal echoes), later rounds from the stop-hook continues
      * core yields, each announced by the hook's `continue` event; a harness-stamped input
      * nothing announced is another package's user_prompt context riding behind the
      * objective, not a round — and the goal hook's `stop` event becomes the
@@ -1914,9 +1960,9 @@ declare class SessionManager {
     /** Closes a goal as aborted for the UI (stream cut off / infrastructure failure). */
     private finishAborted;
     /**
-     * Shared task launch (fresh tasks, auto-started follow-ups and retries): flips to running,
-     * publishes the input, and drives the run. Caller holds the session lock and has verified
-     * idle. A retry's input is empty: nothing is published or held, and drive gets no title
+     * Shared task launch (fresh tasks, auto-started follow-ups and retries): flips to running
+     * and drives the run, which echoes the input. Caller holds the session lock and has verified
+     * idle. A retry's input is empty: nothing is echoed or held, and drive gets no title
      * material — the turn it resends already offered its text when it was first sent.
      */
     private launchTask;
@@ -1996,7 +2042,7 @@ declare class SessionManager {
      * keeps the composer's "steering queued" hint, content included, alive across reloads —
      * and the content itself is what a recall (recallSteering) hands back to the composer.
      */
-    steer(sessionId: string, input: OmniMessage[], recall: RecallStore): void;
+    steer(sessionId: string, input: AmspRecord[], recall: RecallStore): void;
     /**
      * Recall an undelivered steering message (#287): withdraw it from core's queue and the
      * display mirror, re-broadcast state, and hand back its original content for the composer
@@ -2152,12 +2198,10 @@ declare class SessionManager {
      * a Task arriving mid-load waits for this load instead of starting a second one.
      *
      * A Session that is gone or being deleted, alone or with its Agent, resolves quietly: there is
-     * nothing to warm and the caller has nothing to do about it. So does one with no Trace yet,
-     * because loading it is a self-heal REBUILD under a new session id — that would move the
-     * Session out from under the binding that asked, and earlier than any Task would. The row's
-     * `hasTrace` is a cache, so a row that has not caught up only misses the warm-up. Any other
-     * load failure rejects; the first Task meets the same failure and reports it where a person
-     * will see it.
+     * nothing to warm and the caller has nothing to do about it. One that never ran is rebuilt
+     * under its own id (see createCoreSessionLoader), so the binding that asked keeps its Session.
+     * Any other load failure rejects; the first Task meets the same failure and reports it where a
+     * person will see it.
      */
     preload(sessionId: string): Promise<void>;
     private assertOpen;
@@ -2168,7 +2212,9 @@ declare class SessionManager {
     private assertIdle;
     private generationOf;
     private refreshProviderCredentialIfNeeded;
-    /** get-or-resume-or-heal: use directly on an active-table hit; otherwise load via the loader, updating the index's primary key on self-heal. */
+    /** get-or-resume-or-heal: use directly on an active-table hit; otherwise load via the loader, updating the index's primary key when it answers another id. */
+    /** startGoal's check before the load (goal-plugin.ts); an unknown id is left to ensureEntry's 404. */
+    private assertGoalPluginInstalled;
     private ensureEntry;
     /**
      * Auto-start of queued background completion notices: called when core signals an
@@ -2182,7 +2228,8 @@ declare class SessionManager {
      * Drive the output stream in the background: publish each message + persist usage +
      * persist LLM/tool errors; on completion (including errors) resets to idle and pushes
      * the status. `titleSource` is passed only for Task runs (compaction doesn't generate
-     * a title): its user text drives automatic title generation at run start.
+     * a title): its user text drives automatic title generation at run start, and its `echo`
+     * is the run's input, published right behind the run's first `task_begin` (see InputEcho).
      */
     private drive;
     /**
@@ -2330,7 +2377,17 @@ declare abstract class AgentLifecycle {
     abstract listAgents(projectId: string): Promise<AgentListItem[]>;
     /** Every id `createAgent` refuses as taken, as names only, including a folder that does not list. */
     abstract takenAgentIds(projectId: string): Promise<string[]>;
-    abstract deleteAgent(projectId: string, agentId: string): Promise<void>;
+    /**
+     * Moves the Agent's folder out of the agents directory in one rename and drops its index row,
+     * so it is gone from every list and route at once; its files are then removed in the
+     * background, as the returned deletion reports. Refuses a built-in Agent, and a folder another
+     * program holds open (409 `agent_folder_busy`, nothing deleted).
+     */
+    abstract deleteAgent(projectId: string, agentId: string): Promise<AgentDeletionInfo>;
+    /** Where one deletion stands; null once it is unknown here (finished long ago, or never was). */
+    abstract agentDeletion(projectId: string, deletionId: string): AgentDeletionInfo | null;
+    /** Removes whatever deleted Agents left behind when the server last stopped mid-removal. */
+    abstract resumeDeletions(): Promise<void>;
     abstract createAgent(projectId: string, agentId: string, name?: string, description?: string, skillNames?: readonly string[], directory?: {
         path: string;
         names: readonly string[];
@@ -2357,7 +2414,7 @@ interface AgentListItem {
     kernelOutdated: boolean;
     /** Number of vault keys. */
     vaultKeyCount: number;
-    /** Number of scheduled tasks (count of .toml files under schedule/, including invalid ones). */
+    /** Number of scheduled tasks (count of .toml files directly under schedule/, including invalid ones; archived files under schedule/expired/ are not counted). */
     scheduleCount: number;
     /** Workbench folders with a manifest, including ones with a load error. */
     workbenchCount: number;
@@ -2376,7 +2433,19 @@ declare class AgentService implements AgentLifecycle {
     private readonly agents;
     private readonly agentConfig;
     private readonly snapshots;
-    /** Union of DB index ∪ directory scan; unmanaged directory Agents are backfilled into the DB. */
+    /** Deletions this process knows, by `${projectId}/${deletionId}`. */
+    private readonly deletions;
+    /** The removals in flight, by the same key. */
+    private readonly running;
+    /** Shared by every removal, so two deletions at once still hold only PURGE_SLOTS calls. */
+    private readonly limiter;
+    /** Ends this generation's removals when it is disposed; the next one resumes them from disk. */
+    private readonly stopping;
+    setup(ctx: ClassCtx): void;
+    /**
+     * Union of DB index ∪ directory scan; unmanaged directory Agents are backfilled into the DB.
+     * Only what `AgentConfig.exists` accepts is listed — the rule every route checks.
+     */
     listAgents(projectId: string): Promise<AgentListItem[]>;
     /** Count installed folders without compiling or walking their UI/runtime assets. */
     private workbenchCount;
@@ -2388,7 +2457,7 @@ declare class AgentService implements AgentLifecycle {
     takenAgentIds(projectId: string): Promise<string[]>;
     /** Number of vault keys (falls back to 0 on read failure). */
     private vaultKeyCount;
-    /** Number of scheduled tasks: count of .toml files under schedule/ (0 if the directory doesn't exist). */
+    /** Number of scheduled tasks: count of .toml files directly under schedule/ (0 if the directory doesn't exist). The expired/ subdirectory of archived files is not a .toml name, so it is never counted. */
     private scheduleCount;
     /**
      * One pass over `skills/` and one over `hooks/`, answering the card's questions: how many
@@ -2449,14 +2518,32 @@ declare class AgentService implements AgentLifecycle {
     /** Last config modification time: the later of system_config.yaml and AGENTS.md mtime; omitted if neither is readable. */
     private configUpdatedAt;
     /**
-     * Delete an Agent: the sole built-in Agent
-     * default_agent (shared with the CLI, the default conversation Agent) cannot be
-     * deleted; callers must first drain any active run via manager.abortAgent.
-     * The directory is deleted recursively (including Trace), and the DB's
-     * agents/sessions index rows are removed along with it; usage records are kept
-     * (historical stats are unaffected).
+     * Delete an Agent: the built-in Agents cannot be deleted; callers must first drain any active
+     * run (the session manager's `beginAgentDeletion`) and let go of what holds the folder open.
+     *
+     * The folder (Agent State, Traces, scratchpads, temporary Workspaces) is moved to
+     * `agents/.deleting/<id>-<time>` in one rename and the index row dropped: from then on no list
+     * shows the Agent and no route accepts it, and a new Agent may take its id. The move is the
+     * whole of what the caller waits for — the contents are removed in the background, reported by
+     * the deletion returned (and by `agentDeletion` as it goes). A folder that cannot be moved is
+     * refused with nothing deleted (409 `agent_folder_busy`). Usage records are kept (historical
+     * stats are unaffected); the caller drops the Agent's other index rows.
+     */
+    deleteAgent(projectId: string, agentId: string): Promise<AgentDeletionInfo>;
+    agentDeletion(projectId: string, deletionId: string): AgentDeletionInfo | null;
+    /**
+     * Every folder left under a Project's `agents/.deleting/` — a deletion the last process did
+     * not finish, or one that met an entry it could not remove — is removed again, one after
+     * another. Folders a deletion of this process is already removing are left to it.
      */
-    deleteAgent(projectId: string, agentId: string): Promise<void>;
+    resumeDeletions(): Promise<void>;
+    /**
+     * Renames the Agent's folder into `.deleting/`. Null when there was no folder to move; a
+     * folder a program keeps holding is refused with nothing moved.
+     */
+    private moveAside;
+    /** Starts removing `.deleting/<deletionId>` in the background; answers its first reading. */
+    private startPurge;
     /**
      * Create an Agent: the id is chosen by the creator (a semantic id, checked for
      * duplicates against both the DB and the directory within the Project — a 409
@@ -2844,7 +2931,7 @@ type AppEnv = {
 /** Minimal dependency on SessionManager (eases test doubles; mirrors ScheduleTaskRunner). */
 interface MessagingTaskRunnerShape {
     statusOf(sessionId: string): string;
-    startTask(sessionId: string, input: OmniMessage[], 
+    startTask(sessionId: string, input: AmspRecord[], 
     /**
      * `recall` is what a queued follow-up hands back when the user withdraws it in the Web
      * App. It is optional because the manager derives one from the input for every caller
@@ -3322,9 +3409,18 @@ interface PluginConfigSlots {
     groups: Slot<SettingsGroupDecl>;
 }
 
-/** The assembled business surface: one request in, one response (or a decline) out. */
+/**
+ * The assembled business surface: one request in, one response (or a decline) out.
+ *
+ * `fetchAs` is the same surface entered as a user already established by other means — the
+ * API socket (socket/serve.ts), whose handshake the runtime authenticated and whose owner it
+ * checked before the platform ever saw the socket. Those requests carry no cookie, so the
+ * gate in front of the routes is not the cookie one but "this user": the routes themselves,
+ * their authorization and their errors are identical.
+ */
 declare abstract class Http {
     abstract fetch(request: Opaque<"Request", Request>): Promise<Opaque<"Response", Response>>;
+    abstract fetchAs(userId: string, request: Opaque<"Request", Request>): Promise<Opaque<"Response", Response>>;
 }
 interface HttpSlots {
     /**