@maudecode/talaria-web-contracts 1.19.0 → 1.21.0

package/dist/sidecar/namespaces.js

@@ -1,7 +1,10 @@
+import { OutboundDraftRefSchema, OutboundDraftFieldsSchema, OutboundDraftResultSchema } from '../outbound-drafts.js';
+import { McpCostPolicyDataSchema } from '../mcp-cost-policy.js';
+import { ContextDetailSchema } from '../context-detail.js';
 import { z } from 'zod';
 import { ProviderPhaseSchema } from '../run-status.js';
 import { SpeedTierSchema } from '../speed.js';
-import { GatewaySessionParamsSchema, GatewaySessionResultSchema } from '../gateway-session.js';
+import { GatewayClarifyBatchSchema, GatewayCreateParamsSchema, GatewaySessionParamsSchema, GatewaySessionResultSchema } from '../gateway-session.js';
 /** Warnings and wording come from the Agent's selection guard registry, including future guard kinds. */
 export const ModelSelectionWarningSchema = z.object({ kind: z.string(), title: z.string(), model: z.string(), provider: z.string(), message: z.string() });
 /** Shared param shapes. */
@@ -71,37 +74,93 @@ export const PluginSettingFieldSchema = z.object({
     key: z.string(), type: z.enum(['string', 'number', 'boolean', 'enum', 'json', 'secret']), label: z.string(), description: z.string(), required: z.boolean(),
     choices: z.array(z.string()).optional(), default: Json.optional(), value: Json.optional(), env: z.string().optional(), has_value: z.boolean().optional(),
 });
+/** Persistence succeeded; this separately describes application to live plugin MCP connections. */
+export const PluginRuntimeApplicationSchema = z.enum(['applied', 'restart_required', 'unknown']);
+/** TAL-1276: one OAuth client a plugin manifest declares, its grant's state as `hermes auth status` maps it, and the hosts the code is approved at and exchanged at. */
+export const PluginOAuthStateSchema = z.enum(['signed_in', 'sign_in_needed', 'revoked', 'logged_out']);
+export const PluginOAuthClientSchema = z.object({ id: z.string(), state: PluginOAuthStateSchema, authorize_host: z.string(), token_host: z.string() });
+export const PluginUpdateResultSchema = z.discriminatedUnion('status', [
+    z.object({ key: z.string(), status: z.literal('updated') }),
+    z.object({ key: z.string(), status: z.literal('needs_consent'), verdict: z.literal('caution'), findings: z.string(), consent_token: z.string().min(1) }),
+    z.object({ key: z.string(), status: z.literal('blocked'), verdict: z.string(), findings: z.string() }),
+]);
+export const PluginCatalogQuerySchema = z.object({ query: z.string().trim().max(200).default(''), offset: z.coerce.number().int().min(0).max(10000).default(0), limit: z.coerce.number().int().min(1).max(50).default(20) });
+export const PluginInstallInputSchema = z.object({ name: z.string().regex(/^[a-z0-9_-]{1,64}$/), consent_token: z.string().min(1).max(128).optional() });
+export const PluginCatalogSchema = z.object({ supported: z.boolean(), read_only: z.boolean().optional(), entries: z.array(z.object({
+        name: z.string(), title: z.string(), description: z.string(), repo: z.string(), sha: z.string(), tier: z.string(), category: z.string(),
+        requirements: z.array(z.string()), installed_key: z.string().nullable(), installed_sha: z.string().nullable(), can_install: z.boolean(), refusal: z.string().nullable(),
+    })), total: z.number().int().nonnegative(), next_offset: z.number().int().nullable() });
+export const PluginInstallResultSchema = z.discriminatedUnion('status', [
+    z.object({ name: z.string(), key: z.string(), status: z.literal('installed'), enabled: z.literal(false) }),
+    z.object({ name: z.string(), status: z.literal('needs_consent'), findings: z.string(), consent_token: z.string() }),
+    z.object({ name: z.string(), status: z.literal('blocked'), findings: z.string() }),
+]);
 export const PluginProviderSchema = z.object({ name: z.string(), display_name: z.string(), auth_type: z.string(), setup: z.enum(['ready', 'missing_cli', 'needs_setup', 'not_loaded', 'unavailable']) });
+/** Profile-owned Agent dashboards use Web protocol panels; native Desktop bundles need migration. */
+export const AgentDashboardPluginSchema = z.object({
+    name: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/), label: z.string().max(80), version: z.string().max(40), description: z.string().max(300),
+    enabled: z.boolean(), panel: z.string().nullable(), has_api: z.boolean(),
+});
+export const AgentDashboardResponseSchema = z.object({ status: z.number().int().min(200).max(599), body: z.string(), content_type: z.string() });
+const DashboardNameParams = ProfileHomeParams.extend({ name: z.string() });
 /** A skill bundle: `/<name>` loads its `skill_count` skills in one message (TAL-265). */
 export const CommandBundleSchema = z.object({ name: z.string(), description: z.string(), skill_count: z.number().int(), source: z.literal('bundle') });
 /** `message` is the user message that loads the bundle's skills; members not installed or disabled are in `missing_skills` or left out. */
 export const CommandBundleInvocationSchema = z.object({ name: z.string(), source: z.literal('bundle'), message: z.string(), loaded_skills: z.array(z.string()), missing_skills: z.array(z.string()) });
+export const MAX_MANAGED_BUFFER_BYTES = 256 * 1024;
+const ManagedBufferName = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/);
+const ManagedBufferSize = z.number().int().min(0).max(MAX_MANAGED_BUFFER_BYTES);
 export const COMMANDS_METHODS = {
+    'drafts.review': { params: OutboundDraftRefSchema.extend({ profile_home: z.string().min(1), session_id: z.string().min(1), action: z.enum(['read', 'edit', 'approve']), version: z.number().int().positive().optional(), revision: z.string().optional(), fields: OutboundDraftFieldsSchema.optional() }), result: OutboundDraftResultSchema },
     'commands.registry': { params: ProfileHomeParams, result: z.object({ commands: z.array(CommandSchema) }) },
-    /** With `session_id`, a plugin command runs under that chat's session binding and `workspace` (TAL-904). */
+    /**
+     * With `session_id`, a plugin command runs under that chat's session binding and `workspace` (TAL-904) and receives the session
+     * as its handler declares it; every recognised command fires the Agent's `pre_command` hook with that session (TAL-1267).
+     */
     'commands.exec': { params: ProfileHomeParams.extend({ command: z.string().min(1), session_id: z.string().min(1).optional(), workspace: z.string().optional() }), result: z.object({ output: z.string(), source: z.enum(['agent', 'plugin']) }) },
     /**
      * `/<prompt built-in> [args]` as the turn text (`message`) the Agent's builder writes for the session's profile, workspace and toolsets.
      * `name` is the built-in's canonical name, null when the command is not one; `message` is null when this Agent has no builder for it.
-     * A failing builder errors `prompt_expand_failed`.
+     * A failing builder errors `prompt_expand_failed`. Every built-in fires the Agent's `pre_command` hook with `session_id` (TAL-1279).
      */
-    'commands.expand_prompt': { params: ProfileHomeParams.extend({ command: z.string().min(1), workspace: z.string(), enabled_toolsets: z.array(z.string()).nullable() }), result: z.object({ name: z.string().nullable(), message: z.string().nullable() }) },
+    'commands.expand_prompt': { params: ProfileHomeParams.extend({ command: z.string().min(1), session_id: z.string().min(1).optional(), workspace: z.string(), enabled_toolsets: z.array(z.string()).nullable() }), result: z.object({ name: z.string().nullable(), message: z.string().nullable() }) },
     'commands.bundles': { params: ProfileHomeParams, result: z.object({ bundles: z.array(CommandBundleSchema) }) },
     'commands.bundle_resolve': { params: ProfileHomeParams.extend({ command: z.string().min(1) }), result: CommandBundleInvocationSchema },
     'commands.moa_preset': { params: ProfileHomeParams.extend({ preset: z.string().nullable().optional() }), result: z.object({ moa: Loose }) },
+    /** Fixed devkit buffer adapter. No arbitrary HTTP paths, promotion or cleanup. Native saves are unconditional. */
+    'plugins.buffers': {
+        params: ProfileHomeParams.extend({ action: z.enum(['list', 'read', 'save']), session_id: z.string().min(1).max(200), name: ManagedBufferName.optional(), content: z.string().max(MAX_MANAGED_BUFFER_BYTES).optional() }),
+        result: z.object({ supported: z.boolean(), buffers: z.array(z.object({ name: ManagedBufferName, size: ManagedBufferSize, read_only: z.boolean() })).max(200), content: z.string().max(MAX_MANAGED_BUFFER_BYTES).optional(), size: ManagedBufferSize.optional(), read_only: z.boolean().optional(), write_semantics: z.literal('unconditional') }),
+    },
+    'plugins.dashboard_list': { params: ProfileHomeParams, result: z.object({ supported: z.boolean(), plugins: z.array(AgentDashboardPluginSchema) }) },
+    'plugins.dashboard_toggle': { params: DashboardNameParams.extend({ enabled: z.boolean() }), result: z.object({ ok: z.literal(true) }) },
+    'plugins.dashboard_asset': { params: DashboardNameParams.extend({ path: z.string() }), result: AgentDashboardResponseSchema },
+    /** Buffered HTTP only. Cancellation abandons the result; the Agent has no handler-cancel operation. */
+    'plugins.dashboard_request': { params: DashboardNameParams.extend({ path: z.string(), method: z.string(), query: z.string(), headers: z.record(z.string(), z.string()), body: z.string(), authenticated: z.boolean(), websocket: z.boolean() }), result: AgentDashboardResponseSchema },
     'plugins.providers': { params: ProfileHomeParams, result: z.object({ providers: z.array(PluginProviderSchema) }) },
-    'plugins.list': { params: ProfileHomeParams.extend({ selected_providers: z.record(z.string(), z.string()).optional() }), result: z.object({ plugins: z.array(z.object({ name: z.string(), key: z.string(), version: z.string(), description: z.string(), enabled: z.boolean(), kind: z.string(), activation: z.string(), hooks: z.array(z.string()), is_active_provider: z.boolean().optional() })), supported_hooks: z.array(z.string()) }) },
+    'plugins.list': { params: ProfileHomeParams.extend({ selected_providers: z.record(z.string(), z.string()).optional() }), result: z.object({ plugins: z.array(z.object({ name: z.string(), key: z.string(), version: z.string(), description: z.string(), enabled: z.boolean(), kind: z.string(), activation: z.string(), hooks: z.array(z.string()), is_active_provider: z.boolean().optional(), update_available: z.boolean().optional(), latest_revision: z.string().optional() })), supported_hooks: z.array(z.string()) }) },
+    'plugins.catalog': { params: ProfileHomeParams.extend(PluginCatalogQuerySchema.shape), result: PluginCatalogSchema },
+    'plugins.install': { params: ProfileHomeParams.extend(PluginInstallInputSchema.shape), result: PluginInstallResultSchema },
+    'plugins.update': { params: ProfileHomeParams.extend({ key: z.string().min(1), accept_caution: z.boolean().optional(), consent_token: z.string().min(1).max(128).optional() }), result: PluginUpdateResultSchema },
     /** TAL-820: each profile's `plugins.isolation` and installed third-party plugin count, read without loading a plugin. */
     'plugins.isolation': { params: BaseHomeParams, result: z.object({ profiles: z.array(z.object({ name: z.string(), isolation: z.enum(['in_process', 'host']), third_party_plugins: z.number().int() })) }) },
     /** TAL-806: plugins whose manifest declares settings; `supported` is false on an Agent without `hermes_cli.plugins_settings`. */
     'plugins.settings': { params: ProfileHomeParams, result: z.object({ supported: z.boolean(), plugins: z.array(z.object({ key: z.string(), fields: z.array(PluginSettingFieldSchema) })) }) },
+    /**
+     * TAL-1276: plugins whose manifest declares OAuth clients (Agent v0.22.3+), each client's sign-in state as
+     * `hermes auth status <plugin>:<id>` reports it, and the hosts the CLI names before signing in: the code is approved
+     * at `authorize_host` and exchanged at `token_host`. `supported` is false on an Agent without the plugin OAuth helpers.
+     */
+    'plugins.oauth_status': { params: ProfileHomeParams, result: z.object({ supported: z.boolean(), plugins: z.array(z.object({ key: z.string(), clients: z.array(PluginOAuthClientSchema) })) }) },
+    /** TAL-1276: `hermes auth logout <plugin>:<id>`; `removed` is false when no grant was stored. Errors `oauth_unsupported` on older Agents. */
+    'plugins.oauth_logout': { params: ProfileHomeParams.extend({ key: z.string().min(1), id: z.string().min(1) }), result: z.object({ key: z.string(), id: z.string(), removed: z.boolean() }) },
     /**
      * TAL-806: write non-secret `values` through the Agent's locked plugin-state writer and return the refreshed fields.
      * An undeclared key, a secret or a type mismatch is invalid params; a managed install or key errors `plugin_settings_managed`.
      * `secret_envs` (secret key → `.env` name the caller wrote) is checked against the current manifest before anything is
      * written; a key that is no longer a secret stored under that name errors `plugin_settings_changed`.
      */
-    'plugins.settings_save': { params: ProfileHomeParams.extend({ key: z.string().min(1), values: z.record(z.string(), Json), secret_envs: z.record(z.string(), z.string()).optional() }), result: z.object({ key: z.string(), written: z.array(z.string()), fields: z.array(PluginSettingFieldSchema) }) },
+    'plugins.settings_save': { params: ProfileHomeParams.extend({ key: z.string().min(1), values: z.record(z.string(), Json), secret_envs: z.record(z.string(), z.string()).optional() }), result: z.object({ key: z.string(), written: z.array(z.string()), fields: z.array(PluginSettingFieldSchema), runtime_application: PluginRuntimeApplicationSchema.optional() }) },
 };
 // ── kanban ─────────────────────────────────────────────────────────────
 const Board = ProfileHomeParams.extend({ board: z.string().nullable().optional() });
@@ -124,7 +183,14 @@ export const KanbanBoardSchema = z.union([
 export const KanbanAssigneeSchema = z.union([z.string(), z.object({ name: z.string(), on_disk: z.boolean().optional(), counts: z.record(z.string(), z.number().int()).optional() }).catchall(Json)]);
 export const KanbanEventSchema = z.object({ id: z.number().int(), task_id: z.string().nullable(), run_id: z.union([z.number().int(), z.string()]).nullable(), kind: z.string(), payload: Json, created_at: z.number().nullable() });
 export const KanbanBoardMetaSchema = z.object({ slug: z.string(), name: z.string().nullable().optional(), archived: z.boolean().optional() }).catchall(Json);
+export const KanbanInspectionEdgeSchema = z.object({ source: z.string(), target: z.string() });
+export const KanbanInspectionNodeSchema = z.object({ key: z.string(), board: z.string(), board_name: z.string(), task: KanbanTaskSchema.extend(KanbanRunStartShape) });
+export const KanbanInspectionSnapshotSchema = z.object({
+    nodes: z.array(KanbanInspectionNodeSchema).max(500),
+    edges: z.array(KanbanInspectionEdgeSchema).max(2000), generated_at: z.number(), truncated: z.boolean(), read_only: z.boolean(),
+});
 export const KANBAN_METHODS = {
+    'kanban.inspection': { params: Board.extend({ include_archived: z.boolean().optional() }), result: KanbanInspectionSnapshotSchema },
     'kanban.board': { params: Board.extend({ tenant: z.string().nullable().optional(), assignee: z.string().nullable().optional(), include_archived: z.boolean().optional(), only_mine: z.boolean().optional(), since: z.number().int().nullable().optional(), profile: z.string().nullable().optional() }), result: KanbanBoardSchema },
     'kanban.boards': { params: ProfileHomeParams.extend({ include_archived: z.boolean().optional() }), result: z.object({ boards: z.array(KanbanBoardMetaSchema.extend({ is_current: z.boolean(), counts: z.record(z.string(), z.number().int()), total: z.number().int() })), current: z.string(), read_only: z.boolean() }) },
     'kanban.create_board': { params: ProfileHomeParams.extend({ board_spec: Loose }), result: z.object({ board: KanbanBoardMetaSchema, current: z.string(), read_only: z.boolean() }) },
@@ -166,6 +232,12 @@ export const STATE_DB_METHODS = {
     'state_db.delete_cli_session': { params: Session.extend({ include_compression_lineage: z.boolean().optional() }), result: Ok.extend({ refused: SessionDeleteRefusedSchema.optional(), deleted_ids: z.array(z.string().min(1)).optional() }) },
     /** TAL-258: append one row through the Agent's `SessionDB.append_message` (bumps `message_count`); `ok` is false without a state.db. */
     'state_db.append_message': { params: Session.extend({ role: z.string().min(1), content: z.string(), tool_name: z.string().nullable().optional(), timestamp: z.number().nullable().optional() }), result: Ok },
+    /**
+     * TAL-1274: the Agent's low-disk session auto-prune question for the profile (Agent v0.22.3 `hermes_cli.prune_advisor`), as the
+     * Agent's own `lines` naming `/autoprune on|off|later`; null while the Agent would not ask (disk not low, `sessions.auto_prune`
+     * set, or snoozed) or has no advisor. May measure state.db, which takes seconds on a large store.
+     */
+    'state_db.prune_advice': { params: ProfileHomeParams, result: z.object({ advice: z.object({ lines: z.array(z.string()).min(1) }).nullable() }) },
 };
 // ── profiles ───────────────────────────────────────────────────────────
 /** TAL-213: the profile's canonical Bot Chat (its session titled exactly "Bot Chat") and that chat's live compression tip. */
@@ -209,6 +281,7 @@ export const SKILLS_METHODS = {
 };
 // ── mcp ────────────────────────────────────────────────────────────────
 export const MCP_METHODS = {
+    'mcp.cost_policies': { params: ProfileHomeParams.extend({ servers: Loose }), result: z.object({ supported: z.boolean(), policies: z.array(McpCostPolicyDataSchema) }) },
     'mcp.status': { params: ProfileHomeParams, result: z.object({ servers: z.array(z.object({ name: z.string() }).catchall(Json)) }) },
     'mcp.registry_tools': { params: ProfileHomeParams, result: z.object({ tools: z.array(z.object({ name: z.string(), server: z.string(), schema: Loose })) }) },
     'mcp.reload': { params: ProfileHomeParams, result: z.object({ output: z.string() }) },
@@ -312,7 +385,7 @@ export const CRON_METHODS = {
     'cron.history': { params: CronJob.extend({ offset: z.number().int().optional(), limit: z.number().int().optional() }), result: z.object({ job_id: z.string(), runs: z.array(z.object({ filename: z.string(), size: z.number().int(), modified: z.number(), usage: CronUsageSchema })), total: z.number().int(), offset: z.number().int() }) },
     'cron.run_detail': { params: CronJob.extend({ filename: z.string().min(1) }), result: z.object({ job_id: z.string(), filename: z.string(), content: z.string(), snippet: z.string(), usage: CronUsageSchema }) },
     'cron.output': { params: CronJob.extend({ limit: z.number().int().optional() }), result: z.object({ job_id: z.string(), outputs: z.array(z.object({ filename: z.string(), content: z.string() })) }) },
-    'cron.delivery_options': { params: z.object({}), result: z.object({ platforms: z.array(z.object({ value: z.string(), label: z.string() })) }) },
+    'cron.delivery_options': { params: ProfileHomeParams, result: z.object({ platforms: z.array(z.object({ value: z.string(), label: z.string() })) }) },
 };
 // ── providers / models ─────────────────────────────────────────────────
 /**
@@ -339,14 +412,21 @@ export const PROVIDERS_METHODS = {
  * `oauth.start` answers the code to show; a sidecar thread polls the provider and writes the credential through the
  * Agent's own auth store. A flow belongs to the profile home that started it: poll and cancel from another home do not
  * find it. `error` is the Agent's reason for a flow that ended without a credential.
+ *
+ * TAL-1276: provider `plugin:<key>:<id>` is the browser sign-in of a plugin-declared OAuth client. Its start has no
+ * `user_code`; `verification_url` is the authorize link, `redirect_uri` the loopback address the browser is sent back
+ * to, and `authorize_host`/`token_host` the hosts the code goes to. It finishes when that redirect reaches the sidecar's
+ * listener or through `oauth.submit_redirect` with the address the browser showed (`oauth_redirect_invalid` for any
+ * other address, `oauth_flow_ended` once the flow ended).
  */
 export const OAuthFlowStatusSchema = z.enum(['pending', 'approved', 'denied', 'expired', 'cancelled', 'error']);
 const OAuthFlow = z.object({ flow_id: z.string(), provider: z.string(), status: OAuthFlowStatusSchema, error: z.string().nullable() });
 const OAuthFlowParams = ProfileHomeParams.extend({ flow_id: z.string().min(1) });
 export const OAUTH_METHODS = {
-    'oauth.start': { params: ProfileHomeParams.extend({ provider: z.string().min(1) }), result: z.object({ flow_id: z.string(), provider: z.string(), status: z.literal('pending'), user_code: z.string(), verification_url: z.string(), expires_in: z.number().int(), interval: z.number().int() }) },
+    'oauth.start': { params: ProfileHomeParams.extend({ provider: z.string().min(1) }), result: z.object({ flow_id: z.string(), provider: z.string(), status: z.literal('pending'), user_code: z.string().optional(), verification_url: z.string(), expires_in: z.number().int(), interval: z.number().int(), redirect_uri: z.string().optional(), authorize_host: z.string().optional(), token_host: z.string().optional() }) },
     'oauth.poll': { params: OAuthFlowParams, result: OAuthFlow },
     'oauth.cancel': { params: OAuthFlowParams, result: OAuthFlow },
+    'oauth.submit_redirect': { params: OAuthFlowParams.extend({ url: z.string().min(1) }), result: OAuthFlow },
 };
 // ── aux / text / process / usage / gateway ─────────────────────────────
 export const AuxUsageSchema = z.object({ prompt_tokens: z.number().int().optional(), completion_tokens: z.number().int().optional(), total_tokens: z.number().int().optional() });
@@ -420,6 +500,7 @@ export const PROCESS_METHODS = {
     /** Hands back a claim the busy target never admitted, without spending one of the Agent's delivery attempts. */
     'process.defer_delivery': { params: ProfileHomeParams.extend({ event: Loose, claim_id: z.string() }), result: Ok },
     'process.format_notification': { params: z.object({ event: Loose }), result: z.object({ text: z.string() }) },
+    'process.stop': { params: ProfileHomeParams.extend({ session_id: z.string().min(1), process_id: z.string().min(1) }), result: z.object({ outcome: z.enum(['stopped', 'not_running', 'not_found']) }) },
     'process.list': { params: ProfileHomeParams, result: z.object({ sessions: z.array(Loose) }) },
     /** TAL-372: the Agent's view of these WebUI sessions' background work: ledger delegations (with live status) and notified processes. */
     'process.background_list': {
@@ -490,6 +571,12 @@ export const CONFIG_METHODS = {
 };
 export const WORKTREE_METHODS = {
     'worktree.create': { params: ProfileHomeParams.extend({ repo_root: z.string().min(1) }), result: z.object({ path: z.string(), branch: z.string(), repo_root: z.string(), base: z.string().nullable() }) },
+    /**
+     * TAL-1254: relock Talaria's worktrees for this sidecar (`hermes pid=<pid>`) so the Agent's worktree sweep reads them as
+     * live. `foreign_lock`: a lock that is not a `hermes pid=` one holds the tree and stays. A tree this sidecar does not
+     * hold yet (a running process's `hermes pid=` lock, or a git failure) is absent from `results`; the caller retries it.
+     */
+    'worktree.retain': { params: z.object({ paths: z.array(z.string().min(1)) }), result: z.object({ results: z.record(z.string(), z.enum(['retained', 'missing', 'foreign_lock'])) }) },
 };
 /** TAL-913: a workspace's checkpoints, read and restored through the Agent's `CheckpointManager`; `store` is its shared git store. */
 const CheckpointTarget = ProfileHomeParams.extend({ workspace: z.string().min(1) });
@@ -498,7 +585,14 @@ export const CHECKPOINTS_METHODS = {
     'checkpoints.list': { params: CheckpointTarget, result: z.object({ checkpoints: z.array(AgentCheckpointSchema), store: z.string() }) },
     /** `diff` is `git diff <checkpoint> --cached` over the workspace: `a/` is the checkpoint, `b/` the files now. */
     'checkpoints.diff': { params: CheckpointTarget.extend({ checkpoint: z.string().min(1) }), result: z.object({ stat: z.string(), diff: z.string() }) },
-    'checkpoints.restore': { params: CheckpointTarget.extend({ checkpoint: z.string().min(1) }), result: z.object({ restored_to: z.string(), reason: z.string() }) },
+    /**
+     * Safe unless `all` (TAL-1260): only files still as the Agent last wrote them are reverted, and `kept_user_edits` names the
+     * hand-edited ones left in place. `restored_files` is what a safe restore acted on; null when the whole tree was checked out.
+     */
+    'checkpoints.restore': {
+        params: CheckpointTarget.extend({ checkpoint: z.string().min(1), all: z.boolean().optional() }),
+        result: z.object({ restored_to: z.string(), reason: z.string(), restored_files: z.array(z.string()).nullable(), kept_user_edits: z.array(z.string()), skipped_oversize: z.array(z.string()), failed_deletes: z.array(z.string()) }),
+    },
 };
 // ── chat / approval / clarify ──────────────────────────────────────────
 export const ChatUsageSchema = z.object({ prompt_tokens: z.number().int(), completion_tokens: z.number().int(), cache_read_tokens: z.number().int(), cache_write_tokens: z.number().int(), estimated_cost_usd: z.number().nullable() });
@@ -540,6 +634,7 @@ export const ChatStreamSchema = z.discriminatedUnion('event', [
     /** TAL-397: the Agent's session counters, before the content frame that follows a change. */
     z.object({ event: z.literal('usage'), data: ChatUsageSchema }),
     z.object({ event: z.literal('tool'), data: ToolFrame }),
+    z.object({ event: z.literal('tool_progress'), data: z.object({ tool_call_id: z.string(), message: z.string().nullable().optional(), progress: z.number().nullable().optional(), total: z.number().nullable().optional(), percent: z.number().nullable().optional() }) }),
     z.object({ event: z.literal('tool_complete'), data: ToolFrame }),
     z.object({ event: z.literal('approval'), data: Loose }),
     z.object({ event: z.literal('clarify'), data: Loose }),
@@ -628,9 +723,12 @@ export const CHAT_METHODS = {
             commit_token: z.string().nullable(),
         }),
     },
+    /** TAL-1333: safe metadata from the existing matching resident Agent, never a new Agent. */
+    'chat.context_detail': { params: ProfileHomeParams.extend({ session_id: z.string().min(1), model: z.string().nullable(), model_provider: z.string().nullable(), workspace: z.string().nullable() }), result: ContextDetailSchema },
     /** TAL-255: second phase of `chat.compress`; `finalized: false` when the token is unknown or already expired. */
     'chat.compress_finalize': { params: z.object({ commit_token: z.string().min(1), committed: z.boolean() }), result: z.object({ finalized: z.boolean() }) },
-    'chat.finalize_session': { params: ProfileHomeParams.extend({ session_id: z.string().min(1), reason: z.enum(['clear', 'delete']) }), result: z.object({ messages: z.array(z.string()) }) },
+    /** Archive only emits on_session_delete for the committed local transition; it never closes the Agent session. */
+    'chat.finalize_session': { params: ProfileHomeParams.extend({ session_id: z.string().min(1), reason: z.enum(['clear', 'delete', 'archive']), lineage: z.array(z.string().min(1)).max(10_000).optional() }), result: z.object({ messages: z.array(z.string()) }) },
     'chat.evict_agent': { params: z.object({ session_id: z.string().min(1), clear_session: z.boolean().optional() }), result: z.object({ evicted: z.boolean() }) },
     'chat.commit_memory': { params: ProfileHomeParams.extend({ session_id: z.string().min(1) }), result: z.object({ committed: z.boolean() }) },
     /**
@@ -653,18 +751,26 @@ export const CHAT_METHODS = {
     'approval.set_yolo': { params: z.object({ session_id: z.string().min(1), enabled: z.boolean() }), result: z.object({ yolo_enabled: z.boolean(), released: z.number().int() }) },
     'clarify.respond': { params: z.object({ stream_id: z.string().optional(), session_id: z.string().optional(), clarify_id: z.string().optional(), response: z.string() }), result: z.object({ ok: z.boolean(), clarify_id: z.string().optional() }) },
 };
-const GatewayActionParams = ProfileHomeParams.extend({ cli_profile: z.string().nullable().optional(), quick_timeout_seconds: z.number().optional(), background_wait_seconds: z.number().optional() });
+const GatewayActionParams = ProfileHomeParams.extend({ interrupt: z.boolean().optional(), cli_profile: z.string().nullable().optional(), quick_timeout_seconds: z.number().optional(), background_wait_seconds: z.number().optional() });
 /**
  * A lifecycle run of `hermes --profile <name> gateway <action>` for the profile at `profile_home` (TAL-894). `busy` means another
- * action holds the lock; `timed_out` marks a child killed after `background_wait_seconds` (a restart defaults to the Agent CLI's own
+ * action holds the lock; `busy_live_work` is an Agent live-work refusal. `interrupt` explicitly consents to interruption.
+ * `timed_out` marks a child killed after `background_wait_seconds` (a restart defaults to the Agent CLI's own
  * restart budget plus 30 s) or cancelled. `detail` is CLI output, never shown to a browser; `reason` is the Agent's first error line of a
  * failed run (TAL-884), the one line the server shows.
  */
-const GatewayActionResult = z.object({ status: z.enum(['completed', 'failed', 'busy']), message: z.string(), detail: z.string().optional(), returncode: z.number().int().optional(), reason: z.string().optional(), timed_out: z.boolean().optional() });
+const GatewayActionResult = z.object({ status: z.enum(['completed', 'failed', 'busy', 'busy_live_work']), message: z.string(), detail: z.string().optional(), returncode: z.number().int().optional(), reason: z.string().optional(), timed_out: z.boolean().optional() });
 const GatewayActionStream = z.discriminatedUnion('event', [z.object({ event: z.literal('progress'), data: z.object({ phase: z.enum(['started', 'draining']) }) })]);
 export const GATEWAY_ACTIONS = ['start', 'stop', 'restart'];
 export const GATEWAY_METHODS = {
-    'gateway.session': { params: GatewaySessionParamsSchema, result: GatewaySessionResultSchema, stream: z.object({ event: z.enum(['snapshot', 'event']), data: Loose }) },
+    'gateway.session': { params: GatewaySessionParamsSchema, result: GatewaySessionResultSchema, stream: z.discriminatedUnion('event', [
+            z.object({ event: z.literal('snapshot'), data: GatewaySessionResultSchema.extend({ replaying: z.boolean().optional(), reaction_only: z.boolean().optional() }) }),
+            z.object({ event: z.literal('event'), data: Loose }),
+            z.object({ event: z.literal('replay_complete'), data: z.object({}) }),
+            z.object({ event: z.literal('clarify_batch'), data: GatewayClarifyBatchSchema }),
+            z.object({ event: z.literal('restarting'), data: z.object({ restarting: z.literal(true) }) }),
+        ]) },
+    'gateway.create': { params: GatewayCreateParamsSchema, result: GatewaySessionResultSchema },
     'gateway.control': { params: GatewayActionParams.extend({ action: z.enum(GATEWAY_ACTIONS) }), result: GatewayActionResult, stream: GatewayActionStream },
     'gateway.restart': { params: GatewayActionParams, result: GatewayActionResult, stream: GatewayActionStream },
     /** TAL-805: the gateway mode of the profile `name` at `profile_home`; the root profile (`is_default`) is the host itself. */