@maudecode/talaria-web-contracts 1.19.0 → 1.21.0

package/dist/views.js

@@ -1,3 +1,4 @@
+import { McpCostPolicySchema } from './mcp-cost-policy.js';
 /**
  * Pinned response shapes shared by every consumer (formerly the frontend's
  * hand-written `src/contracts/*` schemas). Known fields are typed; every
@@ -5,11 +6,12 @@
  * that must survive a round trip (documented passthrough).
  */
 import { z } from 'zod';
+import { OutboundDraftRefSchema } from './outbound-drafts.js';
 import { RunStatusSchema } from './run-status.js';
-import { AgentRefreshConfirmationSchema } from './sidecar/runtime.js';
+import { AgentRefreshConfirmationSchema, AgentUpdateOperationSchema } from './sidecar/runtime.js';
 import { SpeedTierSchema } from './speed.js';
-import { OwnerAttachmentSchema } from './gateway-session.js';
-import { CanonicalBotChatSchema, GatewayModeSchema, PluginSettingFieldSchema, SkillCatalogIdentitySchema } from './sidecar/namespaces.js';
+import { ExecutionModeSchema, OwnerAttachmentSchema, MessageReactionViewSchema } from './gateway-session.js';
+import { KanbanInspectionNodeSchema, KanbanInspectionSnapshotSchema, CanonicalBotChatSchema, GatewayModeSchema, PluginOAuthClientSchema, PluginSettingFieldSchema, SkillCatalogIdentitySchema } from './sidecar/namespaces.js';
 export { SpeedTierSchema } from './speed.js';
 const Json = z.unknown();
 export const NullableString = z.string().nullable();
@@ -43,15 +45,20 @@ export const DiffHunkSchema = z.object({
  * that diff parsed (TAL-604). Absent on a call whose result has no diff.
  */
 export const ToolEditDiffSchema = z.object({ added: z.number().int(), removed: z.number().int(), diff: z.string(), truncated: z.boolean(), hunks: z.array(DiffHunkSchema) });
-/** Server-derived display fields every tool call carries: the kind, and the redacted first-line label of its main argument (`''` when none; omitted on a live frame with none, which keeps its start frame's target), and a file edit's `edit_diff`. */
-export const ToolDisplayFields = { kind: ToolKindSchema.optional(), target: z.string().optional(), edit_diff: ToolEditDiffSchema.optional() };
+/** The latest server-normalized MCP update; never stored with the transcript. */
+export const ToolProgressSchema = z.object({ percent: z.number().min(0).max(100).nullable(), message: z.string().nullable() });
+/** Shared tool display fields. Progress is ephemeral, absent on older servers and null after completion. */
+export const ToolDisplayFields = {
+    progress: ToolProgressSchema.nullable().optional(), kind: ToolKindSchema.optional(), target: z.string().optional(), edit_diff: ToolEditDiffSchema.optional(),
+    focus_path: NullableString.optional().describe('TAL-1458: a read or write call\'s file as a workspace-relative path, the file a companion page shows; absent for any other call or an absolute, home or out-of-workspace path.'),
+};
 /**
  * TAL-315: a tool result's display sections, decided by the server's one rule for live, replayed and persisted results
  * alike. Clients show `stdout`, `stderr`, a labelled `error` and a labelled `exit_code` (sent only when worth showing), or
  * `text`, in that order, and never parse result text. Each string is capped server-side; a client without the field
  * shows `preview`.
  */
-export const ToolResultViewSchema = z.object({ text: z.string().optional(), stdout: z.string().optional(), stderr: z.string().optional(), error: z.string().optional(), exit_code: z.number().int().optional() });
+export const ToolResultViewSchema = z.object({ outbound_draft: OutboundDraftRefSchema.optional(), text: z.string().optional(), stdout: z.string().optional(), stderr: z.string().optional(), error: z.string().optional(), exit_code: z.number().int().optional() });
 /**
  * Stored transcripts carry the OpenAI shape (`function.name` / `function.arguments` JSON string); live events carry `name` / `args`.
  * On an assistant row the server resolves every call (TAL-313, `session-sse-contract-v1.md`): Anthropic `tool_use` parts and
@@ -129,6 +136,7 @@ export const BackgroundLineSchema = z.object({ kind: z.enum(['agent', 'command',
 });
 export const MessageSchema = z.looseObject({
     role: z.string(), content: MessageContentSchema.optional(), id: MessageIdSchema.optional(), message_id: MessageIdSchema.optional(), timestamp: z.number().nullable().optional(),
+    reaction_view: MessageReactionViewSchema.optional(),
     attachments: z.array(AttachmentSchema).optional(), tool_calls: z.array(ToolCallSchema).optional(),
     /**
      * TAL-302: an assistant row's whole reasoning as one string (its reasoning fields, typed thinking parts and inline
@@ -286,8 +294,19 @@ export const CompressionReferenceSchema = z.object({
 });
 /** TAL-454: the chat a `/branch` copied, with its redacted title. */
 export const BranchedFromSchema = z.object({ session_id: SessionIdSchema, title: z.string() });
+export const MAX_SOURCE_REFERENCES = 5;
+export const SourceReferenceSchema = z.object({
+    session_id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/).describe('Retained logical conversation identity.'),
+    tip_session_id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),
+    profile: z.string().min(1).max(128),
+});
+export const AcceptedSourceReferenceSchema = SourceReferenceSchema.extend({ title: z.string() });
 /** Full session record from `GET /api/session` and mutations returning `session`. */
+export const SessionActivityPhaseSchema = z.enum(['starting', 'running', 'waiting_for_approval', 'waiting_for_input', 'completed', 'failed', 'cancelled', 'stale']);
 export const SessionSchema = z.looseObject({
+    activity_phase: SessionActivityPhaseSchema.optional(),
+    source_references: z.array(AcceptedSourceReferenceSchema).optional(),
+    context_detail_key: z.string().nullable().optional().describe('Opaque identity for open-only context details; changes with owner epoch, model and context.'),
     composer_state_key: z.string().optional().describe('Opaque profile-home and owner identity for device-local composer state; never an API session id.'),
     session_id: SessionIdSchema, title: z.string(), workspace: z.string().optional(), created_workspace: z.string().nullable().optional(), model: NullableString.optional(), model_provider: NullableString.optional(),
     model_option_id: NullableString.optional().describe('TAL-301: the catalog entry id the stored model/provider selects; null when none.'),
@@ -302,11 +321,14 @@ export const SessionSchema = z.looseObject({
     automatic_turns_held: z.boolean().optional().describe('TAL-899: the user pressed Stop, so no automatic turn (background wakeup or goal continuation) starts until their next message.'), has_pending_user_message: z.boolean().optional(),
     pending_user_message: NullableString.optional(), pending_attachments: z.array(AttachmentSchema).optional(), pending_started_at: NullableNumber.optional(), pending_user_source: NullableString.optional(),
     context_length: NullableNumber.optional(), threshold_tokens: NullableNumber.optional(), last_prompt_tokens: NullableNumber.optional(), post_compression_context_tokens_estimate: NullableNumber.optional(), ...ContextUsageFields,
+    execution_mode: ExecutionModeSchema.optional().describe('TAL-1040: the Agent execution policy frozen when the session was created; absent from older servers.'),
     enabled_toolsets: z.array(z.string()).nullable().optional(), composer_draft: ComposerDraftSchema.optional(), is_cli_session: z.boolean().optional(), source_kind: SourceKindSchema, is_messaging_session: IsMessagingSessionSchema, sort_ts: SortTsSchema, read_only: ReadOnlySchema, read_only_reason: ReadOnlyReasonSchema, owner_attachment: OwnerAttachmentSchema.optional(), can_branch: CanBranchSchema, can_pin: CanPinSchema, can_archive: CanArchiveSchema, can_delete: CanDeleteSchema, can_duplicate: CanDuplicateSchema, source_tag: NullableString.optional(),
     can_compress: z.boolean().optional().describe('TAL-614: a manual compression would start now: writable, no running turn, and at least four model-history messages. Only the full session detail carries it; absent means no.'),
     confirms_deep_truncate: z.boolean().optional().describe('TAL-929: this server holds a `session.truncate` that discards more than one user turn until it is confirmed; absent on older servers, which cut at once.'),
     source_label: NullableString.optional(), session_source: NullableString.optional(), raw_source: NullableString.optional(), parent_session_id: NullableString.optional(), worktree_path: NullableString.optional(),
-    worktree_branch: NullableString.optional(), worktree_repo_root: NullableString.optional(), share_token: NullableString.optional(), share_url: NullableString.optional(), share_created_at: NullableNumber.optional(), manual_title: z.boolean().optional(),
+    worktree_branch: NullableString.optional(), worktree_repo_root: NullableString.optional(),
+    worktree_retained: z.literal(true).optional().describe('TAL-1254: the last sidecar start found this worktree gone from git; the Agent\'s sweep keeps an archived one under `refs/hermes/archive/`. Absent while the worktree exists.'),
+    share_token: NullableString.optional(), share_url: NullableString.optional(), share_created_at: NullableNumber.optional(), manual_title: z.boolean().optional(),
     compression_anchor_summary: NullableString.optional(), compression_recovery: z.record(z.string(), Json).optional(), recommended_recovery_action: NullableString.optional(), compression_recovery_action: NullableString.optional(),
     compression_recovery_source_session_id: NullableString.optional(), gateway_routing: Json.optional(), _messages_offset: z.number().optional(), _messages_truncated: z.boolean().optional(), _msg_limit_max: z.number().optional(), _load_revision: z.string().optional(),
     /**
@@ -319,6 +341,7 @@ export const SessionSchema = z.looseObject({
     assistant_name: z.string().optional(),
     workspace_name: WorkspaceNameSchema,
     compression_reference: CompressionReferenceSchema.nullable().optional(),
+    focus_path: NullableString.optional().describe('TAL-1458: the last non-null `focus_path` of the session\'s persisted tool calls, so a reopened chat shows its file before any stream event; null when none.'),
     branched_from: BranchedFromSchema.nullable().optional().describe('TAL-454: the chat this one was branched from while it still loads (archived included); null for a compression continuation, a deleted or missing parent, and every other chat.'),
 });
 export const SessionEnvelopeSchema = z.looseObject({ session: SessionSchema });
@@ -349,6 +372,7 @@ export const SessionsListSchema = z.looseObject({
     archived_limit: z.number().int().nullable().optional(), archived_offset: z.number().int().optional(),
 });
 export const SessionStatusSchema = z.looseObject({
+    activity_phase: SessionActivityPhaseSchema.optional(),
     session_id: SessionIdSchema, title: z.string().optional(), active_stream_id: ActiveStreamIdSchema, active_turn_origin: ActiveTurnOriginSchema, agent_running: IsStreamingSchema, is_streaming: IsStreamingSchema, read_only: ReadOnlySchema, read_only_reason: ReadOnlyReasonSchema, owner_attachment: OwnerAttachmentSchema.optional(), message_count: z.number().optional(), model: NullableString.optional(),
     profile: NullableString.optional(), workspace: z.string().optional(), input_tokens: z.number().optional(), output_tokens: z.number().optional(), total_tokens: z.number().optional(), estimated_cost: NullableNumber.optional(), updated_at: UnixSeconds.optional(),
 });
@@ -379,7 +403,7 @@ export const ChatStartResponseSchema = z.looseObject({
  * stream's session: this run while it unwinds after a Stop, or a successor such as a goal continuation. A session delete
  * answers 409 while it is set, so a client draining a session before deleting it waits until it is null.
  */
-export const StreamStatusSchema = z.looseObject({ active: z.boolean(), stream_id: z.string(), replay_available: z.boolean().optional(), journal: Json.optional(), blocking_stream_id: z.string().nullable() });
+export const StreamStatusSchema = z.looseObject({ activity_phase: SessionActivityPhaseSchema.optional(), active: z.boolean(), stream_id: z.string(), replay_available: z.boolean().optional(), journal: Json.optional(), blocking_stream_id: z.string().nullable() });
 /**
  * TAL-424: a pending steer is no longer pending without the Agent taking it: Edit and Cancel by the user, `stopped` by a
  * Stop (`text` goes back to the composer), or `followup` when the server sends it as the next turn. `steer_id` is null
@@ -390,7 +414,7 @@ export const SteerWithdrawnSchema = z.object({ steer_id: z.string().nullable(),
  * `withdrawn_steers` (TAL-426): the steers this Stop withdrew, the same `steer_withdrawn` (stopped) the stream carries, so
  * a client that stops reading the stream once the Stop answers still gives its own text back.
  */
-export const CancelResponseSchema = z.looseObject({ ok: z.boolean(), cancelled: z.boolean(), stream_id: z.string().optional(), withdrawn_steers: z.array(SteerWithdrawnSchema).optional(), error: z.string().optional() });
+export const CancelResponseSchema = z.looseObject({ activity_phase: SessionActivityPhaseSchema.optional(), ok: z.boolean(), cancelled: z.boolean(), stream_id: z.string().optional(), withdrawn_steers: z.array(SteerWithdrawnSchema).optional(), error: z.string().optional() });
 export const SteerWithdrawRequestSchema = z.object({ session_id: SessionIdSchema, steer_id: z.string().min(1), reason: z.enum(['edit', 'cancel']) });
 /** `withdrawn: false` when the steer is unknown, already taken by the Agent (it then settles as consumed), or being sent. */
 export const SteerWithdrawResponseSchema = z.object({ withdrawn: z.boolean(), text: z.string().optional() });
@@ -413,7 +437,8 @@ export const ApprovalRespondRequestSchema = z.looseObject({ session_id: SessionI
 export const ApprovalRespondResponseSchema = z.looseObject({ ok: z.boolean(), choice: z.string().optional(), yolo_enabled: z.boolean().optional(), stale_cleared: z.boolean().optional(), error: z.string().optional(), pending_count: z.number().optional() });
 export const ClarifyChoiceSchema = z.union([z.string(), z.looseObject({ label: z.string().optional(), value: z.string().optional(), text: z.string().optional() })]);
 /** One question the client asks, in server order; answers are keyed by `qid`. A single-question prompt is one `q0` step. */
-export const ClarifyStepSchema = z.looseObject({ qid: z.string(), question: z.string(), choices: z.array(z.string()), multi_select: z.boolean() });
+export const ClarifyStepSchema = z.looseObject({ qid: z.string(), question: z.string(), choices: z.array(z.string()), multi_select: z.boolean(),
+    answered: z.boolean().optional().describe('TAL-1271: a gateway-owned batch question the owner already holds an answer for; it stays editable until the last answer.') });
 /** Keyed step answers; a multi-select step takes a list. The server shapes them into the Agent's reply. */
 export const ClarifyAnswersSchema = z.record(z.string(), z.union([z.string(), z.array(z.string())]));
 /** TAL-887: one input of a password-manager prompt, answered under its `key`; a `secure` input is masked. */
@@ -477,6 +502,8 @@ export const BackgroundTaskSchema = z.object({
     agents: BackgroundLinkSchema.shape.agents.nullable(),
     pinned: z.boolean(),
     dismissible: z.boolean(),
+    /** TAL-1172: confirmed running work this session may stop. */
+    can_stop: z.boolean().optional(),
     active: z.boolean(),
 });
 /**
@@ -484,17 +511,25 @@ export const BackgroundTaskSchema = z.object({
  * result. `agents_working` (TAL-373): a delegation is running or needs attention, whatever `kind` the list is narrowed to;
  * the chat's side panel opens on Agents for it. Absent from servers before TAL-373.
  */
-export const BackgroundTasksResponseSchema = z.object({ session_id: z.string(), tasks: z.array(BackgroundTaskSchema), agent_available: z.boolean(), agents_working: z.boolean().optional() });
+export const BackgroundTasksResponseSchema = z.object({ activity_phase: SessionActivityPhaseSchema.optional(), session_id: z.string(), tasks: z.array(BackgroundTaskSchema), agent_available: z.boolean(), agents_working: z.boolean().optional() });
 export const BackgroundTaskResultSchema = z.object({ task_id: z.string(), text: z.string() });
 export const BackgroundDismissRequestSchema = z.object({ session_id: SessionIdSchema, task_id: z.string().min(1) });
+export const BackgroundStopResponseSchema = z.object({ outcome: z.enum(['stopped', 'not_running', 'not_found']) });
 export const BackgroundDismissResponseSchema = z.object({ ok: z.literal(true), task: BackgroundTaskSchema });
 export const ShareCreateResponseSchema = z.looseObject({ ok: z.literal(true), share: z.looseObject({ token: z.string(), url: z.string(), title: z.string(), message_count: z.number().int(), created_at: z.number(), updated_at: z.number() }), session: SessionRowSchema });
 export const ShareMessageSchema = z.looseObject({ role: z.string(), content: z.union([z.string(), z.null(), z.array(Json)]).optional() });
 export const ShareSchema = z.looseObject({ title: z.string(), messages: z.array(ShareMessageSchema), message_count: z.number().int(), created_at: z.number().optional(), updated_at: z.number().optional(), model: NullableString.optional() });
 export const ShareReadSchema = z.looseObject({ share: ShareSchema });
+export const SourceReferenceSearchSchema = z.object({
+    sessions: z.array(SessionRowSchema.extend({ source_reference: SourceReferenceSchema })),
+    active_profile: z.string(), max_sources: z.number().int(),
+});
 export const SessionNewRequestSchema = z.looseObject({
     title: z.string().optional(), workspace: z.string().optional(), workspace_inherited_from_prev_session: z.boolean().optional(), model: z.string().nullable().optional(), model_provider: z.string().nullable().optional(),
     profile: z.string().nullable().optional(), prev_session_id: z.string().optional(), project_id: z.string().nullable().optional(), worktree: Json.optional(), enabled_toolsets: z.array(z.string()).nullable().optional(), parent_session_id: z.string().optional(),
+    execution_mode: ExecutionModeSchema.optional().describe('TAL-1040: `ignore_config` and `safe` start the session through the Agent owner; omitted means normal.'),
+    request_id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/).optional().describe('TAL-1040: stable creation identity for a diagnostic or referenced chat. Reuse it only to retry the same creation.'),
+    source_references: z.array(SourceReferenceSchema).max(MAX_SOURCE_REFERENCES).optional().describe('Same-profile search pointers. Nonempty selections require request_id; unavailable or changed identities refuse creation.'),
 });
 /**
  * `streaming` (TAL-802): live dictation over `TRANSCRIBE_STREAM_PATH` would open for this profile (`stt.streaming` on, a live provider wire).
@@ -541,7 +576,7 @@ export const ProfilesSchema = z.looseObject({ profiles: z.array(ProfileSchema),
 export const ActiveProfileSchema = z.looseObject({ name: z.string(), path: z.string().optional(), is_default: z.boolean().optional(), default_workspace: NullableString.optional() });
 export const ProfileSwitchSchema = ProfilesSchema.extend({ is_default: z.boolean(), default_model: Json, default_model_provider: Json, default_workspace: z.string().nullable() });
 /** `/api/reasoning`: config.yaml agent.reasoning_effort / display.show_reasoning, resolved for a model. */
-export const ReasoningStatusSchema = z.looseObject({ show_reasoning: z.boolean().optional(), reasoning_effort: z.string().nullable().optional(), supported_efforts: z.array(z.string()).optional(), supports_reasoning_effort: z.boolean().optional(), supports_thinking_toggle: z.boolean().optional() });
+export const ReasoningStatusSchema = z.looseObject({ show_reasoning: z.boolean().optional(), reasoning_effort: z.string().nullable().optional(), supported_efforts: z.array(z.string()).optional(), supports_reasoning_effort: z.boolean().optional(), supports_thinking_toggle: z.boolean().optional(), supports_session_scope: z.boolean().optional() });
 export const QuotaLevelSchema = z.enum(['healthy', 'warning', 'critical', 'stale', 'unavailable']);
 /**
  * TAL-301: `provider_id`/`bare_id` are the server's split of `id`; clients match a stored `(model, provider)` against them and send `id` back.
@@ -676,15 +711,17 @@ export const MaxTokensSchema = z.looseObject({ max_tokens: NullableNumber, max_t
 export const WorkspaceEntrySchema = z.looseObject({ name: z.string().min(1), path: z.string() });
 export const WorkspacesSchema = z.looseObject({ workspaces: z.array(WorkspaceEntrySchema), last: NullableString.optional(), terminal_remote_backend: z.boolean().optional() });
 export const FileEntrySchema = z.looseObject({
-    name: z.string(), path: z.string().optional(), is_dir: z.boolean().optional(), type: z.string().optional(), size: z.number().nullable().optional(), mtime: z.number().nullable().optional(), mtime_ns: z.union([z.number(), z.string()]).nullable().optional(),
+    read_only: z.boolean().optional(), name: z.string(), path: z.string().optional(), is_dir: z.boolean().optional(), type: z.string().optional(), size: z.number().nullable().optional(), mtime: z.number().nullable().optional(), mtime_ns: z.union([z.number(), z.string()]).nullable().optional(),
     birthtime_ns: z.union([z.number(), z.string()]).nullable().optional(), hidden: z.boolean().optional(), workspace_sort_rank: z.number().int().optional(), target: z.string().optional(), target_outside_workspace: z.boolean().optional(),
 });
-export const DirListingSchema = z.looseObject({ path: z.string().optional(), entries: z.array(FileEntrySchema), signature: z.string().optional(), workspace: z.string().optional(), workspace_recovered: z.boolean().optional(), is_git: z.boolean().optional() });
+export const FileSourceSchema = z.enum(['workspace', 'managed']);
+const ManagedFileFields = { source: FileSourceSchema.optional(), read_only: z.boolean().optional(), write_semantics: z.literal('unconditional').optional() };
+export const DirListingSchema = z.looseObject({ ...ManagedFileFields, unavailable: z.boolean().optional(), path: z.string().optional(), entries: z.array(FileEntrySchema), signature: z.string().optional(), workspace: z.string().optional(), workspace_recovered: z.boolean().optional(), is_git: z.boolean().optional() });
 /** How a workspace file renders (TAL-566): media streams from `/api/file/raw`; text kinds carry `content`. */
 export const FilePreviewKindSchema = z.enum(['text', 'markdown', 'csv', 'html', 'image', 'pdf', 'audio', 'video', 'binary']);
 /** `table` is a `csv` preview's leading rows (header first); `table_truncated` says the file has more. `preview_url` is an
  * `html` preview's app-relative frame URL, under which the page's relative assets also resolve. */
-export const FileContentSchema = z.looseObject({
+export const FileContentSchema = z.looseObject({ ...ManagedFileFields, name: z.string().optional(),
     path: z.string().optional(), content: z.string().optional(), lines: z.number().optional(), size: z.number().optional(), truncated: z.boolean().optional(), binary: z.boolean().optional(), mime: z.string().optional(),
     preview: FilePreviewKindSchema.optional(), table: z.array(z.array(z.string())).optional(), table_truncated: z.boolean().optional(),
     preview_url: z.string().optional(),
@@ -806,7 +843,7 @@ export const UpdateTargetSchema = z.looseObject({
     versions: z.array(UpdateVersionSchema).describe('TAL-946: every installable Stable release newer than the installed one, newest first; empty unless `release_ready` can apply.'),
     folded_count: z.number().int().nonnegative().describe('How many `versions` are `folded`.'),
 });
-export const AgentRecoveryStateSchema = z.object({ phase: z.enum(['idle', 'running', 'waiting', 'complete', 'blocked']), attempt: z.number().int().nonnegative(), detail: z.string(), retry_at: z.string().nullable() });
+export const AgentRecoveryStateSchema = z.object({ phase: z.enum(['idle', 'running', 'waiting', 'complete', 'blocked']), attempt: z.number().int().nonnegative(), detail: z.string(), retry_at: z.string().nullable(), operation_id: z.uuid().optional(), operation: AgentUpdateOperationSchema.optional(), verified_revision: z.string().regex(/^[a-f0-9]{40}$/).optional(), runtime_revision: z.string().regex(/^[a-f0-9]{40}$/).optional(), verified_version: z.string().nullable().optional() });
 export const UpdatesCheckSchema = z.looseObject({ agent_recovery: AgentRecoveryStateSchema.optional(), disabled: z.boolean().optional(), cached: z.boolean().optional(), channel: z.string().optional(), agent_channel: z.enum(['stable', 'experimental']).optional(), checked_at: z.number().optional(), include_agent: z.boolean().optional(), webui: UpdateTargetSchema.nullable().optional(), agent: UpdateTargetSchema.nullable().optional() });
 export const UpdatesSummarySchema = z.object({
     ok: z.boolean(), target: z.enum(['webui', 'agent']), summary: z.string(),
@@ -818,11 +855,15 @@ export const UpdatesSummarySchema = z.object({
     cached: z.boolean(),
 });
 export const UpdateApplySchema = z.looseObject({
+    recovery_only: z.boolean().optional().describe('Only a retained transaction was repaired; the selected update outcome remains unverified.'),
+    recovery_pending: z.boolean().optional().describe('The initiating operation remains active through automatic recovery; follow its notification_id without replaying the update.'),
+    verified_revision: z.string().regex(/^[a-f0-9]{40}$/).optional(), verified_version: z.string().nullable().optional(),
     recovery_compatibility: z.object({ manual_execution: z.boolean(), bot_chat_delivery: z.boolean() }).optional()
         .describe('Whether the target Agent can reconcile retained manual execution and pending Bot Chat records. A false value blocks the update before any source or repair-intent change.'),
     ok: z.boolean().optional(), status: z.string().optional(), error: z.string().optional(), message: z.string().optional(), lock: Json.optional(), confirmation_required: z.boolean().optional(), refresh_confirmation: AgentRefreshConfirmationSchema.optional(), candidate_revision: z.string().optional(), supported_revision: z.string().optional(), supported_version: z.string().optional(), agent_channel: z.enum(['stable', 'experimental']).optional(), notification_id: z.uuid().optional(), channel_switch: z.boolean().optional(), backup_dir: z.string().nullable().optional(), backup_failed: z.boolean().optional(), stash_conflict: z.boolean().optional(), gateway_restart: z.string().optional().describe('TAL-953: `waiting_for_idle` when an Agent update left the gateway restart to wait for the gateway\'s running work; the update notification reports its outcome.')
 });
-export const UpdateNotificationPhaseSchema = z.enum(['applying', 'awaiting_confirmation', 'waiting_for_idle', 'restarting', 'succeeded', 'blocked', 'failed', 'unknown']);
+/** `verifying` (TAL-1138): the gateway restarted, and the server is checking that the new gateway process and the Agent runtime answer. */
+export const UpdateNotificationPhaseSchema = z.enum(['applying', 'awaiting_confirmation', 'waiting_for_idle', 'restarting', 'verifying', 'recovering', 'succeeded', 'blocked', 'failed', 'unknown']);
 export const UpdateNotificationActionSchema = z.object({
     id: z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9_-]*$/),
     label: z.string().min(1).max(80),
@@ -833,6 +874,17 @@ export const UpdateNotificationDestinationSchema = z.object({
     key: z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9_.-]*$/),
     label: z.string().min(1).max(80),
 });
+/** TAL-1138: one step of an update as its Updating dialog lists it; the server derives every label and state. */
+export const UpdateStepSchema = z.object({
+    id: z.enum(['install', 'web_restart', 'ready', 'gateway_wait', 'gateway_restart', 'agent_ready', 'recovery']),
+    label: z.string().min(1).max(80),
+    state: z.enum(['done', 'active', 'pending', 'failed']),
+});
+export const AgentUpdateRecoverySchema = z.object({
+    operation: AgentUpdateOperationSchema, attempt_error: z.string().max(2000).nullable(), runtime_revision: z.string().regex(/^[a-f0-9]{40}$/).nullable(),
+    rollback: z.boolean().nullable().optional(),
+    outcome: z.enum(['recovering', 'target_installed', 'baseline_restored', 'other_revision', 'blocked', 'unknown']),
+});
 export const UpdateNotificationSchema = z.object({
     id: z.uuid(),
     kind: z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9_-]*$/),
@@ -854,10 +906,17 @@ export const UpdateNotificationSchema = z.object({
     verified_version: z.string().min(1).max(80).nullable(),
     /** The apply's own explanation of a failed or blocked attempt, or of a success that needs attention (an Agent update that kept local edits in the git stash), line breaks kept; null otherwise. */
     detail: z.string().max(2000).nullable(),
+    recovery: AgentUpdateRecoverySchema.optional(),
     unread: z.boolean(),
     active: z.boolean(),
     requires_interaction: z.boolean(),
     can_dismiss: z.boolean(),
+    /** TAL-1138: the update's steps in order; empty for records that are not updates. */
+    steps: z.array(UpdateStepSchema).max(8),
+    /** TAL-1138: every client that sees this record opens its Updating dialog, which cannot be closed while this holds. */
+    presents_dialog: z.boolean(),
+    /** TAL-1138: how an open Updating dialog for this record closes: not at all, with Close, with Restart later (the wait goes on), or by itself after showing the outcome. */
+    dialog_close: z.enum(['none', 'close', 'restart_later', 'auto']),
 });
 export const FrontendBuildIdSchema = z.string().regex(/^[a-f0-9]{64}$/);
 export const TabIdSchema = z.string().regex(/^[A-Za-z0-9_-]{8,64}$/);
@@ -882,16 +941,26 @@ export const UpdateNotificationsSchema = z.object({
 });
 /** TAL-806: a plugin setting as Settings shows it; `locked` marks a secret the server's launch environment supplies, so an edit would not take effect. */
 export const PluginSettingViewSchema = PluginSettingFieldSchema.extend({ locked: z.boolean().optional() });
+/** TAL-1276: a plugin OAuth client as Settings shows it; `can_sign_out` is true while the profile stores a grant for it (any state but `logged_out`). */
+export const PluginOAuthClientViewSchema = PluginOAuthClientSchema.extend({ can_sign_out: z.boolean() });
 export const PluginSchema = z.looseObject({ key: z.string(), name: z.string().optional(), kind: z.string().optional(), enabled: z.boolean().optional(), description: z.string().optional(), version: z.string().optional(), activation: z.string().optional(), is_active_provider: z.boolean().optional(), hooks: z.array(Json).optional(),
+    /** Stored Agent check, absent when the installed Agent lacks cached update support. */
+    update: z.object({ available: z.boolean(), latest_revision: z.string().optional() }).optional(),
     /** TAL-806: the manifest's `config_schema` fields with current values; absent when the plugin declares none. */
-    settings: z.array(PluginSettingViewSchema).optional() });
+    settings: z.array(PluginSettingViewSchema).optional(),
+    /**
+     * TAL-1276: the OAuth clients the manifest declares (Agent v0.22.3+), each with its sign-in state and the two hosts the
+     * sign-in sends the code to. Sign in through `/api/onboarding/oauth/start` with provider `plugin:<key>:<id>`; absent
+     * when the plugin declares none or the Agent cannot sign in to plugin clients.
+     */
+    oauth_clients: z.array(PluginOAuthClientViewSchema).optional() });
 /**
  * `read_only` (TAL-806): this session may not save plugin `settings` (not the server owner, or no sidecar).
  * `plugin_isolation_advisory` (TAL-820): more than one profile has third-party plugins installed and one of those runs them
  * `in_process`, so Settings recommends `plugins.isolation: host`; Talaria never sets the mode.
  */
 export const PluginsSchema = z.looseObject({ plugins: z.array(PluginSchema), empty: z.boolean().optional(), read_only: z.boolean().optional(), supported_hooks: z.array(z.string()).optional(), unavailable: z.boolean().optional(), plugin_isolation_advisory: z.boolean().optional() });
-export const McpServerSchema = z.looseObject({ name: z.string(), id: z.string().optional(), transport: z.string().optional(), enabled: z.boolean().optional(), can_toggle: z.boolean().optional().describe('Whether PATCH can enable or disable this server; false for invalid config.'), active: z.boolean().optional(), status: z.string().optional(), tools: z.number().optional(), tool_count: z.number().int().nullable().optional(), health: z.string().optional(), health_detail: z.string().optional(), health_checked_at: Json.optional(), health_pending: z.boolean().optional() });
+export const McpServerSchema = z.looseObject({ cost_policy: McpCostPolicySchema.nullable().optional(), name: z.string(), id: z.string().optional(), transport: z.string().optional(), enabled: z.boolean().optional(), can_toggle: z.boolean().optional().describe('Whether PATCH can enable or disable this server; false for invalid config.'), active: z.boolean().optional(), status: z.string().optional(), tools: z.number().optional(), tool_count: z.number().int().nullable().optional(), health: z.string().optional(), health_detail: z.string().optional(), health_checked_at: Json.optional(), health_pending: z.boolean().optional() });
 export const McpServersSchema = z.looseObject({ servers: z.array(McpServerSchema), health_pending: z.boolean().optional(), reload_required: z.boolean().optional(), toggle_supported: z.boolean().optional() });
 /** TAL-818: one connected account of a Nous tool-gateway app; `name` is its alias, else the vendor label. `problem` is its gateway status while it is not active, else null. */
 export const ConnectorAccountViewSchema = z.object({ connection_id: z.string(), name: z.string(), problem: z.enum(['pending', 'failed', 'expired', 'revoked', 'inactive']).nullable(), status_reason: z.string().nullable(), active: z.boolean(), created_at: z.string() });
@@ -907,9 +976,10 @@ export const ConnectorViewSchema = z.object({
 /**
  * TAL-818: the Connectors page. `available` is the Agent's connectors gate; false hides the page. `policy_revision` is the
  * member rules' revision every rule change sends back; null when the rules are read-only (no member layer, or unreadable),
- * so no switch changes them. `rules_error`: why the rules could not be read; every app then reads off (fails closed).
+ * so no switch changes them. `sign_in_required` offers Nous sign-in without creating a guest on reads.
+ * `rules_error`: why the rules could not be read; every app then reads off (fails closed).
  */
-export const ConnectorsPageSchema = z.object({ available: z.boolean(), connectors: z.array(ConnectorViewSchema), policy_revision: z.string().nullable(), rules_error: z.string().nullable() });
+export const ConnectorsPageSchema = z.object({ available: z.boolean(), sign_in_required: z.boolean().default(false), connectors: z.array(ConnectorViewSchema), policy_revision: z.string().nullable(), rules_error: z.string().nullable() });
 /**
  * TAL-818: one app's tools: `enabled`: Hermes may use it (the member rules leave it on and nothing locks it); `locked`: an
  * organization or role rule (by name or tag) keeps it off. `editable`: its switch may change the member rule (readable rules, the app on in them, and no lock).
@@ -968,6 +1038,13 @@ export const OnboardingProbeSchema = z.looseObject({ ok: z.boolean().optional(),
 export const OnboardingOAuthSchema = z.looseObject({
     ok: z.boolean().optional(), status: z.string().optional(), url: z.string().optional(), verification_url: z.string().optional(), user_code: z.string().optional(), message: z.string().optional(),
     error: z.string().nullable().optional(), flow_id: z.string().optional(), provider: z.string().optional(), expires_in: z.number().int().optional(), interval: z.number().int().optional(),
+    /**
+     * TAL-1276, a plugin client's browser sign-in (`plugin:<key>:<id>`, no `user_code`): `verification_url` is the
+     * authorize link, `authorize_host` and `token_host` the hosts the code goes to, and `redirect_uri` the address the
+     * browser is sent back to. When that address does not open on this machine, send the one the browser shows to
+     * `/api/plugins/oauth/redirect`.
+     */
+    authorize_host: z.string().optional(), token_host: z.string().optional(), redirect_uri: z.string().optional(),
 });
 // ── automation ───────────────────────────────────────────────────────────
 export const CronScheduleSchema = z.looseObject({ kind: z.string().optional(), expr: z.string().optional(), minutes: z.number().optional(), run_at: z.string().optional(), display: z.string().optional() });
@@ -1018,6 +1095,14 @@ export const KanbanTaskPolicyShape = { available_actions: KanbanTaskActionsSchem
 export const KanbanTaskViewSchema = z.looseObject({ id: z.union([z.string(), z.number()]), title: z.string().optional(), status: z.string().optional(), assignee: NullableString.optional(), priority: z.union([z.string(), z.number()]).nullable().optional(), description: z.string().optional(), tags: z.array(z.string()).optional(), session_id: NullableString.optional(), archived: z.boolean().optional(), created_at: Json.optional(), updated_at: Json.optional(), ...KanbanTaskPolicyShape });
 /** A board column in the Agent workflow's order (TAL-796): `name` is the status key, `label` the Agent's English label. */
 export const KanbanColumnSchema = z.looseObject({ name: z.string(), label: z.string(), tasks: z.array(KanbanTaskViewSchema) });
+/** One bounded profile-scoped read shared by timeline and relationship layouts. Null timing means unknown, never planned effort. */
+export const KanbanInspectionSchema = KanbanInspectionSnapshotSchema.extend({
+    nodes: z.array(KanbanInspectionNodeSchema.extend({ task: KanbanTaskViewSchema,
+        ancestors: z.array(z.string()), descendants: z.array(z.string()), cycle: z.boolean(), running_lineage: z.boolean(),
+        timing: z.object({ start: z.number().nullable(), end: z.number().nullable(), duration_seconds: z.number().nullable(), offset: z.number().nullable(), width: z.number().nullable() }),
+    })).max(500),
+    window: z.object({ start: z.number().nullable(), end: z.number().nullable() }),
+});
 /** One profile lane (TAL-567): an assignee's tasks (`null` = unassigned) across every board column, with its task count. */
 export const KanbanLaneSchema = z.object({ assignee: z.string().nullable(), count: z.number().int(), columns: z.array(KanbanColumnSchema) });
 export const KanbanBoardViewSchema = z.looseObject({ columns: z.array(KanbanColumnSchema).optional(), assignees: z.array(Json).optional(), filters: Json.optional(), latest_event_id: z.number().optional(), read_only: z.boolean().optional(), tenants: z.array(Json).optional(), changed: z.boolean().optional(),