@maudecode/talaria-web-contracts 1.18.0 → 1.19.0

package/dist/sidecar/namespaces.js

@@ -1,17 +1,35 @@
 import { z } from 'zod';
+import { ProviderPhaseSchema } from '../run-status.js';
+import { SpeedTierSchema } from '../speed.js';
+import { 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. */
 export const ProfileHomeParams = z.object({ profile_home: z.string().min(1) });
 export const BaseHomeParams = z.object({ base_home: z.string().min(1) });
 const Ok = z.object({ ok: z.boolean() });
 const Json = z.unknown();
 const Loose = z.record(z.string(), z.unknown());
+/** Profile-scoped toolset choices; clients render policy and selection without deriving them. */
+export const ToolsetsCatalogSchema = z.object({
+    toolsets: z.array(z.object({
+        name: z.string(), description: z.string(), available: z.boolean(), selected: z.boolean(),
+        unavailable_reason: z.enum(['disabled', 'unavailable']).nullable(),
+    })),
+    selected_toolsets: z.array(z.string()), using_defaults: z.boolean(),
+});
+export const TOOLSETS_METHODS = {
+    'toolsets.catalog': { params: ProfileHomeParams.extend({ enabled_toolsets: z.array(z.string()).nullable() }), result: ToolsetsCatalogSchema },
+};
 // ── goals ──────────────────────────────────────────────────────────────
 export const GoalStateSchema = z.object({
     goal: z.string(), status: z.string(), turns_used: z.number().int(), max_turns: z.number().int(),
     last_verdict: z.string().nullable(), last_reason: z.string().nullable(), paused_reason: z.string().nullable(),
 });
 const GoalSession = ProfileHomeParams.extend({ session_id: z.string().min(1), default_max_turns: z.number().int().positive().optional() });
-export const GoalStatusSchema = z.object({ goal: GoalStateSchema.nullable(), active: z.boolean(), message: z.string(), message_key: z.string().optional(), message_args: z.array(Json).optional() });
+/** TAL-808: `parked` is an active goal's live wait barrier: its reason and, for a timed wait, the Unix-seconds deadline. */
+export const GoalParkedSchema = z.object({ reason: z.string().nullable(), until: z.number().nullable() });
+export const GoalStatusSchema = z.object({ goal: GoalStateSchema.nullable(), active: z.boolean(), parked: GoalParkedSchema.nullable(), message: z.string(), message_key: z.string().optional(), message_args: z.array(Json).optional() });
 export const GoalCommandResultSchema = z.object({
     ok: z.boolean(), action: z.string(), message: z.string(), goal: GoalStateSchema.nullable(), error: z.string().optional(), kickoff_prompt: z.string().optional(),
     message_key: z.string().optional(), message_args: z.array(Json).optional(),
@@ -22,10 +40,11 @@ export const GoalDecisionSchema = z.object({
 });
 export const GOALS_METHODS = {
     'goals.get': { params: GoalSession, result: GoalStatusSchema },
-    'goals.command': { params: GoalSession.extend({ args: z.string(), stream_running: z.boolean().optional() }), result: GoalCommandResultSchema },
+    // `workspace`: the session's declared workspace, where the Agent runs goal gates (TAL-882).
+    'goals.command': { params: GoalSession.extend({ args: z.string(), stream_running: z.boolean().optional(), workspace: z.string().optional() }), result: GoalCommandResultSchema },
     'goals.snapshot': { params: GoalSession, result: z.object({ goal: GoalStateSchema.nullable(), snapshot: z.string().nullable() }) },
     'goals.restore': { params: GoalSession.extend({ snapshot: z.string().nullable() }), result: z.object({ goal: GoalStateSchema.nullable() }) },
-    'goals.evaluate': { params: GoalSession.extend({ last_response: z.string(), user_initiated: z.boolean().optional() }), result: GoalDecisionSchema },
+    'goals.evaluate': { params: GoalSession.extend({ last_response: z.string(), user_initiated: z.boolean().optional(), workspace: z.string().optional() }), result: GoalDecisionSchema },
 };
 // ── commands / plugins ─────────────────────────────────────────────────
 export const CommandSchema = z.object({
@@ -33,12 +52,25 @@ export const CommandSchema = z.object({
     cli_only: z.boolean(), gateway_only: z.boolean(),
     /** `commands.exec` runs it: the sidecar's runtime commands and every plugin command (TAL-561). */
     exec: z.boolean(),
+    /**
+     * An Agent prompt built-in, which every Agent surface answers by sending its builder's prompt as the turn (TAL-817):
+     * `expand` when `commands.expand_prompt` can build it on this Agent, `unsupported` when it cannot; null for any other command.
+     */
+    prompt: z.enum(['expand', 'unsupported']).nullable(),
 });
 /**
  * A model-provider plugin installed and enabled in the profile (TAL-288); bundled providers are built-ins. `setup` is the Agent's
  * own verdict without spawning the plugin's CLI: `not_loaded` means the installed plugin could not be loaded (import failure, or its
  * provider id or directory name is taken by another profile's plugin in this process-wide registry).
  */
+/**
+ * TAL-806: one field of a plugin manifest's `config_schema` (Agent `plugin_settings_fields`) with its current value from
+ * `plugins.entries.<key>.settings`, else `default`. A `secret` field carries its `.env` name and `has_value`, never a value.
+ */
+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(),
+});
 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']) });
 /** 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') });
@@ -46,22 +78,45 @@ export const CommandBundleSchema = z.object({ name: z.string(), description: z.s
 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 COMMANDS_METHODS = {
     'commands.registry': { params: ProfileHomeParams, result: z.object({ commands: z.array(CommandSchema) }) },
-    'commands.exec': { params: ProfileHomeParams.extend({ command: z.string().min(1) }), result: z.object({ output: z.string(), source: z.enum(['agent', 'plugin']) }) },
+    /** With `session_id`, a plugin command runs under that chat's session binding and `workspace` (TAL-904). */
+    '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`.
+     */
+    '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.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 }) },
     '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()) }) },
+    /** 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-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) }) },
 };
 // ── kanban ─────────────────────────────────────────────────────────────
 const Board = ProfileHomeParams.extend({ board: z.string().nullable().optional() });
-/** `claim_live`: a running task's worker still holds its claim. `has_completion_evidence`: the task stores a result, which the Agent requires to complete it (TAL-557). */
-export const KanbanTaskSchema = z.object({ id: z.string(), title: z.string(), status: z.string(), priority: z.number().int(), claim_live: z.boolean(), has_completion_evidence: z.boolean() }).catchall(Json);
+/** `claim_live`: a running task's worker still holds its claim. `has_completion_evidence`: the task stores a result, which the Agent requires to complete it (TAL-557).
+ * `agent_move_targets`: the Agent workflow's manual moves from the task's status, `null` before Agent 0.21.6 (TAL-796). */
+export const KanbanTaskSchema = z.object({ id: z.string(), title: z.string(), status: z.string(), priority: z.number().int(), claim_live: z.boolean(), has_completion_evidence: z.boolean(), agent_move_targets: z.array(z.string()).nullable() }).catchall(Json);
 const TaskEnvelope = z.object({ task: KanbanTaskSchema, read_only: z.boolean() });
+/** Task detail's links (TAL-809): `link_tasks` names each linked task that still exists; `current_run_started_at` is the active run's start, `null` without one (`started_at` is the first-ever start). */
+export const KanbanTaskLinksShape = { links: z.object({ parents: z.array(z.string()), children: z.array(z.string()) }), link_tasks: z.array(z.object({ id: z.string(), title: z.string(), status: z.string() })) };
+export const KanbanRunStartShape = { current_run_started_at: z.number().nullable() };
 export const KanbanBoardSchema = z.union([
     z.object({ changed: z.literal(false), latest_event_id: z.number().int(), read_only: z.boolean() }),
     z.object({
-        changed: z.literal(true), columns: z.array(z.object({ name: z.string(), tasks: z.array(KanbanTaskSchema) })), tenants: z.array(z.string()), assignees: z.array(z.string()),
+        /** The Agent workflow's columns in board order (TAL-796): `name` is the status key, `label` the Agent's English label. */
+        changed: z.literal(true), columns: z.array(z.object({ name: z.string(), label: z.string(), tasks: z.array(KanbanTaskSchema) })), tenants: z.array(z.string()), assignees: z.array(z.string()),
         latest_event_id: z.number().int(), read_only: z.boolean(),
         filters: z.object({ tenant: z.string().nullable(), assignee: z.string().nullable(), include_archived: z.boolean(), only_mine: z.boolean(), profile: z.string().nullable() }),
     }),
@@ -76,7 +131,7 @@ export const KANBAN_METHODS = {
     'kanban.update_board': { params: ProfileHomeParams.extend({ slug: z.string(), board_spec: Loose }), result: z.object({ board: KanbanBoardMetaSchema, read_only: z.boolean() }) },
     'kanban.delete_board': { params: ProfileHomeParams.extend({ slug: z.string(), delete: z.boolean().optional() }), result: z.object({ result: Json, current: z.string(), read_only: z.boolean() }) },
     'kanban.switch_board': { params: ProfileHomeParams.extend({ slug: z.string() }), result: z.object({ current: z.string(), read_only: z.boolean() }) },
-    'kanban.task': { params: Board.extend({ task_id: z.string() }), result: z.object({ task: KanbanTaskSchema, comments: z.array(Loose), events: z.array(Loose), links: z.object({ parents: z.array(z.string()), children: z.array(z.string()) }), runs: z.array(Loose), read_only: z.boolean() }) },
+    'kanban.task': { params: Board.extend({ task_id: z.string() }), result: z.object({ task: KanbanTaskSchema.extend(KanbanRunStartShape), comments: z.array(Loose), events: z.array(Loose), ...KanbanTaskLinksShape, runs: z.array(Loose), read_only: z.boolean() }) },
     'kanban.create_task': { params: Board.extend({ task: Loose }), result: TaskEnvelope },
     'kanban.patch_task': { params: Board.extend({ task_id: z.string(), patch: Loose }), result: TaskEnvelope },
     'kanban.task_action': { params: Board.extend({ task_id: z.string(), action: z.enum(['block', 'unblock']), reason: z.string().nullable().optional(), confirm_running_exit: z.boolean().optional() }), result: TaskEnvelope },
@@ -86,29 +141,46 @@ export const KANBAN_METHODS = {
     'kanban.normalize_board': { params: Board, result: z.object({ board: z.string() }) },
     'kanban.events': { params: Board.extend({ since: z.number().int().optional(), limit: z.number().int().optional() }), result: z.object({ events: z.array(KanbanEventSchema), cursor: z.number().int(), latest_event_id: z.number().int(), read_only: z.boolean() }) },
     'kanban.config': { params: Board, result: z.object({ columns: z.array(z.string()), assignees: z.array(KanbanAssigneeSchema), default_tenant: z.string(), lane_by_profile: z.boolean(), include_archived_by_default: z.boolean(), render_markdown: z.boolean(), read_only: z.boolean() }) },
-    'kanban.stats': { params: Board, result: Loose },
+    /** `column_order`: the Agent workflow's column keys in board order (TAL-796). */
+    'kanban.stats': { params: Board, result: z.object({ column_order: z.array(z.string()) }).catchall(Json) },
     'kanban.assignees': { params: Board, result: z.object({ assignees: z.array(KanbanAssigneeSchema) }) },
     'kanban.task_log': { params: Board.extend({ task_id: z.string(), tail: z.number().int().optional() }), result: z.object({ task_id: z.string(), path: z.string(), exists: z.boolean(), size_bytes: z.number().int(), content: z.string(), truncated: z.boolean() }) },
     'kanban.bulk': { params: Board.extend({ bulk: Loose }), result: z.object({ results: z.array(z.object({ id: z.string(), ok: z.boolean(), error: z.string().optional() })), read_only: z.boolean() }) },
     'kanban.dispatch': { params: Board.extend({ dry_run: z.boolean().optional(), max: z.number().int().optional() }), result: Loose },
 };
 // ── state_db ───────────────────────────────────────────────────────────
+/** Busy Agent work, or retained canonical history that this Agent cannot safely retire. */
+export const SessionDeleteRefusedSchema = z.enum(['active_turn', 'runtime_history_unsupported']);
 const Session = ProfileHomeParams.extend({ session_id: z.string().min(1) });
 export const STATE_DB_METHODS = {
     'state_db.sync_start': { params: Session.extend({ model: z.string().nullable().optional() }), result: Ok },
     'state_db.sync_usage': { params: Session.extend({ input_tokens: z.number().int().optional(), output_tokens: z.number().int().optional(), estimated_cost: z.number().nullable().optional(), model: z.string().nullable().optional(), title: z.string().nullable().optional(), message_count: z.number().int().nullable().optional(), cache_read_tokens: z.number().int().optional(), cache_write_tokens: z.number().int().optional(), api_call_count: z.number().int().nullable().optional() }), result: Ok },
     /** TAL-574: `manual` writes a user-requested title (rename or regenerate) with `user` provenance; otherwise it is an `llm` auto title. */
     'state_db.sync_title': { params: Session.extend({ title: z.string(), manual: z.boolean().optional() }), result: Ok },
-    'state_db.delete_cli_session': { params: Session, result: Ok },
+    /**
+     * TAL-792: `include_compression_lineage` also removes the session's compression continuations, resolved and removed in the
+     * same transaction (tip first). `refused` when another Agent process holds a live turn lease or compression lock on any
+     * row the delete would remove, or the Agent lacks retirement APIs for retained canonical history; nothing is removed. `deleted_ids` is the transaction's committed target set,
+     * including continuations/delegates; it remains present when only post-commit artifact cleanup failed.
+     */
+    '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 },
 };
 // ── profiles ───────────────────────────────────────────────────────────
 /** TAL-213: the profile's canonical Bot Chat (its session titled exactly "Bot Chat") and that chat's live compression tip. */
 export const CanonicalBotChatSchema = z.object({ session_id: z.string(), tip_session_id: z.string() });
+/**
+ * TAL-805: a profile's gateway under the host multiplexer. `own` runs its own gateway process, `served` is served by the
+ * live host gateway, `parked` was stopped through the host (`hermes -p X gateway stop`) and nothing runs, `standalone` opted out of the host
+ * and is not running, `stopped` is none of these. Only `own` and `served` are running; Agents without the multiplexer
+ * helpers report `own` or `stopped`.
+ */
+export const GatewayModeSchema = z.enum(['own', 'served', 'parked', 'standalone', 'stopped']);
 export const ProfileRowSchema = z.object({
     name: z.string(), path: z.string(), is_default: z.boolean(), gateway_running: z.boolean(), model: z.string().nullable(), provider: z.string().nullable(), has_env: z.boolean(),
     visible: z.boolean(), skill_count: z.number().int(), enabled_skills: z.number().int(), total_skills: z.number().int(),
+    gateway_mode: GatewayModeSchema.default('stopped'),
     // Absent reads as no identity and no chat, so hand-built rows (test fakes) need not spell them out.
     display_name: z.string().default(''), description: z.string().default(''), has_avatar: z.boolean().default(false),
     canonical_session: CanonicalBotChatSchema.nullable().default(null),
@@ -121,15 +193,19 @@ export const PROFILES_METHODS = {
     'profiles.skills_stats': { params: ProfileHomeParams, result: z.object({ enabled: z.number().int(), total: z.number().int() }) },
 };
 // ── skills ─────────────────────────────────────────────────────────────
-export const SkillRowSchema = z.object({ name: z.string(), description: z.string(), category: z.string().nullable(), disabled: z.boolean() });
+export const SkillCatalogIdentitySchema = z.object({
+    load_name: z.string().optional(), declared_name: z.string().optional(),
+    status: z.enum(['unique', 'ambiguous', 'shadowed']).optional(), tier: z.number().int().optional(),
+});
+export const SkillRowSchema = SkillCatalogIdentitySchema.extend({ name: z.string(), description: z.string(), category: z.string().nullable(), disabled: z.boolean() });
 export const SkillViewSchema = z.union([
-    z.object({ success: z.literal(true), name: z.string(), description: z.string(), tags: z.array(z.string()), related_skills: z.array(z.string()), content: z.string(), path: z.string(), skill_dir: z.string().nullable(), linked_files: z.record(z.string(), z.array(z.string())) }),
+    z.object({ success: z.literal(true), name: z.string(), description: z.string(), tags: z.array(z.string()), related_skills: z.array(z.string()), content: z.string(), path: z.string(), skill_dir: z.string().nullable(), linked_files: z.record(z.string(), z.array(z.string())), editable: z.boolean().optional() }),
     z.object({ success: z.literal(false), error: z.string(), available_skills: z.array(z.string()).optional(), available_skills_truncated: z.boolean().optional(), total_skills: z.number().int().optional(), hint: z.string().optional() }),
 ]);
 export const SKILLS_METHODS = {
     'skills.list': { params: ProfileHomeParams.extend({ category: z.string().nullable().optional() }), result: z.object({ success: z.boolean().optional(), skills: z.array(SkillRowSchema), categories: z.array(z.string()), count: z.number().int(), message: z.string().optional() }) },
     'skills.view': { params: ProfileHomeParams.extend({ name: z.string().min(1) }), result: SkillViewSchema },
-    'skills.find': { params: ProfileHomeParams.extend({ name: z.string().min(1) }), result: z.object({ found: z.boolean(), skill_dir: z.string().nullable(), skill_md: z.string().nullable() }) },
+    'skills.find': { params: ProfileHomeParams.extend({ name: z.string().min(1) }), result: z.object({ found: z.boolean(), skill_dir: z.string().nullable(), skill_md: z.string().nullable(), load_name: z.string().optional(), declared_name: z.string().optional(), sibling_load_names: z.array(z.string()).optional() }) },
 };
 // ── mcp ────────────────────────────────────────────────────────────────
 export const MCP_METHODS = {
@@ -137,18 +213,90 @@ export const MCP_METHODS = {
     '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() }) },
 };
+// ── connectors (TAL-818) ───────────────────────────────────────────────
+const ConnectorSlug = z.string().regex(/^[a-z0-9][a-z0-9_-]*$/);
+/** One portal policy layer's rules (the Agent's `PolicyBody`): `allow` names the apps that stay on, `deny` the ones off; `tools` turns single tools off. */
+export const ConnectorPolicyBodySchema = z.object({
+    mode: z.enum(['unrestricted', 'deny-all', 'allow', 'deny']),
+    connectors: z.array(z.string()).optional(), disabled_connectors: z.array(z.string()).optional(),
+    tools: z.record(z.string(), z.object({ disable: z.array(z.string()) })).optional(),
+    tags: z.object({ enable: z.array(z.string()).optional(), disable: z.array(z.string()).optional() }).optional(),
+});
+/** A connection operation's target (`tools/connectors/operation.py`): a hosted app account, or an MCP server the card approves. */
+export const ConnectorOperationTargetSchema = z.object({
+    name: z.string(), kind: z.string(), state: z.enum(['pending', 'initiated', 'connected', 'skipped', 'failed', 'expired', 'not_connected']), detail: z.string(),
+    connect_url: z.string().nullable().optional(),
+    required_env: z.array(z.object({ name: z.string(), prompt: z.string(), required: z.boolean(), secret: z.boolean() })),
+});
+/** `owner`: `account` for the Connectors page's connect, `session` for a chat card, which `tool_call_id` opened. */
+export const ConnectorOperationSnapshotSchema = z.object({ op_id: z.string(), settled: z.boolean(), owner: z.enum(['account', 'session']), tool_call_id: z.string().nullable(), targets: z.array(ConnectorOperationTargetSchema) });
+const ConnectorOp = ProfileHomeParams.extend({ op_id: z.string().min(1) });
+/**
+ * Failures carry `data.condition`: `connectors_unavailable`, `connectors_sign_in`, `connectors_forbidden`, `connectors_org_required`,
+ * `connector_not_found`, `connection_not_found`, `policy_conflict` (the member rules changed since `expected_revision`), `policy_invalid`,
+ * `operation_not_found`, `operation_settled`, `operation_refused`, `connectors_failed`.
+ */
+export const CONNECTORS_METHODS = {
+    /** The Agent's `connectors_available()`; never creates an identity. */
+    'connectors.available': { params: ProfileHomeParams, result: z.object({ available: z.boolean() }) },
+    'connectors.catalog': { params: ProfileHomeParams, result: z.object({ connectors: z.array(z.object({ slug: z.string(), name: z.string(), description: z.string(), category: z.string(), logo_url: z.string().nullable() })) }) },
+    'connectors.accounts': { params: ProfileHomeParams, result: z.object({ accounts: z.array(z.object({ connection_id: z.string(), connector: z.string(), status: z.string(), status_reason: z.string().nullable(), label: z.string(), alias: z.string().nullable(), active: z.boolean(), disabled: z.boolean(), created_at: z.string() })) }) },
+    'connectors.remove': { params: ProfileHomeParams.extend({ connection_id: z.string().min(1) }), result: z.object({ connection_id: z.string(), connector: z.string(), status: z.literal('removed') }) },
+    'connectors.tools': { params: ProfileHomeParams.extend({ connector: ConnectorSlug, refresh: z.boolean().optional() }), result: z.object({ connector: z.string(), tools: z.array(z.object({ slug: z.string(), name: z.string(), description: z.string(), facet: z.string(), hints: z.array(z.string()), categories: z.array(z.string()), deprecated: z.boolean() })) }) },
+    'connectors.policy.get': { params: ProfileHomeParams, result: z.object({ layers: z.array(z.object({ kind: z.enum(['org', 'role', 'member']), revision: z.string(), body: ConnectorPolicyBodySchema })), effective: ConnectorPolicyBodySchema.extend({ revision: z.string() }) }) },
+    /** One member-rule change: `enabled` turns the app on or off; `tool` with `tool_enabled` turns one of its tools on or off. */
+    'connectors.policy.set': { params: ProfileHomeParams.extend({ connector: ConnectorSlug, expected_revision: z.string().min(1), enabled: z.boolean().optional(), tool: z.string().min(1).optional(), tool_enabled: z.boolean().optional() }), result: z.object({ revision: z.string() }) },
+    /** Starts (or rejoins) the account-owned connect and waits for its authorization link. */
+    'connectors.connect': { params: ProfileHomeParams.extend({ connector: ConnectorSlug }), result: ConnectorOperationSnapshotSchema },
+    'connectors.operation': { params: ConnectorOp, result: ConnectorOperationSnapshotSchema },
+    'connectors.respond': { params: ConnectorOp.extend({ action: z.enum(['skip', 'retry', 'approve', 'continue']), target: z.string().optional(), env: z.record(z.string(), z.string()).optional() }), result: ConnectorOperationSnapshotSchema },
+};
 // ── stt ────────────────────────────────────────────────────────────────
 export const STT_METHODS = {
-    'stt.capability': { params: ProfileHomeParams, result: z.object({ available: z.boolean(), provider: z.string() }) },
-    'stt.transcribe': { params: ProfileHomeParams.extend({ audio_b64: z.string().min(1), suffix: z.string().optional() }), result: z.object({ transcript: z.string() }) },
+    /**
+     * `streaming` (TAL-802): `stt.streaming` is on and the provider has a live wire with credentials, so `stt.stream` would open.
+     * `warm_supported` (TAL-916): the available provider is the local engine and the Agent can pre-load it (`tools.stt_lease`),
+     * so `stt.warm` does real work.
+     */
+    'stt.capability': { params: ProfileHomeParams, result: z.object({ available: z.boolean(), provider: z.string(), streaming: z.boolean(), warm_supported: z.boolean() }) },
+    /**
+     * TAL-916: pre-load the profile's local engine (first-use download and model load) so the next `stt.transcribe` starts
+     * hot. Blocks until loaded; a no-op (`warmed: false`) for remote providers, and `action: 'unsupported'` on an Agent
+     * without the warmer.
+     */
+    'stt.warm': { params: ProfileHomeParams, result: z.object({ provider: z.string(), warmed: z.boolean(), action: z.string(), error: z.string().optional() }) },
+    'stt.transcribe': { params: ProfileHomeParams.extend({ audio_b64: z.string().min(1), suffix: z.string().optional() }), result: z.object({ transcript: z.string(), filtered: z.boolean() }) },
+    /**
+     * TAL-802: one live dictation. Opens the profile's streaming session for s16le mono PCM at `sample_rate` (the sidecar
+     * resamples), emits `ready` with the `stream_id` that `stt.stream_audio` feeds, then `partial` text as the provider
+     * recognizes it, and returns the session's final transcript once audio ends. Cancelling the call cancels the session.
+     */
+    'stt.stream': {
+        params: ProfileHomeParams.extend({ sample_rate: z.number().int().min(8000).max(48000) }),
+        result: z.object({ transcript: z.string(), filtered: z.boolean(), provider: z.string() }),
+        stream: z.discriminatedUnion('event', [
+            z.object({ event: z.literal('ready'), data: z.object({ stream_id: z.string() }) }),
+            z.object({ event: z.literal('partial'), data: z.object({ text: z.string() }) }),
+        ]),
+    },
+    /** TAL-802: feed one PCM chunk to an open `stt.stream`, in order; `end` marks the end of speech. */
+    'stt.stream_audio': { params: z.object({ stream_id: z.string().min(1), audio_b64: z.string().optional(), end: z.boolean().optional() }), result: z.object({ ok: z.literal(true) }) },
 };
 // ── cron ───────────────────────────────────────────────────────────────
-export const CronJobSchema = z.object({ id: z.string(), name: z.string().nullable().optional(), profile: z.string().nullable(), toast_notifications: z.boolean(), monitor: z.string(), continuity: z.boolean() }).catchall(Json);
+/** `running_elsewhere`: a live execution owner. `recovery_only`: a retained snapshot, not a source for new task context. */
+export const CronJobSchema = z.object({ id: z.string(), name: z.string().nullable().optional(), profile: z.string().nullable(), toast_notifications: z.boolean(), monitor: z.string(), continuity: z.boolean(), running_elsewhere: z.boolean().optional(), recovery_only: z.boolean().optional() }).catchall(Json);
 const CronJob = ProfileHomeParams.extend({ job_id: z.string().min(1) });
 const JobEnvelope = z.object({ job: CronJobSchema });
 export const CronUsageSchema = z.object({ model: z.string().optional(), provider: z.string().optional(), estimated_cost_usd: z.number().optional(), duration_seconds: z.number().optional(), input_tokens: z.number().int().nullable().optional(), output_tokens: z.number().int().nullable().optional(), total_tokens: z.number().int().nullable().optional() });
+export const CronBlueprintSlotSchema = z.object({ name: z.string(), type: z.string(), label: z.string(), default: z.string().nullable(), options: z.array(z.string()), optional: z.boolean(), strict: z.boolean(), help: z.string() });
+export const CronBlueprintsSchema = z.object({ blueprints: z.array(z.object({ key: z.string(), title: z.string(), description: z.string(), category: z.string(), source: z.enum(['builtin', 'plugin']), plugin: z.string().nullable(), schedule_label: z.string(), slots: z.array(CronBlueprintSlotSchema) })) });
+export const CronBlueprintFillInputSchema = z.object({ key: z.string().min(1), values: z.record(z.string(), z.string()) });
+export const CronBlueprintFillSchema = z.object({ draft: z.object({ name: z.string(), prompt: z.string(), schedule: z.string(), deliver: z.string(), skills: z.array(z.string()) }) });
 export const CRON_METHODS = {
-    'cron.list': { params: ProfileHomeParams, result: z.object({ jobs: z.array(CronJobSchema) }) },
+    'cron.blueprints': { params: ProfileHomeParams, result: CronBlueprintsSchema },
+    'cron.blueprint_fill': { params: CronBlueprintFillInputSchema.extend({ profile_home: z.string().optional() }), result: CronBlueprintFillSchema },
+    /** `probe_store` adds the store's write probe (TAL-810): null when writes land or the Agent predates the probe. */
+    'cron.list': { params: ProfileHomeParams.extend({ probe_store: z.boolean().optional() }), result: z.object({ jobs: z.array(CronJobSchema), store_health: z.object({ store: z.string(), error: z.string(), since: z.string(), fix: z.string() }).nullable().optional() }) },
     'cron.get': { params: CronJob, result: z.object({ job: CronJobSchema.nullable() }) },
     'cron.create': { params: ProfileHomeParams.extend({ job: Loose, execution_home: z.string().nullable().optional() }), result: JobEnvelope },
     'cron.update': { params: CronJob.extend({ updates: Loose }), result: JobEnvelope },
@@ -167,12 +315,20 @@ export const CRON_METHODS = {
     'cron.delivery_options': { params: z.object({}), result: z.object({ platforms: z.array(z.object({ value: z.string(), label: z.string() })) }) },
 };
 // ── providers / models ─────────────────────────────────────────────────
+/**
+ * `providers.model_ids` `fallback` (TAL-799): the Agent served its curated list because the live catalog was unreachable.
+ * `providers.local_models` (TAL-798): the GGUFs staged for the Agent's managed llama.cpp provider `provider_id`, and the
+ * running server's base URL (`current_endpoint`, null while it is off).
+ */
 export const PROVIDERS_METHODS = {
     'providers.registry': { params: ProfileHomeParams, result: z.object({ providers: z.record(z.string(), z.object({ id: z.string(), name: z.string(), auth_type: z.string() }).catchall(Json)) }) },
     'providers.auth_status': { params: ProfileHomeParams.extend({ provider: z.string().nullable().optional() }), result: z.object({ status: z.object({ logged_in: z.boolean() }).catchall(Json) }) },
-    'providers.model_ids': { params: ProfileHomeParams.extend({ provider: z.string().min(1), force_refresh: z.boolean().optional() }), result: z.object({ provider: z.string(), model_ids: z.array(z.string()) }) },
+    'providers.model_ids': { params: ProfileHomeParams.extend({ provider: z.string().min(1), force_refresh: z.boolean().optional() }), result: z.object({ provider: z.string(), model_ids: z.array(z.string()), fallback: z.boolean().default(false) }) },
+    'providers.local_models': { params: ProfileHomeParams, result: z.object({ provider_id: z.string(), models: z.array(z.string()), current_endpoint: z.string().nullable() }) },
     'providers.resolve_runtime': { params: ProfileHomeParams.extend({ requested: z.string().nullable().optional(), api_key: z.string().nullable().optional(), base_url: z.string().nullable().optional(), target_model: z.string().nullable().optional() }), result: z.object({ runtime: Loose }) },
     'providers.credential_pool': { params: ProfileHomeParams.extend({ provider: z.string().min(1) }), result: z.object({ available: z.boolean(), strategy: z.string(), entries: z.array(Loose) }) },
+    'models.selection_warnings': { params: ProfileHomeParams.extend({ session_id: z.string().min(1), model: z.string().min(1), provider: z.string().nullable(), current_model: z.string().nullable(), current_provider: z.string().nullable(), context_tokens: z.number().int().positive().nullable(), messages: z.array(Loose) }), result: z.object({ warnings: z.array(ModelSelectionWarningSchema), context_tokens: z.number().int().positive().nullable(), provider: z.string(), base_url: z.string() }) },
+    'models.speed_tiers': { params: ProfileHomeParams.extend({ routes: z.array(z.object({ model: z.string().min(1), provider: z.string(), base_url: z.string().optional() })) }), result: z.object({ tiers: z.array(z.array(SpeedTierSchema)) }) },
     'models.context_length': { params: ProfileHomeParams.extend({ model: z.string().min(1), base_url: z.string().optional(), api_key: z.string().optional(), provider: z.string().optional(), config_context_length: z.number().int().nullable().optional() }), result: z.object({ model: z.string(), context_length: z.number().int().nullable() }) },
     'models.estimate_tokens': { params: z.object({ messages: z.array(Loose) }), result: z.object({ tokens: z.number().int() }) },
     'models.capabilities': { params: ProfileHomeParams.extend({ provider: z.string(), model: z.string() }), result: z.object({ capabilities: Loose.nullable() }) },
@@ -200,13 +356,55 @@ export const AUX_METHODS = {
      * of the task's auxiliary route; `credential_missing` means it has no credential. `finish_reason` is the provider's, when known.
      */
     'aux.complete': { params: ProfileHomeParams.extend({ task: z.string().min(1), messages: z.array(Loose).min(1), main_runtime: Loose.nullable().optional(), main_fallback: z.boolean().optional(), max_tokens: z.number().int().nullable().optional(), temperature: z.number().nullable().optional(), model: z.string().nullable().optional(), provider: z.string().nullable().optional() }), result: z.object({ model: z.string(), text: z.string(), usage: AuxUsageSchema.nullable(), finish_reason: z.string().nullable().default(null) }), stream: z.discriminatedUnion('event', [z.object({ event: z.literal('token'), data: z.object({ text: z.string() }) })]) },
+    /**
+     * TAL-800: the profile's auxiliary slots in Agent order (built-ins, then the profile's plugin tasks). `reasoning_effort`
+     * is the slot's resolved effort (`''` = provider default); `effective` is the route an `inherit_from` task resolves to now.
+     * `reserved`: the Agent's other `auxiliary.*` keys (settings and unlisted routes); a reset never touches them.
+     */
+    'aux.tasks': { params: ProfileHomeParams, result: z.object({ tasks: z.array(z.object({ key: z.string().min(1), label: z.string(), description: z.string(), inherit_from: z.string().nullable(), reasoning_effort: z.string(), effective: z.object({ provider: z.string(), model: z.string(), base_url: z.string() }).nullable() })), reserved: z.array(z.string()) }) },
     'aux.resolve': { params: ProfileHomeParams.extend({ task: z.string().min(1), main_runtime: Loose.nullable().optional() }), result: z.object({ configured: z.boolean(), model: z.string().nullable(), error: z.string().optional() }) },
 };
 export const TEXT_METHODS = {
     'text.image_mode': { params: ProfileHomeParams.extend({ provider: z.string(), model: z.string(), cfg: Loose.nullable().optional(), requested_provider: z.string().optional() }), result: z.object({ mode: z.enum(['native', 'text']), reason: z.string(), supports_vision: z.boolean().nullable() }) },
     'text.portal_tags': { params: ProfileHomeParams, result: z.object({ client_tag: z.string().nullable(), conversation_tag: z.string().nullable(), tags: z.union([z.array(z.string()), Loose]) }) },
+    /** TAL-906: the Agent's read-aloud script (`prepare_spoken_text`); `text` as written on an Agent without it. */
+    'text.spoken': { params: z.object({ text: z.string() }), result: z.object({ spoken_text: z.string() }) },
+};
+/**
+ * TAL-886: the Agent's `MemoryStore` reading of a MEMORY.md / USER.md body: its char count and the profile's limit for that store.
+ * TAL-784: `memory.write` replaces a memory page file with `content` only while its bytes still hash (SHA-256 hex) to `base`,
+ * holding the Agent's per-file lock (`<file>.lock`); `written: false` means the file changed and is untouched.
+ */
+export const MEMORY_METHODS = {
+    'memory.check': { params: ProfileHomeParams.extend({ target: z.enum(['memory', 'user']), content: z.string() }), result: z.object({ count: z.number().int(), limit: z.number().int() }) },
+    'memory.write': { params: ProfileHomeParams.extend({ section: z.enum(['memory', 'user', 'soul']), base: z.string(), content: z.string() }), result: z.object({ written: z.boolean() }) },
 };
-export const ProcessEventSchema = z.object({ process_id: z.string(), consumed: z.boolean(), type: z.string().optional(), session_key: z.string().optional(), origin_ui_session_id: z.string().optional() }).catchall(Json);
+/**
+ * TAL-819: one write the Agent staged for approval (`skills.write_approval` / `memory.write_approval`). `target` is the skill
+ * name(s), or `memory` / `user` for the memory store; `op` the staged action; `diff` the unified diff an approval would apply
+ * (a skill create shows the new file, a write that would fail says why); `revision` is the SHA-256 of that diff, which an approval
+ * must send back. `approvable` is false when no diff could be built or the Agent would refuse the write (`diff` says why;
+ * `revision` is empty); such a write can only be rejected.
+ */
+export const PendingWriteSchema = z.object({
+    id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/), kind: z.enum(['skills', 'memory']), target: z.string(), op: z.string(), summary: z.string(),
+    origin: z.string(), created_at: z.number(), diff: z.string(), approvable: z.boolean(), revision: z.string(),
+});
+export const PendingWriteRefSchema = z.object({ id: PendingWriteSchema.shape.id, revision: z.string() });
+const WriteApprovalParams = ProfileHomeParams.extend({ kind: z.enum(['skills', 'memory']), writes: z.array(PendingWriteRefSchema).min(1) });
+const WriteApprovalResult = z.object({ results: z.array(z.object({ id: z.string(), done: z.boolean(), message: z.string() })) });
+/**
+ * TAL-819: the profile's staged writes of `kind`, oldest first, and whether its gate is on; `supported` is false on an Agent
+ * without the review handlers. `approve` / `reject` run the Agent's `/skills` or `/memory` handler per write; `done` is true
+ * once the record is gone (applied or dropped) and `message` is the handler's text. An approval whose diff no longer has the
+ * reviewed `revision` is refused (`done: false`) without applying.
+ */
+export const WRITE_APPROVAL_METHODS = {
+    'write_approval.pending': { params: ProfileHomeParams.extend({ kind: z.enum(['skills', 'memory']) }), result: z.object({ supported: z.boolean(), enabled: z.boolean(), items: z.array(PendingWriteSchema) }) },
+    'write_approval.approve': { params: WriteApprovalParams, result: WriteApprovalResult },
+    'write_approval.reject': { params: WriteApprovalParams, result: WriteApprovalResult },
+};
+export const ProcessEventSchema = z.object({ process_id: z.string(), consumed: z.boolean(), type: z.string().optional(), session_key: z.string().optional(), origin_ui_session_id: z.string().optional(), child_process: z.boolean().optional(), reconciliation_profile_home: z.string().optional() }).catchall(Json);
 export const PROCESS_METHODS = {
     'process.drain': { params: ProfileHomeParams.extend({ max_events: z.number().int().positive().optional() }), result: z.object({ events: z.array(ProcessEventSchema) }) },
     /** TAL-533: re-adopt the base home's and every named profile's checkpointed background processes in a fresh sidecar. */
@@ -216,7 +414,7 @@ export const PROCESS_METHODS = {
     /** TAL-532: the subset the agent already holds from its own turn (consumed via wait/log, or poll-observed). */
     'process.consumed': { params: z.object({ process_ids: z.array(z.string().min(1)) }), result: z.object({ consumed: z.array(z.string()) }) },
     /** TAL-459: the Agent's durable delivery ledger. A null claim means another consumer delivered (or holds) it; "" means nothing durable to acknowledge. */
-    'process.claim_delivery': { params: ProfileHomeParams.extend({ event: Loose, consumer: z.string().min(1) }), result: z.object({ claim_id: z.string().nullable() }) },
+    'process.claim_delivery': { params: ProfileHomeParams.extend({ event: Loose, consumer: z.string().min(1) }), result: z.object({ claim_id: z.string().nullable(), retryable: z.boolean().optional() }) },
     'process.complete_delivery': { params: ProfileHomeParams.extend({ event: Loose, claim_id: z.string() }), result: Ok },
     'process.release_delivery': { params: ProfileHomeParams.extend({ event: Loose, claim_id: z.string() }), result: Ok },
     /** Hands back a claim the busy target never admitted, without spending one of the Agent's delivery attempts. */
@@ -244,7 +442,7 @@ export const PROCESS_METHODS = {
 export const AccountUsageSnapshotSchema = z.object({ provider: z.string().nullable(), available: z.boolean(), unavailable_reason: z.string().nullable().optional(), windows: z.array(Loose), details: z.array(Json) }).catchall(Json);
 /**
  * TAL-548: one credential-pool entry's local state (no network, no secrets); the server derives a quota source per entry.
- * `matches_api_key`: the entry's key is the server-resolved `api_key` passed to `usage.pool`.
+ * `matches_api_key`: the entry's key is the configured key, passed as `api_key` or resolved from `env_vars` in the profile's secret scope.
  */
 export const PoolEntrySchema = z.object({
     credential_id: z.string(), label: z.string(), status: z.enum(['available', 'exhausted', 'dead']), unavailable_reason: z.string().nullable(), retry_after: z.string().nullable(),
@@ -252,7 +450,7 @@ export const PoolEntrySchema = z.object({
 });
 const BalanceNumber = z.number().nullable();
 /**
- * TAL-548: one key-based balance read. The key is the pool entry's (`credential_id`) or the server-resolved `api_key`.
+ * TAL-548: one key-based balance read. The key is the pool entry's (`credential_id`), a raw `api_key`, or resolved from `env_vars` in the profile's secret scope.
  * `ok` carries the provider's sanitised fields: OpenRouter `quota`/`label`, DeepSeek `balances`/`is_available`, OpenCode Go
  * `windows`; `http_error` carries the status code.
  */
@@ -263,18 +461,32 @@ export const BalanceResultSchema = z.object({
     windows: z.array(z.object({ key: z.enum(['rolling', 'weekly', 'monthly']), used_percent: z.number(), reset_at: z.string(), rate_limited: z.boolean() })),
 });
 const CredentialId = z.string().min(1).nullable().optional();
+/** TAL-807: the Agent's `CredentialPool.limit_state`: every live account benched until `resets_at`, else the given models no usable account serves until their ISO reset. */
+export const PoolLimitSchema = z.discriminatedUnion('scope', [
+    z.object({ scope: z.literal('account'), resets_at: z.string() }),
+    z.object({ scope: z.literal('models'), models: z.record(z.string(), z.string()) }),
+]);
 export const USAGE_METHODS = {
     'usage.account': { params: ProfileHomeParams.extend({ provider: z.string().min(1), base_url: z.string().nullable().optional(), api_key: z.string().nullable().optional(), credential_id: CredentialId }), result: z.object({ snapshot: AccountUsageSnapshotSchema.nullable() }) },
-    'usage.pool': { params: ProfileHomeParams.extend({ provider: z.string().min(1), api_key: z.string().nullable().optional() }), result: z.object({ entries: z.array(PoolEntrySchema) }) },
+    'usage.pool': { params: ProfileHomeParams.extend({ provider: z.string().min(1), api_key: z.string().nullable().optional(), env_vars: z.array(z.string().min(1)).optional() }), result: z.object({ entries: z.array(PoolEntrySchema), has_api_key: z.boolean().optional() }) },
     /** TAL-548: the providers whose persisted credential pool holds an account the user added, keyed or not. */
-    'usage.pool_providers': { params: ProfileHomeParams, result: z.object({ providers: z.array(z.string()) }) },
-    'usage.balance': { params: ProfileHomeParams.extend({ provider: z.enum(['openrouter', 'deepseek', 'opencode-go']), credential_id: CredentialId, api_key: z.string().nullable().optional() }), result: BalanceResultSchema },
+    'usage.pool_providers': { params: ProfileHomeParams.extend({ key_envs: z.record(z.string(), z.array(z.string().min(1))).optional() }), result: z.object({ providers: z.array(z.string()), keys: z.record(z.string(), z.object({ present: z.boolean(), revision: z.string().nullable() })).default({}) }) },
+    /** TAL-807: pool rate limits by provider slug, only for pooled providers that are limited; `models` are bare ids. */
+    'usage.limits': { params: ProfileHomeParams.extend({ providers: z.array(z.object({ slug: z.string().min(1), models: z.array(z.string()) })) }), result: z.object({ limits: z.record(z.string(), PoolLimitSchema) }) },
+    'usage.balance': { params: ProfileHomeParams.extend({ provider: z.enum(['openrouter', 'deepseek', 'opencode-go']), credential_id: CredentialId, api_key: z.string().nullable().optional(), env_vars: z.array(z.string().min(1)).optional() }), result: BalanceResultSchema },
 };
 export const CONFIG_METHODS = {
     // `config_path` is the server-resolved file (honouring HERMES_CONFIG_PATH); the sidecar reads and writes exactly that path.
     'config.get': { params: ProfileHomeParams.extend({ config_path: z.string().min(1) }), result: z.object({ path: z.string(), exists: z.boolean(), config: Loose }) },
     'config.set': { params: ProfileHomeParams.extend({ config_path: z.string().min(1), config: Loose }), result: z.object({ ok: z.literal(true), path: z.string() }) },
+    /** TAL-797: `.env` edits through the Agent's locked writer; `null` removes a key, an empty value is skipped; line breaks, spaces, quotes, `#` and non-ASCII are refused. */
+    'config.env_write': { params: ProfileHomeParams.extend({ updates: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string().nullable()) }), result: z.object({ ok: z.literal(true), path: z.string() }) },
     'models.reasoning_efforts': { params: ProfileHomeParams.extend({ model: z.string(), provider: z.string() }), result: z.object({ efforts: z.array(z.string()), supports_reasoning: z.boolean().nullable() }) },
+    /**
+     * TAL-901: the Agent's personalities for `config` (its built-ins, then the top-level `personalities:` block, then
+     * `agent.personalities`), by case-folded name in the Agent's order; `prompt` is the rendered overlay text.
+     */
+    'personalities.list': { params: z.object({ config: Loose }), result: z.object({ personalities: z.array(z.object({ name: z.string().min(1), description: z.string(), prompt: z.string() })) }) },
 };
 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() }) },
@@ -297,10 +509,16 @@ export const ChatUsageSchema = z.object({ prompt_tokens: z.number().int(), compl
  * A completed `compressed` turn also carries `context_messages`, its `messages` with tool output pruned and capped for the model (row for row),
  * and `post_compression_context_tokens_estimate`, the next request's estimated size (TAL-539); both are null otherwise.
  */
+/**
+ * The turn agent's context figures (`context_length`, `threshold_tokens`, `last_prompt_tokens`, `compression_count`). TAL-1005:
+ * `next_turn_threshold_tokens` is the compression threshold the next turn runs under, the primary runtime's when a fallback ran
+ * this one (the Agent restores the primary each turn); absent when the Agent reports none.
+ */
+const ChatContextSchema = z.looseObject({ next_turn_threshold_tokens: z.number().int().positive().optional() });
 export const ChatStartResultSchema = z.object({
     status: z.enum(['completed', 'cancelled', 'error']), messages: z.array(Loose), context_messages: z.array(Loose).nullable().optional(), post_compression_context_tokens_estimate: z.number().int().nullable().optional(), final_response: z.string(), error: z.string().nullable(),
     failed: z.boolean(), partial: z.boolean(), compression_exhausted: z.boolean(),
-    tool_limit_reached: z.boolean(), max_iterations_summary_request: z.string(), usage: ChatUsageSchema, context: Loose, model: z.string(), provider: z.string(), compressed: z.boolean(), agent_session_id: z.string(),
+    tool_limit_reached: z.boolean(), max_iterations_summary_request: z.string(), usage: ChatUsageSchema, context: ChatContextSchema, model: z.string(), provider: z.string(), compressed: z.boolean(), agent_session_id: z.string(),
     token_sent: z.boolean(), pending_steer: z.string(), live_tool_calls: z.array(Loose),
 });
 const Text = z.object({ text: z.string() }).catchall(Json);
@@ -309,6 +527,8 @@ const Text = z.object({ text: z.string() }).catchall(Json);
  * (scalars as sent, text and nested values as capped text) or its capped text. The server decides `is_error` from it and never forwards it; `is_error` is only an older sidecar's `false`.
  * A `todo` tool's frame also carries `todo_result`, the tool's full result text, which the server turns into `todo_state` (TAL-397) and never forwards.
  * A result with a string `diff` also carries `result_diff`, that whole diff, which the server turns into `edit_diff` (TAL-448) and never forwards.
+ * TAL-909: `display_metadata` is the dict the sidecar returned for the Agent to persist on the tool-result row (a file edit's unified `diff`
+ * from the Agent's before-snapshot); the server turns its `diff` into `edit_diff` when the result has none, and never forwards it.
  */
 const ToolFrame = z.object({ event_type: z.string(), name: z.string().nullable().optional(), preview: Json.optional(), args: Loose.optional(), tid: z.string().optional(), is_error: z.boolean().optional() }).catchall(Json);
 export const ChatStreamSchema = z.discriminatedUnion('event', [
@@ -324,11 +544,26 @@ export const ChatStreamSchema = z.discriminatedUnion('event', [
     z.object({ event: z.literal('approval'), data: Loose }),
     z.object({ event: z.literal('clarify'), data: Loose }),
     z.object({ event: z.literal('clarify_resolved'), data: Loose }),
+    /** TAL-818: a `manage_connections` card opened; `tool_call_id` is the call that opened it. */
+    z.object({ event: z.literal('connection'), data: ConnectorOperationSnapshotSchema }),
     /** The Agent stopped waiting on an approval: `reason` is its settle cause (`resolved`, `timeout`, `interrupted`, `session_closed`). */
     z.object({ event: z.literal('approval_resolved'), data: z.looseObject({ approval_id: z.string(), session_id: z.string().optional(), reason: z.string().optional() }) }),
     z.object({ event: z.literal('compressing'), data: Loose }),
+    /** TAL-1006: the Agent finished the compaction the last `compressing` started; an aborted one sends none. */
+    z.object({ event: z.literal('compression_finished'), data: Loose }),
     z.object({ event: z.literal('warning'), data: Loose }),
     z.object({ event: z.literal('status'), data: Loose }),
+    /**
+     * TAL-803: the Agent's `AgentNotice` (`kind` `sticky` or `ttl`, `ttl_ms` only for `ttl`), the clear of one by `key`, and
+     * `notices_reset` before a new agent for the session is built: the notices of the one it replaces with
+     * `lapses_with_agent` lapse (an Agent startup warning, raised once per process, does not).
+     */
+    z.object({ event: z.literal('notice'), data: z.looseObject({ id: z.string().nullable().optional(), key: z.string().nullable().optional(), level: z.string(), kind: z.string(), ttl_ms: z.number().int().nullable().optional(), text: z.string(), lapses_with_agent: z.boolean().optional() }) }),
+    z.object({ event: z.literal('notice_clear'), data: z.looseObject({ key: z.string() }) }),
+    z.object({ event: z.literal('notices_reset'), data: Loose }),
+    z.object({ event: z.literal('provider_phase'), data: z.object({ phase: ProviderPhaseSchema.nullable() }) }),
+    /** TAL-821: the Agent's live rate-limit wait (`until`, epoch seconds: the limit's reset or the Agent's retry, as `until_kind` says); a null `until` ends it. */
+    z.object({ event: z.literal('rate_limit_wait'), data: z.looseObject({ provider: z.string().nullable(), until: z.number().nullable(), until_kind: z.enum(['reset', 'retry']).optional() }) }),
 ]);
 export const CHAT_METHODS = {
     'chat.start': {
@@ -343,6 +578,14 @@ export const CHAT_METHODS = {
             persist_user_message: z.string().optional(),
             /** TAL-529: a `/btw` side question, whose throwaway session the Agent keeps out of the profile's state.db. */
             ephemeral: z.boolean().optional(),
+            /** TAL-801: a spoken turn, which the Agent runs on the profile's `auxiliary.voice_chat` slot when it has that route. */
+            voice_turn: z.boolean().optional(),
+            /** TAL-818: attach the Agent's `connection_callback`, so `manage_connections` streams a `connection` frame and waits on the card. */
+            connect_card: z.boolean().optional(),
+            /** Bind turn-local skill capture only for a client that renders the masked prompt. */
+            skill_secret: z.boolean().optional(),
+            /** TAL-903: `workspace` is a host path (the profile's terminal runs locally), so the Agent anchors AGENTS.md discovery and its memory provider there. A remote backend's target-side path is never read on the host. */
+            workspace_local: z.boolean().optional(),
         }),
         result: ChatStartResultSchema,
         stream: ChatStreamSchema,
@@ -362,11 +605,11 @@ export const CHAT_METHODS = {
     /**
      * TAL-424: deliver `pending[index]` now with the Agent's `redirect`: `delivery: redirect` restarts the model request with
      * it, `delivery: steer` puts it last on the slot while tools yield. Not redirected: it stays pending, `requeued` in its
-     * place (`kept`) or last (`last`); `withdrawn: false` when the Agent already took it.
+     * place (`kept`) or last (`last`); `withdrawn: false` when the Agent already took it, or `reason: not_running` when the run or Agent is absent.
      */
     'chat.steer_now': {
         params: z.object({ stream_id: z.string().optional(), session_id: z.string().optional(), pending: z.array(z.string().min(1)).min(1), index: z.number().int().nonnegative() }),
-        result: z.object({ redirected: z.boolean(), withdrawn: z.boolean(), delivery: z.enum(['redirect', 'steer']).optional(), requeued: z.enum(['kept', 'last']).optional() }),
+        result: z.object({ redirected: z.boolean(), withdrawn: z.boolean(), delivery: z.enum(['redirect', 'steer']).optional(), requeued: z.enum(['kept', 'last']).optional(), reason: z.enum(['not_running']).optional() }),
     },
     /**
      * TAL-255: manual `/compress` of `conversation_history` through the Agent's `compress_now` on a throwaway agent. Nothing is
@@ -387,20 +630,44 @@ export const CHAT_METHODS = {
     },
     /** 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()) }) },
     '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() }) },
+    /**
+     * TAL-902: `/refine [focus]`, the Agent's on-demand memory/skill review of `messages` (the session's model context) on the
+     * session's cached agent, else one built from the turn parameters and cached like a turn's. `output` is the Agent's
+     * wording: the review started, or why not (a turn is running, the conversation is empty).
+     */
+    'chat.refine': {
+        params: ProfileHomeParams.extend({
+            session_id: z.string().min(1), messages: z.array(Loose), focus: z.string(), model: z.string(), model_provider: z.string().nullable().optional(),
+            enabled_toolsets: z.array(z.string()).nullable().optional(), max_iterations: z.number().int().nullable().optional(), max_tokens: z.number().int().nullable().optional(),
+            reasoning_config: z.object({ enabled: z.boolean(), effort: z.string().optional() }).nullable().optional(),
+            /** TAL-903: the session's workspace, as `chat.start` sends it, so the agent built here is the one its next turn reuses. */
+            workspace: z.string().optional(), workspace_local: z.boolean().optional(),
+        }),
+        result: z.object({ output: z.string() }),
+    },
     'approval.respond': { params: ProfileHomeParams.extend({ session_id: z.string().min(1), choice: z.enum(['once', 'session', 'always', 'deny']), request_id: z.string().nullable().optional() }), result: z.object({ ok: z.boolean(), resolved: z.number().int(), choice: z.string() }) },
     'approval.pending': { params: z.object({ session_id: z.string().min(1) }), result: z.object({ pending: z.array(Loose) }) },
     '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().min(1) }), result: z.object({ ok: z.boolean(), clarify_id: z.string().optional() }) },
+    '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() });
-/** A lifecycle run of `hermes gateway <action>`. `busy` means another action holds the lock; `timed_out` marks a child killed after `background_wait_seconds`. `detail` is CLI output, never shown to a browser. */
-const GatewayActionResult = z.object({ status: z.enum(['completed', 'failed', 'busy']), message: z.string(), detail: z.string().optional(), returncode: z.number().int().optional(), timed_out: z.boolean().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
+ * 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 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.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. */
+    'gateway.mode': { params: ProfileHomeParams.extend({ name: z.string().min(1), is_default: z.boolean() }), result: z.object({ gateway_mode: GatewayModeSchema }) },
 };
 //# sourceMappingURL=namespaces.js.map