@nekro-nxt/contracts 0.4.0 → 0.5.0

package/src/host-api.ts

@@ -1,10 +1,21 @@
+import { CommandCatalogEntrySchema, CommandExecutionRecordSchema, CommandPolicySchema } from './commands.js'
 import { z } from 'zod'
+import {
+  hostLogDebugLeaseSchema,
+  hostLogDebugRequestSchema,
+  hostLogEntrySchema,
+  hostLogPageSchema,
+  hostLogSettingsSchema,
+  hostLogSourceSchema,
+  hostLogStatusSchema,
+} from './logs.js'
 import { McpServerFormSchema } from './extension-capabilities.js'
 import { HostUpgradeSummarySchema, RuntimeCompatibilityDiagnosticSchema } from './runtime-compatibility.js'
 import {
   AgentIdSchema,
   AgentRevisionIdSchema,
   AuthoringAttemptIdSchema,
+  SubConversationIdSchema,
   AuthoringTaskIdSchema,
   AssetIdSchema,
   ChannelEventIdSchema,
@@ -38,9 +49,8 @@ import {
   CommunityReleaseIdSchema,
   CommunityReviewStatusSchema,
   CommunityStatusSchema,
-  CommunitySourceSchema,
   CommunityEndpointSchema,
-  CommunityInstalledSchema,
+  CommunitySyncSchema,
   CommunityMyExtensionSchema,
   CommunityReviewReportSchema,
 } from './community.js'
@@ -101,6 +111,9 @@ const DynamicAttemptErrorSchema = z
     phase: z.enum(['approval', 'host-load', 'host-apply', 'client-load', 'client-apply', 'client-render']),
     message: z.string(),
     stack: z.string().optional(),
+    /** A render failure also names the contribution slot that failed and whether its frame gave up. */
+    slot: NonEmptyStringSchema.optional(),
+    abdicated: z.boolean().optional(),
     pluginId: DynamicIdSchema,
     packageId: DynamicIdSchema,
     pluginRunId: DynamicIdSchema,
@@ -131,6 +144,7 @@ const AuthoringTaskStatusSchema = z.enum([
   'interrupted',
   'stopped',
   'completed',
+  'paused',
 ])
 
 const AuthoringAttemptStateSchema = z.enum([
@@ -175,6 +189,8 @@ const AuthoringAttemptSummarySchema = z
       })
       .strict()
       .optional(),
+    /** Verified without loading its interface, because no browser was available; the interface itself is unchecked. */
+    uiUnverified: z.boolean().optional(),
     createdAt: z.number().int().nonnegative(),
     settledAt: z.number().int().nonnegative().optional(),
   })
@@ -189,6 +205,15 @@ const AuthoringTaskSummarySchema = z
     title: z.string(),
     requirementSummary: z.string(),
     status: AuthoringTaskStatusSchema,
+    /** `create` builds a new extension; `revise` changes `targetExtensionId` starting from `baseRevisionId`. */
+    kind: z.enum(['create', 'revise']).default('create'),
+    targetExtensionId: ExtensionIdSchema.optional(),
+    baseRevisionId: ExtensionRevisionIdSchema.optional(),
+    referenceRevisionId: ExtensionRevisionIdSchema.optional(),
+    /** Why the task is paused; it continues when the agent picks it up in a later conversation. */
+    pausedReason: z.string().optional(),
+    /** The conversation the task runs in is live, so its candidate can be previewed directly. */
+    live: z.boolean().default(false),
     approvalPolicy: z.enum(['risk-stable', 'fully-automatic']),
     approvedRiskDigest: z
       .string()
@@ -282,6 +307,20 @@ export const ImageUnderstandingPolicyApiSchema = z
   })
   .strict()
 
+export const CommandAccountServiceSchema = z.enum(['github'])
+export type CommandAccountService = z.output<typeof CommandAccountServiceSchema>
+
+export const CommandAccountUsageSchema = z.enum(['read', 'issues', 'pull-requests', 'push'])
+
+const CommandAccountGrantSchema = z
+  .object({
+    service: CommandAccountServiceSchema,
+    accountId: NonEmptyStringSchema.max(64),
+    /** Told to the agent as guidance, not enforced; empty gives no hint. */
+    usage: z.array(CommandAccountUsageSchema).max(4).default([]),
+  })
+  .strict()
+
 const AgentCapabilitiesSchema = z
   .object({
     subagents: z.boolean(),
@@ -296,12 +335,22 @@ const AgentCapabilitiesSchema = z
     codeRun: z.boolean().default(false),
     /** Network for commands; absent in older clients means on. */
     commandNetwork: z.boolean().default(true),
+    communityFeedbackAuto: z.boolean().default(false),
+    /** Accounts this agent's commands may act as; absent in older clients means none. */
+    commandAccounts: z.array(CommandAccountGrantSchema).max(8).default([]),
+    /**
+     * What the agent may do with extensions without the console: `manual` only develops and test-runs, `confirm` asks
+     * an administrator in the channel for every step, `autonomous` takes ordinary steps that only affect itself.
+     */
+    extensionAutonomy: z.enum(['manual', 'confirm', 'autonomous']).default('manual'),
+    /** Whose requests make the agent develop or change extensions: anyone in the channel, or administrators only. */
+    extensionRequesters: z.enum(['everyone', 'admins']).default('everyone'),
   })
   .strict()
 
 export const DynamicClientApprovalPolicySchema = z.enum(['manual', 'automatic'])
 
-export const NotificationEventKeySchema = z.enum(['dynamic-client-approval-requested'])
+export const NotificationEventKeySchema = z.enum(['dynamic-client-approval-requested', 'community-feedback-update'])
 export type NotificationEventKey = z.output<typeof NotificationEventKeySchema>
 
 export const NotificationSettingsViewSchema = z
@@ -315,7 +364,12 @@ export const NotificationSettingsViewSchema = z
         deviceKeyConfigured: z.boolean(),
       })
       .strict(),
-    events: z.record(NotificationEventKeySchema, z.boolean()),
+    events: z
+      .object({
+        'dynamic-client-approval-requested': z.boolean(),
+        'community-feedback-update': z.boolean().default(true),
+      })
+      .strict(),
   })
   .strict()
 
@@ -331,7 +385,9 @@ export const UpdateNotificationSettingsRequestSchema = z
         clearDeviceKey: z.boolean().optional(),
       })
       .strict(),
-    events: z.record(NotificationEventKeySchema, z.boolean()),
+    events: z
+      .object({ 'dynamic-client-approval-requested': z.boolean(), 'community-feedback-update': z.boolean().optional() })
+      .strict(),
   })
   .strict()
   .refine((value) => !(value.bark.deviceKey !== undefined && value.bark.clearDeviceKey === true), {
@@ -390,13 +446,17 @@ const ReviseAgentRequestSchema = AgentRevisionRequestContentSchema.extend({
   validatePersonaDocumentProjection(value, context)
 })
 
-// The defaults that fill `scheduledTasks`, `codeRun` and `commandNetwork` for older clients must not reset them in a
-// partial update.
+// Defaults that fill capabilities for older clients must not
+// reset them in a partial update.
 const UpdateAgentCapabilitiesRequestSchema = AgentCapabilitiesSchema.partial()
   .extend({
     scheduledTasks: z.boolean().optional(),
     codeRun: z.boolean().optional(),
     commandNetwork: z.boolean().optional(),
+    communityFeedbackAuto: z.boolean().optional(),
+    commandAccounts: z.array(CommandAccountGrantSchema).max(8).optional(),
+    extensionAutonomy: z.enum(['manual', 'confirm', 'autonomous']).optional(),
+    extensionRequesters: z.enum(['everyone', 'admins']).optional(),
   })
   .strict()
   .refine((value) => Object.values(value).some((entry) => entry !== undefined), '至少提供一个能力。')
@@ -418,7 +478,14 @@ const SnapshotMessagePartSchema = z.discriminatedUnion('type', [
   z
     .object({ type: z.literal('mention'), memberId: ChannelMemberIdSchema, displayName: z.string().optional() })
     .strict(),
-  z.object({ type: z.literal('image'), assetId: AssetIdSchema, alt: z.string().optional() }).strict(),
+  z
+    .object({
+      type: z.literal('image'),
+      assetId: AssetIdSchema,
+      alt: z.string().optional(),
+      sticker: z.literal(true).optional(),
+    })
+    .strict(),
   z.object({ type: z.literal('file'), assetId: AssetIdSchema, name: z.string().optional() }).strict(),
   z.object({ type: z.literal('audio'), assetId: AssetIdSchema }).strict(),
   z.object({ type: z.literal('quote'), messageId: LogicalMessageIdSchema }).strict(),
@@ -465,7 +532,10 @@ export const HostSnapshotMessageSchema = z
       })
       .strict()
       .optional(),
-    origin: z.enum(['admin-console']).optional(),
+    origin: z.enum(['admin-console', 'command', 'extension-notice']).optional(),
+    command: CommandExecutionRecordSchema.optional(),
+    /** A host notice about extension work: a request an administrator must confirm, or what an action did. */
+    extensionNotice: z.object({ requestNumber: z.number().int().positive().optional() }).strict().optional(),
     /** What the agent's inbound hooks decided for this message, when anything differs from the default. */
     inboundHook: z
       .object({
@@ -535,6 +605,8 @@ export const PlatformUserListResponseSchema = z
           activeChannelCount: z.number().int().nonnegative(),
           channelPreview: z.array(PlatformUserChannelPreviewSchema).max(3),
           historicalOnly: z.boolean(),
+          /** Listed in Settings → Administrators. */
+          administrator: z.boolean().default(false),
         })
         .strict(),
     ),
@@ -945,6 +1017,40 @@ export const DEFAULT_MESSAGE_PACING: MessagePacing = 'normal'
 
 export const MessagePacingSettingsSchema = z.object({ pacing: MessagePacingSchema }).strict()
 
+/**
+ * A conversation of its own under a channel's conversation (docs/NekroNxt界面交互模型.md §5.6): the agent opens one
+ * for a separate piece of work, and the host opens scripted ones to check creation candidates. It has its own log
+ * and context, and is shown under its channel.
+ */
+export const SubConversationSchema = z
+  .object({
+    id: SubConversationIdSchema,
+    channelId: ChannelIdSchema,
+    episodeId: EpisodeIdSchema,
+    agentId: AgentIdSchema,
+    title: z.string().min(1).max(200),
+    /** `agent`: the agent opened it with a tool; `host`: NekroNXT opened it, such as to check a candidate. */
+    openedBy: z.enum(['agent', 'host']),
+    /** `model`: the agent's model talks in it; `script`: the host plays fixed tool calls. */
+    driver: z.enum(['model', 'script']),
+    status: z.enum(['open', 'closed']),
+    closeReason: z.enum(['completed', 'closed-by-agent', 'closed-by-admin', 'failed', 'conversation-ended']).optional(),
+    /** What it handed back to the channel's conversation when it ended. */
+    summary: z.string().max(4000).optional(),
+    authoringTaskId: AuthoringTaskIdSchema.optional(),
+    createdAt: z.number().int().nonnegative(),
+    closedAt: z.number().int().nonnegative().optional(),
+  })
+  .strict()
+
+export type SubConversation = z.output<typeof SubConversationSchema>
+
+/** How long ended sub-conversations are kept before they are cleaned up. */
+export const SubConversationRetentionSchema = z.enum(['1d', '3d', '7d', '30d', 'never'])
+export type SubConversationRetention = z.output<typeof SubConversationRetentionSchema>
+export const DEFAULT_SUB_CONVERSATION_RETENTION: SubConversationRetention = '7d'
+export const SubConversationSettingsSchema = z.object({ retention: SubConversationRetentionSchema }).strict()
+
 /** `keyword`: SQLite keyword search only; `builtin`: keywords fused with the built-in semantic model. */
 export const RetrievalModeSchema = z.enum(['keyword', 'builtin'])
 export type RetrievalMode = z.output<typeof RetrievalModeSchema>
@@ -985,6 +1091,23 @@ export const RetrievalStatusSchema = z
   .strict()
 export type RetrievalStatus = z.output<typeof RetrievalStatusSchema>
 
+/** Where the Host keeps restore points it takes before an upgrade, or none. */
+export const UpgradeBackupModeSchema = z.enum(['data', 'directory', 'off'])
+export const UpgradeBackupSettingsSchema = z
+  .object({
+    mode: UpgradeBackupModeSchema,
+    /** The chosen directory when `mode` is `directory`. */
+    directory: z.string().nullable(),
+    /** Set through the server's environment; the settings page cannot change it. */
+    locked: z.boolean(),
+    /** Restore points kept; older ones are removed after an upgrade succeeds. */
+    keep: z.number().int().positive(),
+    /** Restore points currently in the chosen place. */
+    usage: z.object({ count: z.number().int().nonnegative(), bytes: z.number().int().nonnegative() }).strict(),
+  })
+  .strict()
+export type UpgradeBackupSettings = z.output<typeof UpgradeBackupSettingsSchema>
+
 /** What the agent keeps about individual members of one channel; each note comes with that member's messages. */
 export const ChannelMemberNotesViewSchema = z
   .object({
@@ -1145,11 +1268,13 @@ export const AttentionItemSchema = z
       'connection-unhealthy',
       'agent-model-unavailable',
       'agent-vision-unavailable',
+      'logs-unavailable',
+      'community-feedback',
     ]),
     severity: z.enum(['critical', 'warning', 'info']),
     subject: z
       .object({
-        kind: z.enum(['outbound', 'channel', 'authoring-task', 'connection', 'agent']),
+        kind: z.enum(['outbound', 'channel', 'authoring-task', 'connection', 'agent', 'logs', 'community-feedback']),
         id: NonEmptyStringSchema,
       })
       .strict(),
@@ -1166,7 +1291,15 @@ export const AttentionItemSchema = z
     detail: z.string().max(400),
     action: z
       .object({
-        kind: z.enum(['open-channel', 'resolve-delivery', 'open-authoring-task', 'open-connection', 'open-agent']),
+        kind: z.enum([
+          'open-channel',
+          'resolve-delivery',
+          'open-authoring-task',
+          'open-connection',
+          'open-agent',
+          'open-logs',
+          'open-community-feedback',
+        ]),
         label: z.string().min(1).max(40),
       })
       .strict(),
@@ -1311,8 +1444,85 @@ export const CodeRunAvailabilitySchema = z
 
 export type CodeRunAvailability = z.output<typeof CodeRunAvailabilitySchema>
 
+/** The GitHub CLI commands call: found on this machine, or downloaded by NekroNXT where it can. */
+export const GithubCliAvailabilitySchema = CodeRunAvailabilitySchema
+export type GithubCliAvailability = z.output<typeof GithubCliAvailabilitySchema>
+
+/** The optional headless Chromium that loads and checks creation candidates when no page is open. */
+export const VerificationBrowserAvailabilitySchema = CodeRunAvailabilitySchema
+export type VerificationBrowserAvailability = z.output<typeof VerificationBrowserAvailabilitySchema>
+
+/**
+ * One account in the host's library. The library only keeps accounts; an account takes effect only for the agents
+ * whose capabilities grant it, which `usedBy` lists.
+ */
+export const CommandAccountSchema = z
+  .object({
+    id: NonEmptyStringSchema.max(64),
+    service: CommandAccountServiceSchema,
+    /** The account name on the service. */
+    login: NonEmptyStringSchema,
+    source: z.enum(['token', 'gh-login']),
+    /** Token scopes where the service reports them (classic tokens); absent for fine-grained tokens. */
+    scopes: z.array(z.string()).optional(),
+    createdAt: z.number().int().nonnegative(),
+    usedBy: z.array(AgentIdSchema),
+  })
+  .strict()
+
+export type CommandAccount = z.output<typeof CommandAccountSchema>
+
+/** A login the local `gh` holds, offered as a quick way to add an account. */
+export const LocalGithubLoginSchema = z.object({ login: NonEmptyStringSchema, active: z.boolean() }).strict()
+
+export const CommandAccountsViewSchema = z
+  .object({
+    accounts: z.array(CommandAccountSchema),
+    /** Logins found in the local GitHub CLI; empty when it is missing or not logged in. */
+    localLogins: z.array(LocalGithubLoginSchema),
+  })
+  .strict()
+
+export type CommandAccountsView = z.output<typeof CommandAccountsViewSchema>
+
+export const AddCommandAccountRequestSchema = z.discriminatedUnion('source', [
+  z
+    .object({ source: z.literal('token'), service: CommandAccountServiceSchema, token: NonEmptyStringSchema.max(512) })
+    .strict(),
+  z
+    .object({
+      source: z.literal('gh-login'),
+      service: CommandAccountServiceSchema,
+      login: NonEmptyStringSchema.max(128),
+    })
+    .strict(),
+])
+
+export type AddCommandAccountRequest = z.output<typeof AddCommandAccountRequestSchema>
+
+/** An extension action an agent asked an administrator to confirm, or one it took on its own. */
+export const ExtensionRequestSchema = z
+  .object({
+    number: z.number().int().positive(),
+    kind: z.string(),
+    agentId: AgentIdSchema,
+    channelId: ChannelIdSchema.nullable(),
+    extensionId: ExtensionIdSchema.nullable(),
+    summary: z.string(),
+    status: z.enum(['pending', 'approved', 'rejected', 'expired', 'completed', 'failed']),
+    autonomous: z.boolean(),
+    resultMessage: z.string().nullable(),
+    decidedBy: z.string().nullable(),
+    createdAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().nonnegative(),
+    decidedAt: z.number().int().nonnegative().nullable(),
+  })
+  .strict()
+export type ExtensionRequestView = z.output<typeof ExtensionRequestSchema>
+
 export const HostSnapshotSchema = z
   .object({
+    communityFeedback: CommunityFeedbackSnapshotSchema.optional(),
     upgrade: HostUpgradeSummarySchema.optional(),
     cursor: HostSyncCursorSchema,
     diagnosticsSampledAt: z.number().int().nonnegative(),
@@ -1345,10 +1555,15 @@ export const HostSnapshotSchema = z
         subagents: z.object({ available: z.boolean() }).strict(),
         /** Optional in older hosts, which never offer `run_code`. */
         codeRun: CodeRunAvailabilitySchema.optional(),
+        /** Optional in older hosts, which never offer command accounts. */
+        githubCli: GithubCliAvailabilitySchema.optional(),
+        /** Optional in older hosts, which check candidates only in an open page. */
+        verificationBrowser: VerificationBrowserAvailabilitySchema.optional(),
         /** What this host can confine for commands beyond file writes; optional in older hosts. */
         commandConfinement: z.object({ readScope: z.boolean(), networkControl: z.boolean() }).strict().optional(),
         webSearch: z
           .object({
+            unavailableReason: z.string().optional(),
             provider: z.literal('deepseek-official'),
             available: z.boolean(),
             credentialConfigured: z.boolean(),
@@ -1362,6 +1577,8 @@ export const HostSnapshotSchema = z
       .strict(),
     connectionAdapters: z.array(AdapterConnectionDescriptorSchema),
     notificationSettings: NotificationSettingsViewSchema,
+    /** Optional in older hosts, which have no account library. */
+    commandAccounts: z.array(CommandAccountSchema).optional(),
     agents: z.array(
       z
         .object({
@@ -1427,6 +1644,8 @@ export const HostSnapshotSchema = z
           platformChannelId: NonEmptyStringSchema,
           kind: z.enum(['internal', 'group', 'direct']),
           displayName: z.string().optional(),
+          localDisplayName: z.string().optional(),
+          platformDisplayName: z.string().optional(),
           boundAgentId: AgentIdSchema.optional(),
           runtimePhase: ChannelRuntimePhaseSchema.default('idle'),
           activity: ChannelActivitySummarySchema.default({ unreadCount: 0, unreadCapped: false }),
@@ -1438,6 +1657,8 @@ export const HostSnapshotSchema = z
                 channelId: ChannelIdSchema,
                 agentId: AgentIdSchema,
                 triggerPolicy: TriggerPolicySchema,
+                /** Channel pause, independent of the response rule. */
+                paused: z.boolean().default(false),
                 processingFeedback: z.enum(['auto', 'off']).default('auto'),
                 /** Absent means `observe`. */
                 localAgentMessages: z.enum(['observe', 'trigger']).optional(),
@@ -1462,6 +1683,7 @@ export const HostSnapshotSchema = z
           adapterKey: NonEmptyStringSchema,
           alias: ConnectionAliasOutputSchema.optional(),
           activityTriggerDefaults: z.array(AdapterActivityKeySchema).default([]),
+          configuredSecrets: z.array(z.string()).optional(),
           status: z
             .object({
               state: z.enum(['stopped', 'connecting', 'connected', 'reconnecting', 'failed']),
@@ -1526,11 +1748,50 @@ export const HostSnapshotSchema = z
           displayName: z.string(),
           description: z.string(),
           createdByAgentId: AgentIdSchema.optional(),
+          /** The Revision of another extension this one was branched from. */
+          branchOf: z
+            .object({
+              extensionId: ExtensionIdSchema,
+              revisionId: ExtensionRevisionIdSchema,
+              /** Present while the original is on this machine. */
+              displayName: z.string().optional(),
+            })
+            .strict()
+            .optional(),
+          /** Shape version of the data stored on this machine. */
+          dataVersion: z.number().int().positive().default(1),
+          /** The unfinished revise task of this extension, if any. */
+          openRevisionTaskId: AuthoringTaskIdSchema.optional(),
+          /** Whether this machine publishes (`owner`) or follows the line on each community. */
+          communityLinks: z
+            .array(z.object({ communityUrl: z.string(), role: z.enum(['owner', 'subscriber']) }).strict())
+            .default([]),
           revisions: z.array(
             z
               .object({
                 id: ExtensionRevisionIdSchema,
                 revisionNumber: z.number().int().positive(),
+                /** Version number from the lineage, `v3` (or `v3·2` for a second Revision of the same generation). */
+                versionLabel: z.string(),
+                parentRevisionId: ExtensionRevisionIdSchema.optional(),
+                origin: z.enum(['authored', 'file', 'community', 'branch']),
+                authoringTaskId: AuthoringTaskIdSchema.optional(),
+                dataVersion: z.number().int().positive(),
+                /** Community releases this Revision is; installs and publishes from here both record one. */
+                releases: z
+                  .array(
+                    z
+                      .object({
+                        communityUrl: z.string(),
+                        releaseId: CommunityReleaseIdSchema,
+                        number: z.number().int().positive().nullable(),
+                        publisherHandle: z.string(),
+                        via: z.enum(['install', 'publish']),
+                        recordedAt: z.number().int().nonnegative(),
+                      })
+                      .strict(),
+                  )
+                  .default([]),
                 format: z.enum(['current', 'unavailable']).optional(),
                 ui: ExtensionUiContributionsSchema.default(EMPTY_EXTENSION_UI_CONTRIBUTIONS),
                 /** The host instance's configuration form (`config.host`). */
@@ -1543,8 +1804,6 @@ export const HostSnapshotSchema = z
                   .regex(/^\/api\/extensions\/[^/]+\/revisions\/[^/]+\/icon\/[a-f0-9]{64}\.(?:svg|png|webp)$/u)
                   .optional(),
                 createdAt: z.number().int().safe().nonnegative(),
-                /** 从社区安装的版本的来源；本机保存与文件导入没有来源。 */
-                source: CommunitySourceSchema.optional(),
                 provides: z.array(ExtensionProvideSchema),
                 /** Whether this Revision can be enabled for agents (agent-layer contributions or capabilities). */
                 agentLayer: z.boolean(),
@@ -1712,18 +1971,36 @@ export const HostSnapshotSchema = z
         .strict(),
     ),
     authoringTasks: z.array(AuthoringTaskSummarySchema).default([]),
+    /** Open sub-conversations, and the most recently ended ones of each channel. */
+    subConversations: z.array(SubConversationSchema).default([]),
     scheduledTasks: z.array(ScheduledTaskSchema).default([]),
+    /** Extension requests waiting for an administrator. */
+    extensionRequests: z.array(ExtensionRequestSchema).default([]),
   })
   .strict()
 
+export const CHANNEL_COMPOSER_MAX_ATTACHMENTS = 20
+export const CHANNEL_COMPOSER_MAX_BYTES = 64 * 1024 * 1024
+
 const MessageInputPartSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('text'), text: z.string().trim().min(1) }).strict(),
   z.object({ type: z.literal('mention'), memberId: ChannelMemberIdSchema }).strict(),
+  z.object({ type: z.literal('image'), assetId: AssetIdSchema, alt: z.string().trim().max(500).optional() }).strict(),
+  z.object({ type: z.literal('file'), assetId: AssetIdSchema, name: z.string().trim().max(255).optional() }).strict(),
 ])
 
 const SendChannelMessageRequestSchema = z
   .object({
-    parts: z.array(MessageInputPartSchema).min(1),
+    parts: z
+      .array(MessageInputPartSchema)
+      .min(1)
+      .max(256)
+      .refine(
+        (parts) =>
+          parts.filter((part) => part.type === 'image' || part.type === 'file').length <=
+          CHANNEL_COMPOSER_MAX_ATTACHMENTS,
+        '每条消息最多添加 20 个附件。',
+      ),
     clientEventId: NonEmptyStringSchema.optional(),
     senderMemberId: ChannelMemberIdSchema.optional(),
   })
@@ -2163,6 +2440,142 @@ const connectionParam = z.object({ connectionId: ConnectionIdSchema }).strict()
 const agentExtensionParam = z.object({ agentId: AgentIdSchema, extensionId: ExtensionIdSchema }).strict()
 
 const PermissionApprovalSchema = z.object({ permissionDigest: z.string().regex(/^[a-f0-9]{64}$/u) }).strict()
+
+/** One version of one line in the lineage view of an extension family. */
+export const ExtensionLineageNodeSchema = z
+  .object({
+    revisionId: ExtensionRevisionIdSchema,
+    extensionId: ExtensionIdSchema,
+    label: z.string(),
+    parentRevisionId: ExtensionRevisionIdSchema.optional(),
+    origin: z.enum(['authored', 'file', 'community', 'branch']),
+    createdAt: z.number().int().nonnegative(),
+    current: z.boolean(),
+    releaseNumbers: z.array(z.number().int().positive()),
+  })
+  .strict()
+
+/** Every line of the family an extension belongs to: the original and every branch of a branch on this machine. */
+export const ExtensionLineageSchema = z
+  .object({
+    lines: z.array(
+      z
+        .object({
+          extensionId: ExtensionIdSchema,
+          displayName: z.string(),
+          branchOf: z
+            .object({ extensionId: ExtensionIdSchema, revisionId: ExtensionRevisionIdSchema })
+            .strict()
+            .optional(),
+          nodes: z.array(ExtensionLineageNodeSchema),
+        })
+        .strict(),
+    ),
+  })
+  .strict()
+
+const DataChangeCountSchema = z
+  .object({
+    added: z.number().int().nonnegative(),
+    overwritten: z.number().int().nonnegative(),
+    removed: z.number().int().nonnegative(),
+    unchanged: z.number().int().nonnegative(),
+  })
+  .strict()
+
+/** Where a data migration takes data from. */
+export const ExtensionDataSourceSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('extension'), extensionId: ExtensionIdSchema }).strict(),
+  z.object({ kind: z.literal('snapshot'), snapshotId: z.string().min(1).max(80) }).strict(),
+  z.object({ kind: z.literal('package'), token: z.string().min(1).max(80) }).strict(),
+])
+
+export const ExtensionDataMigrationInputSchema = z
+  .object({
+    source: ExtensionDataSourceSchema,
+    mode: z.enum(['overwrite', 'replace']),
+    /** Storage of a source agent goes to the mapped agent here; unmapped agents are skipped. */
+    agentMap: z.record(z.string(), AgentIdSchema).optional(),
+    /** Also move the host and agent configuration (never credentials) the same way. */
+    includeConfig: z.boolean().optional(),
+  })
+  .strict()
+
+export const ExtensionDataPreviewSchema = z
+  .object({
+    diff: z
+      .object({ storage: DataChangeCountSchema, index: DataChangeCountSchema, library: DataChangeCountSchema })
+      .strict(),
+    destructive: z.boolean(),
+    sourceDataVersion: z.number().int().positive(),
+    targetDataVersion: z.number().int().positive(),
+    needsMigration: z.boolean(),
+    /** Configuration fields that would change, when configuration moves too. */
+    config: z
+      .object({
+        hostFields: z.array(z.string()),
+        agents: z.array(z.object({ agentId: AgentIdSchema, fields: z.array(z.string()) }).strict()),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+
+export const ExtensionDataStateSchema = z
+  .object({
+    dataVersion: z.number().int().positive(),
+    counts: z
+      .object({
+        storage: z.number().int().nonnegative(),
+        index: z.number().int().nonnegative(),
+        library: z.number().int().nonnegative(),
+      })
+      .strict(),
+    snapshots: z.array(
+      z
+        .object({
+          id: z.string(),
+          reason: z.enum(['switch', 'migration', 'manual']),
+          label: z.string(),
+          dataVersion: z.number().int().positive(),
+          byteSize: z.number().int().nonnegative(),
+          createdAt: z.number().int().nonnegative(),
+        })
+        .strict(),
+    ),
+  })
+  .strict()
+
+export const ExtensionDataPackageInspectionSchema = z
+  .object({
+    token: z.string(),
+    extensionId: z.string(),
+    displayName: z.string(),
+    dataVersion: z.number().int().positive(),
+    exportedAt: z.number().int().nonnegative(),
+    agents: z.array(z.object({ id: z.string(), name: z.string() }).strict()),
+    counts: z
+      .object({
+        storage: z.number().int().nonnegative(),
+        index: z.number().int().nonnegative(),
+        library: z.number().int().nonnegative(),
+      })
+      .strict(),
+  })
+  .strict()
+
+export const AdministratorSchema = z
+  .object({
+    connectionId: ConnectionIdSchema,
+    connectionName: z.string(),
+    platformUserId: z.string(),
+    identityId: PlatformIdentityIdSchema.optional(),
+    displayName: z.string(),
+    addedVia: z.enum(['console', 'claim']),
+    addedAt: z.number().int().nonnegative(),
+  })
+  .strict()
+
 const extensionParam = z.object({ extensionId: ExtensionIdSchema }).strict()
 const dshPluginPackageParam = z.object({ packageId: DshPluginPackageIdSchema }).strict()
 const dshPluginEntryParam = z.object({ entryId: DshPluginEntryIdSchema }).strict()
@@ -2173,6 +2586,7 @@ const dshSettingsParam = z.object({ namespace: NonEmptyStringSchema }).strict()
 const dshCredentialParam = z.object({ ref: DshCredentialRefSchema }).strict()
 const llmProviderParam = z.object({ provider: NonEmptyStringSchema }).strict()
 const authoringTaskParam = z.object({ taskId: AuthoringTaskIdSchema }).strict()
+const subConversationParam = z.object({ conversationId: SubConversationIdSchema }).strict()
 const scheduledTaskParam = z.object({ taskId: ScheduledTaskIdSchema }).strict()
 const authoringAttemptParam = z.object({ taskId: AuthoringTaskIdSchema, attemptId: AuthoringAttemptIdSchema }).strict()
 
@@ -2216,6 +2630,178 @@ const encodeBinaryUpload = (input: z.output<typeof BinaryUploadRequestSchema>) =
 })
 
 export const HostApiContracts = {
+  listCommands: defineContract({
+    method: 'GET',
+    path: '/api/commands',
+    params: z.object({ channelId: ChannelIdSchema.optional() }).strict(),
+    request: NoRequestBodySchema,
+    response: z
+      .object({
+        commands: z.array(CommandCatalogEntrySchema),
+        problems: z.array(z.string()),
+        /** Host-wide behavior: whether platform members without a grant are told so. */
+        settings: z.object({ unauthorizedFeedback: z.boolean() }).strict(),
+        /** Present when a channel was requested. */
+        channel: z
+          .object({
+            kind: z.enum(['internal', 'direct', 'group']),
+            /** The channel is an external group where commands must address the account. */
+            requiresMention: z.boolean(),
+            bareCommands: z.boolean(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict(),
+    error: HostApiErrorSchema,
+  }),
+  executeCommand: defineContract({
+    method: 'POST',
+    path: '/api/commands/execute',
+    params: EmptyParamsSchema,
+    request: z
+      .object({ channelId: ChannelIdSchema, text: z.string().min(1).max(16000), requestId: z.string().min(1).max(200) })
+      .strict(),
+    response: CommandExecutionRecordSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  getCommandExecution: defineContract({
+    method: 'GET',
+    path: '/api/commands/executions/:executionId',
+    params: z.object({ executionId: z.string().min(1) }).strict(),
+    request: NoRequestBodySchema,
+    response: CommandExecutionRecordSchema,
+    error: HostApiErrorSchema,
+  }),
+  setCommandPolicy: defineContract({
+    method: 'PUT',
+    path: '/api/commands/policy',
+    params: EmptyParamsSchema,
+    request: z
+      .object({
+        scope: z.union([z.literal('global'), ChannelIdSchema]),
+        name: z.string().min(1),
+        policy: CommandPolicySchema,
+      })
+      .strict(),
+    response: z.object({ saved: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  listCommandMembers: defineContract({
+    method: 'GET',
+    path: '/api/commands/members/:channelId',
+    params: z.object({ channelId: ChannelIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: z
+      .object({
+        members: z.array(
+          z
+            .object({
+              identityId: PlatformIdentityIdSchema,
+              displayName: z.string(),
+              platformUserId: z.string(),
+              authorized: z.boolean(),
+            })
+            .strict(),
+        ),
+      })
+      .strict(),
+    error: HostApiErrorSchema,
+  }),
+  setCommandSettings: defineContract({
+    method: 'PUT',
+    path: '/api/commands/settings',
+    params: EmptyParamsSchema,
+    request: z.object({ unauthorizedFeedback: z.boolean() }).strict(),
+    response: z.object({ saved: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  setCommandChannelSettings: defineContract({
+    method: 'PUT',
+    path: '/api/commands/channel-settings',
+    params: EmptyParamsSchema,
+    request: z.object({ channelId: ChannelIdSchema, bareCommands: z.boolean() }).strict(),
+    response: z.object({ saved: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  setCommandGrant: defineContract({
+    method: 'PUT',
+    path: '/api/commands/grants',
+    params: EmptyParamsSchema,
+    request: z
+      .object({ channelId: ChannelIdSchema, identityId: PlatformIdentityIdSchema, enabled: z.boolean() })
+      .strict(),
+    response: z.object({ saved: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  queryLogs: defineContract({
+    method: 'GET',
+    path: '/api/logs',
+    params: z.object({ query: z.string().max(32_768).optional() }).strict(),
+    request: NoRequestBodySchema,
+    response: hostLogPageSchema,
+    error: HostApiErrorSchema,
+  }),
+  getLog: defineContract({
+    method: 'GET',
+    path: '/api/logs/:id',
+    params: z.object({ id: z.string().min(1).max(256) }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ entry: hostLogEntrySchema }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  logSources: defineContract({
+    method: 'GET',
+    path: '/api/logs/sources',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: z.object({ sources: z.array(hostLogSourceSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  logStatus: defineContract({
+    method: 'GET',
+    path: '/api/logs/status',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: hostLogStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  logSettings: defineContract({
+    method: 'GET',
+    path: '/api/logs/settings',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: hostLogSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateLogSettings: defineContract({
+    method: 'PUT',
+    path: '/api/logs/settings',
+    params: EmptyParamsSchema,
+    request: hostLogSettingsSchema,
+    response: hostLogSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  startLogDebug: defineContract({
+    method: 'POST',
+    path: '/api/logs/debug',
+    params: EmptyParamsSchema,
+    request: hostLogDebugRequestSchema,
+    response: z.object({ lease: hostLogDebugLeaseSchema }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  stopLogDebug: defineContract({
+    method: 'DELETE',
+    path: '/api/logs/debug/:id',
+    params: z.object({ id: z.string().min(1).max(256) }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ stopped: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
   retryRuntimeCompatibility: defineContract({
     method: 'POST',
     path: '/api/runtime/compatibility/retry',
@@ -2508,6 +3094,7 @@ export const HostApiContracts = {
         channelId: ChannelIdSchema,
         agentId: AgentIdSchema,
         triggerPolicy: TriggerPolicySchema,
+        paused: z.boolean().default(false),
         processingFeedback: z.enum(['auto', 'off']).default('auto'),
         localAgentMessages: z.enum(['observe', 'trigger']).optional(),
         activityTriggerOverrides: ActivityTriggerOverridesSchema.default({}),
@@ -2569,16 +3156,48 @@ export const HostApiContracts = {
       .strict(),
     error: HostApiErrorSchema,
   }),
-  renameChannel: defineContract({
-    invalidatesSnapshot: true,
+  uploadChannelAsset: defineContract({
     method: 'POST',
-    path: '/api/channels/:channelId/display-name',
+    path: '/api/channels/:channelId/assets',
     params: channelParam,
-    request: z.object({ displayName: z.string().trim().min(1).max(120) }).strict(),
-    response: z.object({ channelId: ChannelIdSchema, displayName: z.string().trim().min(1).max(120) }).strict(),
+    request: BinaryUploadRequestSchema,
+    encodeRequest: (input) => ({
+      body: input.bytes,
+      headers: {
+        'content-type': 'application/octet-stream',
+        'x-file-name': encodeURIComponent(input.fileName ?? '附件'),
+      },
+    }),
+    response: z
+      .object({
+        assetId: AssetIdSchema,
+        mediaType: z.string().min(1),
+        byteSize: z.number().int().nonnegative(),
+        fileName: z.string().min(1).max(255),
+        partType: z.enum(['image', 'file']),
+      })
+      .strict(),
     error: HostApiErrorSchema,
   }),
-  getChannelRuntime: defineContract({
+  deleteChannelAsset: defineContract({
+    method: 'DELETE',
+    path: '/api/channels/:channelId/assets/:assetId',
+    params: z.object({ channelId: ChannelIdSchema, assetId: AssetIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ assetId: AssetIdSchema, revoked: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  renameChannel: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/channels/:channelId/display-name',
+    params: channelParam,
+    /** Empty selects the known platform name for an external channel. */
+    request: z.object({ displayName: z.string().trim().max(120) }).strict(),
+    response: z.object({ channelId: ChannelIdSchema, displayName: z.string().trim().min(1).max(120) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  getChannelRuntime: defineContract({
     method: 'GET',
     path: '/api/channels/:channelId/runtime',
     params: channelParam,
@@ -2616,6 +3235,57 @@ export const HostApiContracts = {
     response: ChannelRuntimeContextSchema,
     error: HostApiErrorSchema,
   }),
+  listSubConversations: defineContract({
+    method: 'GET',
+    path: '/api/sub-conversations/channels/:channelId',
+    params: channelParam,
+    request: NoRequestBodySchema,
+    response: z.object({ items: z.array(SubConversationSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  getSubConversationRuntime: defineContract({
+    method: 'GET',
+    path: '/api/sub-conversations/:conversationId/runtime',
+    params: subConversationParam,
+    request: NoRequestBodySchema,
+    // Read from memory while it runs and from its stored log after it ended.
+    response: z.object({ conversation: SubConversationSchema, runtime: ChannelRuntimeProjectionSchema }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  closeSubConversation: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/sub-conversations/:conversationId/close',
+    params: subConversationParam,
+    request: z.object({}).strict(),
+    response: SubConversationSchema,
+    error: HostApiErrorSchema,
+  }),
+  deleteSubConversation: defineContract({
+    invalidatesSnapshot: true,
+    method: 'DELETE',
+    path: '/api/sub-conversations/:conversationId',
+    params: subConversationParam,
+    request: NoRequestBodySchema,
+    response: z.object({ deleted: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  getSubConversationSettings: defineContract({
+    method: 'GET',
+    path: '/api/settings/sub-conversations',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: SubConversationSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateSubConversationSettings: defineContract({
+    method: 'PUT',
+    path: '/api/settings/sub-conversations',
+    params: EmptyParamsSchema,
+    request: SubConversationSettingsSchema,
+    response: SubConversationSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
   getChannelRuntimeInput: defineContract({
     method: 'GET',
     path: '/api/channels/:channelId/runtime/inputs/:messageId',
@@ -2699,6 +3369,24 @@ export const HostApiContracts = {
     response: MessagePacingSettingsSchema,
     error: HostApiErrorSchema,
   }),
+  getUpgradeBackupSettings: defineContract({
+    method: 'GET',
+    path: '/api/settings/upgrade-backup',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: UpgradeBackupSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateUpgradeBackupSettings: defineContract({
+    method: 'PUT',
+    path: '/api/settings/upgrade-backup',
+    params: EmptyParamsSchema,
+    request: z
+      .object({ mode: UpgradeBackupModeSchema, directory: z.string().trim().min(1).max(1024).optional() })
+      .strict(),
+    response: UpgradeBackupSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
   getRetrievalStatus: defineContract({
     method: 'GET',
     path: '/api/settings/retrieval',
@@ -2749,6 +3437,77 @@ export const HostApiContracts = {
     response: CodeRunAvailabilitySchema,
     error: HostApiErrorSchema,
   }),
+  downloadGithubCli: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/runtimes/github-cli/download',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: GithubCliAvailabilitySchema,
+    error: HostApiErrorSchema,
+  }),
+  removeGithubCli: defineContract({
+    invalidatesSnapshot: true,
+    method: 'DELETE',
+    path: '/api/runtimes/github-cli',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: GithubCliAvailabilitySchema,
+    error: HostApiErrorSchema,
+  }),
+  downloadVerificationBrowser: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/runtimes/verification-browser/download',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: VerificationBrowserAvailabilitySchema,
+    error: HostApiErrorSchema,
+  }),
+  removeVerificationBrowser: defineContract({
+    invalidatesSnapshot: true,
+    method: 'DELETE',
+    path: '/api/runtimes/verification-browser',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: VerificationBrowserAvailabilitySchema,
+    error: HostApiErrorSchema,
+  }),
+  getCommandAccounts: defineContract({
+    method: 'GET',
+    path: '/api/settings/command-accounts',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CommandAccountsViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  addCommandAccount: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/settings/command-accounts',
+    params: EmptyParamsSchema,
+    request: AddCommandAccountRequestSchema,
+    response: CommandAccountsViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  replaceCommandAccountToken: defineContract({
+    invalidatesSnapshot: true,
+    method: 'PUT',
+    path: '/api/settings/command-accounts/:accountId',
+    params: z.object({ accountId: NonEmptyStringSchema.max(64) }).strict(),
+    request: AddCommandAccountRequestSchema,
+    response: CommandAccountsViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  removeCommandAccount: defineContract({
+    invalidatesSnapshot: true,
+    method: 'DELETE',
+    path: '/api/settings/command-accounts/:accountId',
+    params: z.object({ accountId: NonEmptyStringSchema.max(64) }).strict(),
+    request: NoRequestBodySchema,
+    response: CommandAccountsViewSchema,
+    error: HostApiErrorSchema,
+  }),
   getChannelMemberNotes: defineContract({
     method: 'GET',
     path: '/api/channels/:channelId/member-notes',
@@ -2899,7 +3658,13 @@ export const HostApiContracts = {
     method: 'POST',
     path: '/api/connections/:connectionId/configuration',
     params: connectionParam,
-    request: z.object({ configuration: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])) }).strict(),
+    request: z
+      .object({
+        configuration: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+        /** Omitted keys keep their value; null explicitly clears an optional credential. */
+        credentials: z.record(z.string().min(1), z.string().min(1).max(16_384).nullable()).optional(),
+      })
+      .strict(),
     response: z
       .object({
         connectionId: ConnectionIdSchema,
@@ -3072,6 +3837,139 @@ export const HostApiContracts = {
     response: CommunityStatusSchema,
     error: HostApiErrorSchema,
   }),
+  getCommunityFeedbackSettings: defineContract({
+    method: 'GET',
+    path: '/api/community/feedback/settings',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CommunityFeedbackSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateCommunityFeedbackSettings: defineContract({
+    method: 'PUT',
+    path: '/api/community/feedback/settings',
+    params: EmptyParamsSchema,
+    request: CommunityFeedbackSettingsUpdateSchema,
+    response: CommunityFeedbackSettingsSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  listCommunityFeedback: defineContract({
+    timeoutMs: 60_000,
+    method: 'GET',
+    path: '/api/community/feedback',
+    params: z.object({ refresh: z.literal('1').optional() }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityFeedbackLocalListSchema,
+    error: HostApiErrorSchema,
+  }),
+  getCommunityFeedback: defineContract({
+    timeoutMs: 60_000,
+    method: 'GET',
+    path: '/api/community/feedback/items/:ref',
+    params: z.object({ ref: CommunityFeedbackRefSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityFeedbackSchema,
+    error: HostApiErrorSchema,
+  }),
+  createCommunityFeedbackDraft: defineContract({
+    method: 'POST',
+    path: '/api/community/feedback/drafts',
+    params: EmptyParamsSchema,
+    request: CommunityFeedbackDraftInputSchema,
+    response: CommunityFeedbackDraftSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  updateCommunityFeedbackDraft: defineContract({
+    method: 'PUT',
+    path: '/api/community/feedback/drafts/:draftId',
+    params: z.object({ draftId: CommunityFeedbackDraftIdSchema }).strict(),
+    request: CommunityFeedbackDraftUpdateSchema,
+    response: CommunityFeedbackDraftSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  sendCommunityFeedbackDraft: defineContract({
+    timeoutMs: 60_000,
+    method: 'POST',
+    path: '/api/community/feedback/drafts/:draftId/send',
+    params: z.object({ draftId: CommunityFeedbackDraftIdSchema }).strict(),
+    request: z.object({ consent: z.boolean().default(false) }).strict(),
+    response: CommunityFeedbackDraftSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  discardCommunityFeedbackDraft: defineContract({
+    method: 'DELETE',
+    path: '/api/community/feedback/drafts/:draftId',
+    params: z.object({ draftId: CommunityFeedbackDraftIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityFeedbackDraftSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  previewCommunityFeedbackPayload: defineContract({
+    method: 'GET',
+    path: '/api/community/feedback/drafts/:draftId/preview',
+    params: z.object({ draftId: CommunityFeedbackDraftIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityFeedbackPayloadSchema,
+    error: HostApiErrorSchema,
+  }),
+  getLastSentCommunityFeedbackPayload: defineContract({
+    method: 'GET',
+    path: '/api/community/feedback/last-sent',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CommunityFeedbackLastPayloadSchema,
+    error: HostApiErrorSchema,
+  }),
+  replyCommunityFeedback: defineContract({
+    method: 'POST',
+    path: '/api/community/feedback/items/:ref/messages',
+    params: z.object({ ref: CommunityFeedbackRefSchema }).strict(),
+    request: z.object({ body: z.string().trim().min(1).max(4000) }).strict(),
+    response: CommunityFeedbackSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  withdrawCommunityFeedback: defineContract({
+    method: 'POST',
+    path: '/api/community/feedback/items/:ref/withdraw',
+    params: z.object({ ref: CommunityFeedbackRefSchema }).strict(),
+    request: CommunityFeedbackWithdrawSchema,
+    response: CommunityFeedbackSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  reopenCommunityFeedback: defineContract({
+    method: 'POST',
+    path: '/api/community/feedback/items/:ref/reopen',
+    params: z.object({ ref: CommunityFeedbackRefSchema }).strict(),
+    request: CommunityFeedbackReopenSchema,
+    response: CommunityFeedbackSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  markCommunityFeedbackAffected: defineContract({
+    method: 'POST',
+    path: '/api/community/feedback/items/:ref/affected',
+    params: z.object({ ref: CommunityFeedbackRefSchema }).strict(),
+    request: z.object({ affected: z.boolean().default(true), consent: z.boolean().default(false) }).strict(),
+    response: CommunityFeedbackSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
+  confirmCommunityFeedbackFixed: defineContract({
+    method: 'POST',
+    path: '/api/community/feedback/items/:ref/confirm-fixed',
+    params: z.object({ ref: CommunityFeedbackRefSchema }).strict(),
+    request: z.object({}).strict(),
+    response: CommunityFeedbackSchema,
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
   startCommunityLogin: defineContract({
     method: 'POST',
     path: '/api/community/login',
@@ -3151,13 +4049,13 @@ export const HostApiContracts = {
       .strict(),
     error: HostApiErrorSchema,
   }),
-  listCommunityInstalled: defineContract({
-    timeoutMs: 30_000,
+  listCommunitySync: defineContract({
+    timeoutMs: 60_000,
     method: 'GET',
-    path: '/api/community/installed',
+    path: '/api/community/sync',
     params: z.object({ refresh: z.enum(['1']).optional() }).strict(),
     request: NoRequestBodySchema,
-    response: CommunityInstalledSchema,
+    response: CommunitySyncSchema,
     error: HostApiErrorSchema,
   }),
   listCommunityMine: defineContract({
@@ -3222,6 +4120,7 @@ export const HostApiContracts = {
     response: z
       .object({
         releaseId: CommunityReleaseIdSchema,
+        releaseNumber: z.number().int().positive(),
         reviewStatus: CommunityReviewStatusSchema,
         pageUrl: z.string().url(),
         reportUrl: z.string().url(),
@@ -3594,7 +4493,19 @@ export const HostApiContracts = {
     path: '/api/dynamic/:agentId/decline',
     params: agentParam,
     request: z
-      .object({ episodeId: EpisodeIdSchema, requestId: DynamicIdSchema, pluginRunId: DynamicIdSchema.optional() })
+      .object({
+        episodeId: EpisodeIdSchema,
+        requestId: DynamicIdSchema,
+        pluginRunId: DynamicIdSchema.optional(),
+        /**
+         * Why the run did not go ahead: the user declined it, or the page could not start one of its halves. A failed
+         * half is settled as a failed attempt (its Host is retracted and the agent hears about it), not as a decline.
+         */
+        reason: z.enum(['rejected', 'host-half-failed', 'client-half-failed']).optional(),
+        startedHere: z.boolean().optional(),
+        message: z.string().max(4000).optional(),
+        stack: z.string().max(16000).optional(),
+      })
       .strict(),
     response: z.object({ accepted: z.boolean() }).strict(),
     error: HostApiErrorSchema,
@@ -3750,36 +4661,20 @@ export const HostApiContracts = {
     method: 'POST',
     path: '/api/extensions/save-from-dynamic',
     params: EmptyParamsSchema,
-    request: z.union([
-      z
-        .object({
-          taskId: AuthoringTaskIdSchema,
-          attemptId: AuthoringAttemptIdSchema,
-          displayName: z.string().trim().min(1).max(80),
-          slug: z
-            .string()
-            .trim()
-            .regex(/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/u),
-          description: z.string().max(500).default(''),
-          targetExtensionId: ExtensionIdSchema.optional(),
-        })
-        .strict(),
-      z
-        .object({
-          agentId: AgentIdSchema,
-          episodeId: EpisodeIdSchema,
-          pluginId: DynamicIdSchema,
-          packageId: DynamicIdSchema,
-          displayName: z.string().trim().min(1).max(80),
-          slug: z
-            .string()
-            .trim()
-            .regex(/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/u),
-          description: z.string().max(500).default(''),
-          targetExtensionId: ExtensionIdSchema.optional(),
-        })
-        .strict(),
-    ]),
+    request: z
+      .object({
+        taskId: AuthoringTaskIdSchema,
+        /** The candidate the user saw; saving refuses when a newer one appeared since. */
+        attemptId: AuthoringAttemptIdSchema,
+        displayName: z.string().trim().min(1).max(80),
+        slug: z
+          .string()
+          .trim()
+          .regex(/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/u),
+        description: z.string().max(500).default(''),
+        targetExtensionId: ExtensionIdSchema.optional(),
+      })
+      .strict(),
     response: z
       .object({
         extensionId: ExtensionIdSchema,
@@ -3924,6 +4819,8 @@ export const HostApiContracts = {
         permissionApproval: PermissionApprovalSchema.optional(),
         /** Approval of expanded agent-layer capabilities for the agents that move to this Revision. */
         agentPermissionApproval: PermissionApprovalSchema.optional(),
+        /** Data copy to put back first, when the target Revision only reads an older data version. */
+        restoreDataSnapshotId: z.string().min(1).max(80).optional(),
       })
       .strict(),
     response: z
@@ -4040,6 +4937,15 @@ export const HostApiContracts = {
       .strict(),
     error: HostApiErrorSchema,
   }),
+  setChannelPaused: defineContract({
+    method: 'POST',
+    path: '/api/channels/:channelId/pause',
+    params: channelParam,
+    request: z.object({ paused: z.boolean() }).strict(),
+    response: z.object({ paused: z.boolean(), changed: z.boolean(), stopped: z.boolean() }).strict(),
+    error: HostApiErrorSchema,
+    invalidatesSnapshot: true,
+  }),
   resolveOutbound: defineContract({
     method: 'POST',
     path: '/api/outbound/:outboundId/resolve',
@@ -4114,6 +5020,196 @@ export const HostApiContracts = {
     response: z.object({ deleted: z.literal(true) }).strict(),
     error: HostApiErrorSchema,
   }),
+  getExtensionLineage: defineContract({
+    method: 'GET',
+    path: '/api/extensions/:extensionId/lineage',
+    params: extensionParam,
+    request: NoRequestBodySchema,
+    response: ExtensionLineageSchema,
+    error: HostApiErrorSchema,
+  }),
+  branchExtension: defineContract({
+    invalidatesSnapshot: true,
+    timeoutMs: 300_000,
+    method: 'POST',
+    path: '/api/extensions/:extensionId/branch',
+    params: extensionParam,
+    request: z
+      .object({
+        revisionId: ExtensionRevisionIdSchema,
+        name: z.string().trim().min(1).max(80),
+        slug: z
+          .string()
+          .trim()
+          .regex(/^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$/u)
+          .optional(),
+        copyData: z.boolean(),
+      })
+      .strict(),
+    response: z.object({ extensionId: ExtensionIdSchema, revisionId: ExtensionRevisionIdSchema }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  rollbackExtension: defineContract({
+    invalidatesSnapshot: true,
+    timeoutMs: 300_000,
+    method: 'POST',
+    path: '/api/extensions/:extensionId/revert',
+    params: extensionParam,
+    request: NoRequestBodySchema,
+    response: z.object({ message: z.string() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  getExtensionData: defineContract({
+    method: 'GET',
+    path: '/api/extensions/:extensionId/data',
+    params: extensionParam,
+    request: NoRequestBodySchema,
+    response: ExtensionDataStateSchema,
+    error: HostApiErrorSchema,
+  }),
+  previewExtensionDataMigration: defineContract({
+    timeoutMs: 60_000,
+    method: 'POST',
+    path: '/api/extensions/:extensionId/data/preview',
+    params: extensionParam,
+    request: ExtensionDataMigrationInputSchema,
+    response: ExtensionDataPreviewSchema,
+    error: HostApiErrorSchema,
+  }),
+  migrateExtensionData: defineContract({
+    invalidatesSnapshot: true,
+    timeoutMs: 300_000,
+    method: 'POST',
+    path: '/api/extensions/:extensionId/data/migrate',
+    params: extensionParam,
+    request: ExtensionDataMigrationInputSchema,
+    response: z.object({ snapshotId: z.string(), preview: ExtensionDataPreviewSchema }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  exportExtensionData: defineContract({
+    method: 'GET',
+    timeoutMs: 300_000,
+    path: '/api/extensions/:extensionId/data/export',
+    params: extensionParam,
+    request: NoRequestBodySchema,
+    responseFormat: 'bytes',
+    response: z.instanceof(Uint8Array),
+    error: HostApiErrorSchema,
+  }),
+  /** The same package with the host and agent configuration; secrets are left out. */
+  exportExtensionDataWithConfig: defineContract({
+    method: 'GET',
+    timeoutMs: 300_000,
+    path: '/api/extensions/:extensionId/data/export-config',
+    params: extensionParam,
+    request: NoRequestBodySchema,
+    responseFormat: 'bytes',
+    response: z.instanceof(Uint8Array),
+    error: HostApiErrorSchema,
+  }),
+  createExtensionDataSnapshot: defineContract({
+    method: 'POST',
+    path: '/api/extensions/:extensionId/data/snapshots',
+    params: extensionParam,
+    request: z.object({ label: z.string().trim().min(1).max(80) }).strict(),
+    response: z.object({ snapshotId: z.string() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  inspectExtensionDataPackage: defineContract({
+    timeoutMs: 300_000,
+    method: 'POST',
+    path: '/api/extensions/data/inspect',
+    params: EmptyParamsSchema,
+    request: BinaryUploadRequestSchema,
+    encodeRequest: encodeBinaryUpload,
+    response: ExtensionDataPackageInspectionSchema,
+    error: HostApiErrorSchema,
+  }),
+  listExtensionRequests: defineContract({
+    method: 'GET',
+    path: '/api/extension-requests',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: z.object({ requests: z.array(ExtensionRequestSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  approveExtensionRequest: defineContract({
+    invalidatesSnapshot: true,
+    timeoutMs: 300_000,
+    method: 'POST',
+    path: '/api/extension-requests/:number/approve',
+    params: z.object({ number: z.coerce.number().int().positive() }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ message: z.string() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  rejectExtensionRequest: defineContract({
+    method: 'POST',
+    path: '/api/extension-requests/:number/reject',
+    params: z.object({ number: z.coerce.number().int().positive() }).strict(),
+    request: z.object({ reason: z.string().trim().max(500).optional() }).strict(),
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  listAdministrators: defineContract({
+    method: 'GET',
+    path: '/api/administrators',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: z.object({ administrators: z.array(AdministratorSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  addAdministrator: defineContract({
+    method: 'POST',
+    path: '/api/administrators',
+    params: EmptyParamsSchema,
+    request: z.object({ identityId: PlatformIdentityIdSchema }).strict(),
+    response: AdministratorSchema,
+    error: HostApiErrorSchema,
+  }),
+  removeAdministrator: defineContract({
+    method: 'POST',
+    path: '/api/administrators/remove',
+    params: EmptyParamsSchema,
+    request: z.object({ connectionId: ConnectionIdSchema, platformUserId: z.string().min(1) }).strict(),
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  createAdministratorClaimCode: defineContract({
+    method: 'POST',
+    path: '/api/administrators/claim-code',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: z.object({ code: z.string(), expiresAt: z.number().int().nonnegative() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  dismissCommunityRelease: defineContract({
+    method: 'POST',
+    path: '/api/community/sync/:extensionId/dismiss',
+    params: extensionParam,
+    request: z.object({ releaseId: CommunityReleaseIdSchema.nullable() }).strict(),
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  updateFromCommunity: defineContract({
+    invalidatesSnapshot: true,
+    timeoutMs: 300_000,
+    method: 'POST',
+    path: '/api/community/sync/:extensionId/update',
+    params: extensionParam,
+    request: NoRequestBodySchema,
+    response: z.object({ message: z.string() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  archiveAuthoringTask: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/authoring/tasks/:taskId/archive',
+    params: z.object({ taskId: AuthoringTaskIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
 } as const
 
 export type HostApiContractName = keyof typeof HostApiContracts
@@ -4173,3 +5269,21 @@ export function buildHostApiContractPath<Params extends AnySchema>(
 export function buildHostApiPath<Name extends HostApiContractName>(name: Name, input: HostApiParams<Name>): string {
   return buildValidatedHostApiPath(HostApiContracts[name], input)
 }
+import {
+  CommunityFeedbackDraftIdSchema,
+  CommunityFeedbackDraftInputSchema,
+  CommunityFeedbackDraftSchema,
+  CommunityFeedbackDraftUpdateSchema,
+  CommunityFeedbackLastPayloadSchema,
+  CommunityFeedbackLocalListSchema,
+  CommunityFeedbackPayloadSchema,
+  CommunityFeedbackSettingsSchema,
+  CommunityFeedbackSettingsUpdateSchema,
+  CommunityFeedbackSnapshotSchema,
+} from './community-feedback-host.js'
+import {
+  CommunityFeedbackRefSchema,
+  CommunityFeedbackSchema,
+  CommunityFeedbackWithdrawSchema,
+  CommunityFeedbackReopenSchema,
+} from './community-feedback.js'