@maudecode/talaria-web-contracts 1.19.0 → 1.20.0

package/dist/views.js

@@ -8,8 +8,8 @@ import { z } from 'zod';
 import { RunStatusSchema } from './run-status.js';
 import { AgentRefreshConfirmationSchema } 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 } from './gateway-session.js';
+import { 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,8 +43,10 @@ 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() };
 /**
  * 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
@@ -288,6 +290,7 @@ export const CompressionReferenceSchema = z.object({
 export const BranchedFromSchema = z.object({ session_id: SessionIdSchema, title: z.string() });
 /** Full session record from `GET /api/session` and mutations returning `session`. */
 export const SessionSchema = z.looseObject({
+    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 +305,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(),
     /**
@@ -413,7 +419,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 +484,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(),
 });
 /**
@@ -487,6 +496,7 @@ export const BackgroundTaskSchema = z.object({
 export const BackgroundTasksResponseSchema = z.object({ 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() });
@@ -495,6 +505,8 @@ export const ShareReadSchema = z.looseObject({ share: ShareSchema });
 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 chat. Reuse it only to retry the same creation.'),
 });
 /**
  * `streaming` (TAL-802): live dictation over `TRANSCRIBE_STREAM_PATH` would open for this profile (`stt.streaming` on, a live provider wire).
@@ -541,7 +553,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.
@@ -822,7 +834,8 @@ export const UpdateApplySchema = z.looseObject({
         .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', '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 +846,12 @@ 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']),
+    label: z.string().min(1).max(80),
+    state: z.enum(['done', 'active', 'pending', 'failed']),
+});
 export const UpdateNotificationSchema = z.object({
     id: z.uuid(),
     kind: z.string().min(1).max(64).regex(/^[a-z0-9][a-z0-9_-]*$/),
@@ -858,6 +877,12 @@ export const UpdateNotificationSchema = z.object({
     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,9 +907,19 @@ 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
@@ -907,9 +942,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 +1004,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() });