@nekro-nxt/contracts 0.5.0 → 0.7.0

package/src/host-api.ts

@@ -10,7 +10,30 @@ import {
   hostLogStatusSchema,
 } from './logs.js'
 import { McpServerFormSchema } from './extension-capabilities.js'
+import {
+  BoundCredentialsSchema,
+  CredentialBindingsRequestSchema,
+  CreateCredentialRequestSchema,
+  CredentialsViewSchema,
+  CredentialUsesViewSchema,
+  RemoveCredentialRequestSchema,
+  RemoveCredentialResultSchema,
+  ReplaceCredentialValueRequestSchema,
+  SetModelProviderAccessRequestSchema,
+  UpdateCredentialRequestSchema,
+} from './credentials.js'
+import {
+  AddLinkedAccountRequestSchema,
+  LinkedAccountMethodSchema,
+  LinkedAccountPlatformIdSchema,
+  LinkedAccountUsesViewSchema,
+  LinkedAccountViewSchema,
+  LocalGithubLoginSchema,
+  RemoveLinkedAccountRequestSchema,
+  ReplaceLinkedAccountTokenRequestSchema,
+} from './linked-accounts.js'
 import { HostUpgradeSummarySchema, RuntimeCompatibilityDiagnosticSchema } from './runtime-compatibility.js'
+import { AgentAliasesSchema, ResponseTimingSettingsSchema } from './response-timing.js'
 import {
   AgentIdSchema,
   AgentRevisionIdSchema,
@@ -23,6 +46,8 @@ import {
   ChannelIdSchema,
   ChannelMemberIdSchema,
   ConnectionIdSchema,
+  CredentialIdSchema,
+  LinkedAccountIdSchema,
   ConnectionEventIdSchema,
   DshPluginEntryIdSchema,
   DshPluginPackageIdSchema,
@@ -45,6 +70,7 @@ import {
   CommunityExtensionDetailSchema,
   CommunityExtensionSummarySchema,
   CommunityExtensionSortSchema,
+  CommunityFreshnessSchema,
   CommunityListingInputSchema,
   CommunityReleaseIdSchema,
   CommunityReviewStatusSchema,
@@ -289,7 +315,7 @@ export const ImageUnderstandingPolicyApiSchema = z
         restoreAfterCompaction: z
           .object({
             recentMessages: z.number().int().min(1).max(100),
-            maxImages: z.number().int().min(1).max(50),
+            maxImages: z.number().int().min(0).max(50),
           })
           .strict(),
       })
@@ -307,15 +333,18 @@ 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'])
+/** What the user wants a granted account used for; told to the agent only. */
+export type CommandAccountUsage = z.output<typeof CommandAccountUsageSchema>
 
+/**
+ * One linked account the agent's commands act as, at most one per platform (`service`). Grants saved before linked
+ * accounts name the account without its `acc_` prefix; both forms resolve to the same account.
+ */
 const CommandAccountGrantSchema = z
   .object({
-    service: CommandAccountServiceSchema,
-    accountId: NonEmptyStringSchema.max(64),
+    service: LinkedAccountPlatformIdSchema,
+    accountId: NonEmptyStringSchema.max(72),
     /** Told to the agent as guidance, not enforced; empty gives no hint. */
     usage: z.array(CommandAccountUsageSchema).max(4).default([]),
   })
@@ -336,7 +365,9 @@ const AgentCapabilitiesSchema = z
     /** 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. */
+    /** Voice messages reach the agent with a transcript (附加功能 F10). */
+    voiceTranscription: z.boolean().default(false),
+    /** Linked accounts this agent's commands act as, one per platform; 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
@@ -345,12 +376,23 @@ const AgentCapabilitiesSchema = z
     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'),
+    /**
+     * Whose requests make the agent change extension configuration. With `everyone`, members may only have it change
+     * ordinary fields of its own configuration; network fields, the host layer and credentials still need an
+     * administrator.
+     */
+    extensionConfigRequesters: z.enum(['everyone', 'admins']).default('admins'),
   })
   .strict()
 
 export const DynamicClientApprovalPolicySchema = z.enum(['manual', 'automatic'])
 
-export const NotificationEventKeySchema = z.enum(['dynamic-client-approval-requested', 'community-feedback-update'])
+export const NotificationEventKeySchema = z.enum([
+  'dynamic-client-approval-requested',
+  'community-feedback-update',
+  'credential-requested',
+  'extension-notification',
+])
 export type NotificationEventKey = z.output<typeof NotificationEventKeySchema>
 
 export const NotificationSettingsViewSchema = z
@@ -368,6 +410,8 @@ export const NotificationSettingsViewSchema = z
       .object({
         'dynamic-client-approval-requested': z.boolean(),
         'community-feedback-update': z.boolean().default(true),
+        'credential-requested': z.boolean().default(true),
+        'extension-notification': z.boolean().default(true),
       })
       .strict(),
   })
@@ -386,7 +430,12 @@ export const UpdateNotificationSettingsRequestSchema = z
       })
       .strict(),
     events: z
-      .object({ 'dynamic-client-approval-requested': z.boolean(), 'community-feedback-update': z.boolean().optional() })
+      .object({
+        'dynamic-client-approval-requested': z.boolean(),
+        'community-feedback-update': z.boolean().optional(),
+        'credential-requested': z.boolean().optional(),
+        'extension-notification': z.boolean().optional(),
+      })
       .strict(),
   })
   .strict()
@@ -406,6 +455,122 @@ export const ClientNotificationFeedResponseSchema = z
   })
   .strict()
 
+/** Which model writes one kind of compaction summary: that kind's default, or a model chosen for this agent. */
+export const AgentCompactionModelChoiceSchema = z.discriminatedUnion('mode', [
+  z.object({ mode: z.literal('follow') }).strict(),
+  z.object({ mode: z.literal('custom'), model: AgentModelSchema }).strict(),
+])
+
+/**
+ * In-session compaction follows the main model by default, so the replayed conversation hits the provider's cache;
+ * compaction into a new session follows the host's compaction model.
+ */
+export const AgentCompactionPolicySchema = z
+  .object({ inSession: AgentCompactionModelChoiceSchema, newSession: AgentCompactionModelChoiceSchema })
+  .strict()
+
+/** The host's idle compaction threshold, summary model and wait limit. */
+export const CompactionSettingsSchema = z
+  .object({
+    /** Minimum context occupancy for idle rollover; older settings inherit 50%. */
+    idleThresholdPercent: z.number().int().min(1).max(100).default(50),
+    newSessionModel: z.discriminatedUnion('mode', [
+      z.object({ mode: z.literal('main') }).strict(),
+      z.object({ mode: z.literal('custom'), model: AgentModelSchema }).strict(),
+    ]),
+    /** Past this the new session starts with a fallback note instead of a summary. */
+    timeoutSeconds: z.number().int().min(30).max(900),
+  })
+  .strict()
+
+export type CompactionSettings = z.output<typeof CompactionSettingsSchema>
+
+export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
+  idleThresholdPercent: 50,
+  newSessionModel: { mode: 'main' },
+  timeoutSeconds: 180,
+}
+
+export const FALLBACK_MODEL_LIMIT = 3
+
+/**
+ * Models an agent switches to, in order, when its main model has used up its quota or stays unavailable after the
+ * usual retries. Empty leaves the main model alone, as before fallback models existed.
+ */
+export const AgentFallbackModelsSchema = z
+  .array(AgentModelSchema)
+  .max(FALLBACK_MODEL_LIMIT)
+  .refine(
+    (models) => new Set(models.map((model) => `${model.provider}\0${model.model}`)).size === models.length,
+    '备用模型不能重复。',
+  )
+
+/** Why a channel conversation left its main model. */
+export const ModelFallbackReasonSchema = z.enum(['quota', 'rate-limit', 'unavailable'])
+export type ModelFallbackReason = z.output<typeof ModelFallbackReasonSchema>
+
+/** How long a model that failed is passed over before conversations try it again. */
+export const ModelFallbackSettingsSchema = z
+  .object({
+    /** After rate limits, server errors, timeouts or empty replies that outlasted the usual retries. */
+    unavailableCooldownMinutes: z.number().int().min(1).max(240),
+    /** After the quota or balance ran out. */
+    quotaCooldownMinutes: z.number().int().min(5).max(1440),
+  })
+  .strict()
+
+export type ModelFallbackSettings = z.output<typeof ModelFallbackSettingsSchema>
+
+export const DEFAULT_MODEL_FALLBACK_SETTINGS: ModelFallbackSettings = {
+  unavailableCooldownMinutes: 10,
+  quotaCooldownMinutes: 60,
+}
+
+/** The name an agent passes to open a sub-conversation on its main model; no candidate may take it. */
+export const SUB_CONVERSATION_MAIN_MODEL = '主模型'
+
+export const SUB_CONVERSATION_MODEL_LIMITS = { candidates: 8, name: 20, guidance: 200 } as const
+
+/**
+ * Models an agent may open sub-conversations with, each named so the agent can pick it and described so it knows
+ * when to. Without a `default`, a sub-conversation opened without naming a model follows the main model.
+ */
+export const AgentSubConversationModelsSchema = z
+  .object({
+    candidates: z
+      .array(
+        z
+          .object({
+            // Names are listed to the agent separated by commas, so they carry none and no line breaks.
+            name: z
+              .string()
+              .trim()
+              .min(1, '请填写子对话模型的名称。')
+              .max(SUB_CONVERSATION_MODEL_LIMITS.name)
+              .regex(/^[^\s,，、]+(?: [^\s,，、]+)*$/u, '子对话模型的名称不能含换行、逗号或顿号。')
+              .refine((name) => name !== SUB_CONVERSATION_MAIN_MODEL, `「${SUB_CONVERSATION_MAIN_MODEL}」是保留名称。`),
+            model: AgentModelSchema,
+            guidance: z.string().trim().max(SUB_CONVERSATION_MODEL_LIMITS.guidance),
+          })
+          .strict(),
+      )
+      .max(SUB_CONVERSATION_MODEL_LIMITS.candidates),
+    default: z.string().trim().min(1).optional(),
+  })
+  .strict()
+  .superRefine((policy, context) => {
+    const names = policy.candidates.map((candidate) => candidate.name)
+    if (new Set(names).size !== names.length)
+      context.addIssue({ code: 'custom', message: '子对话模型的名称不能重复。' })
+    if (policy.default !== undefined && !names.includes(policy.default)) {
+      context.addIssue({ code: 'custom', message: '默认的子对话模型不在候选里。' })
+    }
+  })
+
+export type AgentSubConversationModels = z.output<typeof AgentSubConversationModelsSchema>
+
+export const NO_SUB_CONVERSATION_MODELS: AgentSubConversationModels = { candidates: [] }
+
 const AgentRevisionRequestContentSchema = z
   .object({
     displayName: z.string().trim().min(1).max(80),
@@ -417,6 +582,10 @@ const AgentRevisionRequestContentSchema = z
     model: AgentModelSchema,
     imagePolicy: ImageUnderstandingPolicyApiSchema.optional(),
     dynamicClientApprovalPolicy: DynamicClientApprovalPolicySchema.optional(),
+    compaction: AgentCompactionPolicySchema.optional(),
+    subConversationModels: AgentSubConversationModelsSchema.optional(),
+    fallbackModels: AgentFallbackModelsSchema.optional(),
+    aliases: AgentAliasesSchema.optional(),
   })
   .strict()
 
@@ -454,14 +623,16 @@ const UpdateAgentCapabilitiesRequestSchema = AgentCapabilitiesSchema.partial()
     codeRun: z.boolean().optional(),
     commandNetwork: z.boolean().optional(),
     communityFeedbackAuto: z.boolean().optional(),
+    voiceTranscription: z.boolean().optional(),
     commandAccounts: z.array(CommandAccountGrantSchema).max(8).optional(),
     extensionAutonomy: z.enum(['manual', 'confirm', 'autonomous']).optional(),
     extensionRequesters: z.enum(['everyone', 'admins']).optional(),
+    extensionConfigRequesters: z.enum(['everyone', 'admins']).optional(),
   })
   .strict()
   .refine((value) => Object.values(value).some((entry) => entry !== undefined), '至少提供一个能力。')
 
-const TriggerPolicySchema = z.enum(['always', 'mentioned-or-replied', 'command', 'observe-only'])
+const TriggerPolicySchema = z.enum(['always', 'mentioned-or-replied', 'smart', 'command', 'observe-only'])
 
 export const WorkTreeOrderSchema = z
   .object({
@@ -473,6 +644,22 @@ export const WorkTreeOrderSchema = z
 
 export type WorkTreeOrder = z.output<typeof WorkTreeOrderSchema>
 
+/** The group key of 「未接线」 in `collapsedGroupIds`; agent groups use the agent id. */
+export const UNBOUND_CHANNEL_GROUP_ID = 'unbound'
+
+/**
+ * How the console arranges its channel list: pinned channels in their order and the groups it has collapsed. Shared
+ * by every device signed in to the console; it never changes bindings.
+ */
+export const ChannelListViewSchema = z
+  .object({
+    pinnedChannelIds: z.array(ChannelIdSchema).max(200),
+    collapsedGroupIds: z.array(z.union([AgentIdSchema, z.literal(UNBOUND_CHANNEL_GROUP_ID)])).max(500),
+  })
+  .strict()
+
+export type ChannelListView = z.output<typeof ChannelListViewSchema>
+
 const SnapshotMessagePartSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('text'), text: z.string() }).strict(),
   z
@@ -542,16 +729,36 @@ export const HostSnapshotMessageSchema = z
         trigger: z.enum(['default', 'suppress', 'force']),
         hidden: z.boolean(),
         annotation: z.string().optional(),
+        /** What NekroNXT itself added for the agent, such as the transcript of a voice message. */
+        hostAnnotations: z.array(z.object({ label: z.string(), text: z.string() }).strict()).optional(),
         extensions: z.array(z.string()),
         problems: z.array(z.string()).optional(),
       })
       .strict()
       .optional(),
+    /** Extensions that processed the agent's message before it was sent; `followUp` marks a message one appended. */
+    outboundProcessing: z
+      .object({
+        extensions: z.array(z.string()),
+        rewritten: z.boolean(),
+        followUp: z.literal(true).optional(),
+      })
+      .strict()
+      .optional(),
     /** A scheduled task came due: a Host fact shown as a notice, not a member message. */
     scheduledTask: z
       .object({ label: z.string(), extensionName: z.string().optional(), note: z.string().optional() })
       .strict()
       .optional(),
+    /** The agent finished waiting for someone to finish speaking: a Host fact shown as a notice. */
+    responseWait: z
+      .object({
+        displayName: z.string().optional(),
+        cause: z.enum(['quiet', 'limit']),
+        waitedSeconds: z.number().int().nonnegative(),
+      })
+      .strict()
+      .optional(),
   })
   .strict()
 
@@ -638,7 +845,14 @@ export const ChannelFactSseDataSchema = z
   })
   .strict()
 
-export const ChannelRuntimePhaseSchema = z.enum(['idle', 'thinking', 'using-tool', 'waiting-input', 'unavailable'])
+export const ChannelRuntimePhaseSchema = z.enum([
+  'idle',
+  'thinking',
+  'using-tool',
+  'compacting',
+  'waiting-input',
+  'unavailable',
+])
 
 export const ChannelRuntimeUsageSchema = z
   .object({
@@ -651,6 +865,12 @@ export const ChannelRuntimeUsageSchema = z
   })
   .strict()
 
+/** The latest progress a running extension tool reported. */
+export const ChannelRuntimeToolProgressSchema = z
+  .object({ text: z.string().min(1).max(200), fraction: z.number().min(0).max(1).optional() })
+  .strict()
+export type ChannelRuntimeToolProgress = z.output<typeof ChannelRuntimeToolProgressSchema>
+
 const channelRuntimeToolFields = {
   callId: NonEmptyStringSchema,
   name: NonEmptyStringSchema,
@@ -659,8 +879,11 @@ const channelRuntimeToolFields = {
   inputPreview: z.string().optional(),
   resultPreview: z.string().optional(),
   wroteToChannel: z.boolean().optional(),
-  deliveryState: z.enum(['sent', 'partially-sent', 'failed', 'unknown']).optional(),
+  /** `cancelled`: an extension stopped the message before it was sent. */
+  deliveryState: z.enum(['sent', 'partially-sent', 'failed', 'unknown', 'cancelled']).optional(),
   durationMs: z.number().int().nonnegative().optional(),
+  /** Set while the tool runs and has reported progress. */
+  progress: ChannelRuntimeToolProgressSchema.optional(),
 }
 
 export const ChannelRuntimeToolSchema = z
@@ -868,6 +1091,21 @@ export const ChannelRuntimeProjectionSchema = z
     episodeId: EpisodeIdSchema.optional(),
     phase: ChannelRuntimePhaseSchema,
     summary: z.string(),
+    /** A compaction under way: inside the current session, or before a new session opens. */
+    compaction: z
+      .object({ kind: z.enum(['in-session', 'new-session']), startedAt: z.number().int().nonnegative() })
+      .strict()
+      .optional(),
+    /** The conversation runs on a fallback model; it tries the main model again at a new message after `retryMainAt`. */
+    modelFallback: z
+      .object({
+        model: AgentModelSchema,
+        reason: ModelFallbackReasonSchema,
+        since: z.number().int().nonnegative(),
+        retryMainAt: z.number().int().nonnegative(),
+      })
+      .strict()
+      .optional(),
     pendingInjectCount: z.number().int().nonnegative(),
     occupancy: ChannelRuntimeOccupancySchema.optional(),
     cache: ChannelRuntimeCacheSchema.optional(),
@@ -983,6 +1221,20 @@ export const ChannelContextPolicyViewSchema = z
 
 export type ChannelContextPolicyView = z.output<typeof ChannelContextPolicyViewSchema>
 
+/** One desktop installer of a release; `urls` lists the sources to try in order. */
+export const ProductDownloadSchema = z
+  .object({
+    platform: z.enum(['mac', 'win', 'linux']),
+    arch: z.enum(['arm64', 'x64']),
+    name: z.string().min(1),
+    size: z.number().int().positive(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    urls: z.array(z.string().url()).min(1),
+  })
+  .strict()
+
+export type ProductDownload = z.output<typeof ProductDownloadSchema>
+
 /** Whether a newer release exists on the build's own channel; development builds are never compared. */
 export const ProductUpdateStatusSchema = z
   .object({
@@ -997,6 +1249,8 @@ export const ProductUpdateStatusSchema = z
         commit: z.string().optional(),
         url: z.string().url(),
         publishedAt: z.number().int().nonnegative().optional(),
+        /** Desktop installers of this release; the desktop app downloads its own and checks size and digest. */
+        downloads: z.array(ProductDownloadSchema).optional(),
       })
       .strict()
       .optional(),
@@ -1038,6 +1292,8 @@ export const SubConversationSchema = z
     /** What it handed back to the channel's conversation when it ended. */
     summary: z.string().max(4000).optional(),
     authoringTaskId: AuthoringTaskIdSchema.optional(),
+    /** The model a model-driven sub-conversation talks in; absent for scripts and ones opened before it was kept. */
+    model: AgentModelSchema.optional(),
     createdAt: z.number().int().nonnegative(),
     closedAt: z.number().int().nonnegative().optional(),
   })
@@ -1055,30 +1311,10 @@ export const SubConversationSettingsSchema = z.object({ retention: SubConversati
 export const RetrievalModeSchema = z.enum(['keyword', 'builtin'])
 export type RetrievalMode = z.output<typeof RetrievalModeSchema>
 
-/** Search used by extension indexes (表情包与扩展素材能力 §6.4). */
+/** Search used by extension indexes (表情包与扩展素材能力 §6.4); the model itself is the `retrieval` add-on. */
 export const RetrievalStatusSchema = z
   .object({
     mode: RetrievalModeSchema,
-    builtin: z
-      .object({
-        model: z.string(),
-        /** False where no inference runtime is published for this system and processor. */
-        supported: z.boolean(),
-        downloadBytes: z.number().int().nonnegative(),
-        install: z.discriminatedUnion('state', [
-          z.object({ state: z.literal('not-installed') }).strict(),
-          z
-            .object({
-              state: z.literal('downloading'),
-              receivedBytes: z.number().int().nonnegative(),
-              totalBytes: z.number().int().nonnegative(),
-            })
-            .strict(),
-          z.object({ state: z.literal('installed') }).strict(),
-          z.object({ state: z.literal('failed'), error: z.string() }).strict(),
-        ]),
-      })
-      .strict(),
     vectors: z
       .object({
         documents: z.number().int().nonnegative(),
@@ -1270,11 +1506,21 @@ export const AttentionItemSchema = z
       'agent-vision-unavailable',
       'logs-unavailable',
       'community-feedback',
+      'extension-update',
     ]),
     severity: z.enum(['critical', 'warning', 'info']),
     subject: z
       .object({
-        kind: z.enum(['outbound', 'channel', 'authoring-task', 'connection', 'agent', 'logs', 'community-feedback']),
+        kind: z.enum([
+          'outbound',
+          'channel',
+          'authoring-task',
+          'connection',
+          'agent',
+          'logs',
+          'community-feedback',
+          'extension-update',
+        ]),
         id: NonEmptyStringSchema,
       })
       .strict(),
@@ -1299,10 +1545,19 @@ export const AttentionItemSchema = z
           'open-agent',
           'open-logs',
           'open-community-feedback',
+          'open-extension-updates',
         ]),
         label: z.string().min(1).max(40),
       })
       .strict(),
+    /**
+     * The shared cause several items come from: a connection (its outage and the deliveries it failed) or an agent
+     * (its failed turns and unusable models). Dismissing by cause keeps it quiet until the cause recovers.
+     */
+    cause: z
+      .object({ key: z.string().min(1).max(200), label: z.string().min(1).max(120) })
+      .strict()
+      .optional(),
     occurredAt: z.number().int().safe().nonnegative(),
   })
   .strict()
@@ -1423,82 +1678,156 @@ export const ScheduledTaskSchema = z
 
 export type ScheduledTask = z.output<typeof ScheduledTaskSchema>
 
-/** The Node that runs `run_code` programs, and the download the desktop app offers when there is none. */
-export const CodeRunAvailabilitySchema = z
+/** Programs and models NekroNXT installs on request (附加功能); `<data root>/runtimes`, left out of backups. */
+export const AddonIdSchema = z.enum(['media', 'speech', 'retrieval', 'node', 'github-cli', 'browser'])
+export type AddonId = z.output<typeof AddonIdSchema>
+
+/** `extension`: used by extensions; `agent`: used by agents' commands; `host`: used by NekroNXT itself. */
+export const AddonGroupSchema = z.enum(['extension', 'agent', 'host'])
+export type AddonGroup = z.output<typeof AddonGroupSchema>
+
+/**
+ * `installed`: downloaded and ready; `available`: usable without installing (bundled, found on this device, cloud);
+ * `needs-config`: usable once configured (cloud).
+ */
+export const AddonStateSchema = z.enum([
+  'not-installed',
+  'installing',
+  'installed',
+  'failed',
+  'unsupported',
+  'available',
+  'needs-config',
+])
+export type AddonState = z.output<typeof AddonStateSchema>
+
+const AddonProgressSchema = z
   .object({
-    available: z.boolean(),
-    source: z.enum(['host', 'system', 'downloaded']).optional(),
+    receivedBytes: z.number().int().nonnegative(),
+    totalBytes: z.number().int().nonnegative().optional(),
+  })
+  .strict()
+
+/** One way an add-on can be provided, such as a program found on this device or one NekroNXT downloads. */
+export const AddonProviderStatusSchema = z
+  .object({
+    id: NonEmptyStringSchema,
+    title: NonEmptyStringSchema,
+    summary: z.string(),
+    state: AddonStateSchema,
+    /** `bundled`: installed with NekroNXT; `system`: found on this device; `downloaded`: fetched by NekroNXT. */
+    source: z.enum(['bundled', 'system', 'downloaded', 'cloud']).optional(),
+    /** The installed version, or the one an install fetches. */
     version: z.string().optional(),
-    download: z
+    resources: z
       .object({
-        version: z.string(),
-        state: z.enum(['idle', 'downloading', 'failed']),
-        receivedBytes: z.number().int().nonnegative().optional(),
-        totalBytes: z.number().int().nonnegative().optional(),
-        error: z.string().optional(),
+        /** Approximate for this system and processor. */
+        downloadBytes: z.number().int().nonnegative().optional(),
+        /** Measured from its own folder after install. */
+        installedBytes: z.number().int().nonnegative().optional(),
+        memoryBytes: z.number().int().nonnegative().optional(),
+        /** Short differences worth comparing, such as languages or speed. */
+        notes: z.array(z.string()).default([]),
       })
-      .strict()
-      .optional(),
+      .strict(),
+    /** One entry per component that carries its own license. */
+    licenses: z
+      .array(z.object({ component: z.string().optional(), name: NonEmptyStringSchema, url: z.url() }).strict())
+      .default([]),
+    /** Where downloads come from, for display. */
+    sources: z.array(z.string()).default([]),
+    progress: AddonProgressSchema.optional(),
+    error: z.string().optional(),
+    /** Other add-ons it needs to work. */
+    dependsOn: z.array(AddonIdSchema).default([]),
+    installable: z.boolean(),
+    removable: z.boolean(),
   })
   .strict()
+export type AddonProviderStatus = z.output<typeof AddonProviderStatusSchema>
 
-export type CodeRunAvailability = z.output<typeof CodeRunAvailabilitySchema>
+/** One add-on (a capability) as 设置 → 附加功能 shows it; the registry on the server is its only source. */
+export const AddonStatusSchema = z
+  .object({
+    id: AddonIdSchema,
+    group: AddonGroupSchema,
+    title: NonEmptyStringSchema,
+    summary: z.string(),
+    /** Who relies on it, as labels people recognise. */
+    usedBy: z.array(z.string()),
+    /** The selected provider's state, or, while none can be used, the one closest to usable. */
+    state: AddonStateSchema,
+    progress: AddonProgressSchema.optional(),
+    /** The provider in use; absent while none can be used. */
+    selected: NonEmptyStringSchema.optional(),
+    /** In declared order; providers that do not exist on this device are left out. */
+    providers: z.array(AddonProviderStatusSchema),
+  })
+  .strict()
+export type AddonStatus = z.output<typeof AddonStatusSchema>
 
-/** 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>
+/** Languages speech recognition can be asked for; `auto` lets the provider tell. */
+export const SpeechLanguageSchema = z.enum(['auto', 'zh', 'en', 'ja', 'ko', 'yue'])
+export type SpeechLanguage = z.output<typeof SpeechLanguageSchema>
 
-/** 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>
+/** The cloud provider of the `speech` add-on: a provider from 设置 → 模型 and the transcription model it serves. */
+export const SpeechCloudSettingsSchema = z
+  .object({
+    provider: NonEmptyStringSchema,
+    model: z.string().trim().min(1).max(200),
+    /** Used when a caller does not name a language. */
+    language: SpeechLanguageSchema.optional(),
+  })
+  .strict()
+export type SpeechCloudSettings = z.output<typeof SpeechCloudSettingsSchema>
 
-/**
- * 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
+export const SpeechSettingsSchema = 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),
+    cloud: SpeechCloudSettingsSchema.nullable(),
+    /** Configured providers with an OpenAI-compatible address, the ones cloud transcription can use. */
+    providers: z.array(z.object({ provider: NonEmptyStringSchema, displayName: z.string() }).strict()),
   })
   .strict()
+export type SpeechSettings = z.output<typeof SpeechSettingsSchema>
 
-export type CommandAccount = z.output<typeof CommandAccountSchema>
+/** Whether a capability that needs an add-on can run now; details live in `addons`. */
+export const AddonAvailabilitySchema = z.object({ available: z.boolean() }).strict()
+export type AddonAvailability = z.output<typeof AddonAvailabilitySchema>
 
-/** 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()
+/** A platform's own program that linked accounts work through, such as the GitHub CLI. */
+export const LinkedAccountPlatformToolSchema = z
+  .object({
+    /** The add-on it is installed as (`AddonStatus.id`). */
+    id: z.enum(['github-cli']),
+    name: z.string(),
+  })
+  .strict()
 
-export const CommandAccountsViewSchema = z
+/** 设置 → 关联账号: every platform the host supports, with its accounts and tools. */
+export const LinkedAccountsViewSchema = z
   .object({
-    accounts: z.array(CommandAccountSchema),
+    platforms: z.array(
+      z
+        .object({
+          id: LinkedAccountPlatformIdSchema,
+          name: z.string(),
+          addMethods: z.array(LinkedAccountMethodSchema),
+          tool: LinkedAccountPlatformToolSchema.optional(),
+          accounts: z.array(LinkedAccountViewSchema),
+        })
+        .strict(),
+    ),
     /** Logins found in the local GitHub CLI; empty when it is missing or not logged in. */
-    localLogins: z.array(LocalGithubLoginSchema),
+    localGithubLogins: z.array(LocalGithubLoginSchema),
   })
   .strict()
+export type LinkedAccountsView = z.output<typeof LinkedAccountsViewSchema>
 
-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 const RemoveLinkedAccountResultSchema = z.discriminatedUnion('removed', [
+  z.object({ removed: z.literal(true), view: LinkedAccountsViewSchema }).strict(),
+  z.object({ removed: z.literal(false), grantedAgentIds: z.array(AgentIdSchema) }).strict(),
 ])
-
-export type AddCommandAccountRequest = z.output<typeof AddCommandAccountRequestSchema>
+export type RemoveLinkedAccountResult = z.output<typeof RemoveLinkedAccountResultSchema>
 
 /** An extension action an agent asked an administrator to confirm, or one it took on its own. */
 export const ExtensionRequestSchema = z
@@ -1509,7 +1838,7 @@ export const ExtensionRequestSchema = z
     channelId: ChannelIdSchema.nullable(),
     extensionId: ExtensionIdSchema.nullable(),
     summary: z.string(),
-    status: z.enum(['pending', 'approved', 'rejected', 'expired', 'completed', 'failed']),
+    status: z.enum(['pending', 'approved', 'rejected', 'expired', 'completed', 'failed', 'superseded', 'withdrawn']),
     autonomous: z.boolean(),
     resultMessage: z.string().nullable(),
     decidedBy: z.string().nullable(),
@@ -1547,18 +1876,28 @@ export const HostSnapshotSchema = z
           name: z.string(),
           description: z.string().optional(),
           inputModalities: z.array(z.string()).optional(),
+          /** Selectable thinking levels, least to most; absent when the model offers no choice. */
+          reasoning: z
+            .object({
+              efforts: z.array(z.object({ id: NonEmptyStringSchema, name: z.string() }).strict()).min(1),
+              defaultEffort: NonEmptyStringSchema.optional(),
+            })
+            .strict()
+            .optional(),
         })
         .strict(),
     ),
     capabilityAvailability: z
       .object({
         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(),
+        /** The `node` add-on that `run_code` needs. */
+        codeRun: AddonAvailabilitySchema.optional(),
+        /** The `github-cli` add-on that commands use with a GitHub account. */
+        githubCli: AddonAvailabilitySchema.optional(),
+        /** The `browser` add-on that checks candidates when no page is open. */
+        verificationBrowser: AddonAvailabilitySchema.optional(),
+        /** The `speech` add-on that voice message transcription needs. */
+        speechRecognition: AddonAvailabilitySchema.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
@@ -1577,8 +1916,6 @@ 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({
@@ -1590,6 +1927,19 @@ export const HostSnapshotSchema = z
           capabilities: AgentCapabilitiesSchema,
           imagePolicy: ImageUnderstandingPolicyApiSchema,
           dynamicClientApprovalPolicy: DynamicClientApprovalPolicySchema,
+          /** Optional for older hosts, whose agents always follow both defaults. */
+          compaction: AgentCompactionPolicySchema.optional(),
+          /** Optional for older hosts, whose agents offer no candidates. */
+          subConversationModels: AgentSubConversationModelsSchema.optional(),
+          /** Optional for older hosts, whose agents have no fallback models. */
+          fallbackModels: AgentFallbackModelsSchema.optional(),
+          /** Optional for older hosts, whose agents have no aliases. */
+          aliases: AgentAliasesSchema.optional(),
+          /**
+           * Enabled extensions that process the agent's messages before they are sent, in the order they run. Absent
+           * when none does.
+           */
+          outboundOrder: z.array(ExtensionIdSchema).optional(),
           imageDiagnostics: z
             .object({
               route: z
@@ -1663,6 +2013,8 @@ export const HostSnapshotSchema = z
                 /** Absent means `observe`. */
                 localAgentMessages: z.enum(['observe', 'trigger']).optional(),
                 activityTriggerOverrides: ActivityTriggerOverridesSchema.default({}),
+                /** Absent on older hosts; missing keys use the defaults. */
+                responseTiming: ResponseTimingSettingsSchema.optional(),
                 boundAt: z.number().int().safe().nonnegative(),
               })
               .strict(),
@@ -1675,6 +2027,7 @@ export const HostSnapshotSchema = z
       channelIdsByAgent: {},
       unboundChannelIds: [],
     }),
+    channelListView: ChannelListViewSchema.default({ pinnedChannelIds: [], collapsedGroupIds: [] }),
     messages: z.array(HostSnapshotMessageSchema),
     connections: z.array(
       z
@@ -1684,6 +2037,7 @@ export const HostSnapshotSchema = z
           alias: ConnectionAliasOutputSchema.optional(),
           activityTriggerDefaults: z.array(AdapterActivityKeySchema).default([]),
           configuredSecrets: z.array(z.string()).optional(),
+          boundCredentials: BoundCredentialsSchema.optional(),
           status: z
             .object({
               state: z.enum(['stopped', 'connecting', 'connected', 'reconnecting', 'failed']),
@@ -1856,6 +2210,7 @@ export const HostSnapshotSchema = z
                 /** Secret fields are removed; `configuredSecrets` lists those the Host stores. */
                 config: JsonValueSchema,
                 configuredSecrets: z.array(z.string()).optional(),
+                boundCredentials: BoundCredentialsSchema.optional(),
                 activatedAt: z.number().int().safe().nonnegative(),
                 runtime: z
                   .object({
@@ -1891,6 +2246,7 @@ export const HostSnapshotSchema = z
               /** Secret fields are removed; `configuredSecrets` lists those the Host stores. */
               config: JsonValueSchema.default({}),
               configuredSecrets: z.array(z.string()).optional(),
+              boundCredentials: BoundCredentialsSchema.optional(),
               runtime: z
                 .object({
                   status: z.enum(['active', 'restore-failed', 'dispose-failed']),
@@ -1973,6 +2329,7 @@ export const HostSnapshotSchema = z
     authoringTasks: z.array(AuthoringTaskSummarySchema).default([]),
     /** Open sub-conversations, and the most recently ended ones of each channel. */
     subConversations: z.array(SubConversationSchema).default([]),
+    addons: z.array(AddonStatusSchema).default([]),
     scheduledTasks: z.array(ScheduledTaskSchema).default([]),
     /** Extension requests waiting for an administrator. */
     extensionRequests: z.array(ExtensionRequestSchema).default([]),
@@ -2099,6 +2456,10 @@ export const DshPluginCatalogEntrySchema = z
     loadError: z.object({ code: NonEmptyStringSchema, message: NonEmptyStringSchema }).strict().optional(),
     packageId: DshPluginPackageIdSchema.optional(),
     installSource: z.enum(['registry', 'tarball', 'imported']).optional(),
+    /** Published by the DSH maintainers on npm for the DSH release this build runs. */
+    official: z.boolean().optional(),
+    /** Third-party installed plugins: whether an administrator allowed them to submit images to the model. */
+    imageSubmission: z.boolean().optional(),
     installedAt: z.number().int().safe().nonnegative().optional(),
     clientUiDetected: z.boolean().optional(),
     hostUi: DshNxtHostUiSchema.optional(),
@@ -2113,6 +2474,8 @@ export const DshPluginCatalogEntrySchema = z
             suggestedScope: z.enum(['host', 'agent']),
             selectedScope: z.enum(['host', 'agent']).optional(),
             config: JsonValueSchema,
+            /** Host services this official entry declared and received; known once it has loaded. */
+            grantedServices: z.array(NonEmptyStringSchema).optional(),
             activations: z.array(
               z
                 .object({
@@ -2122,9 +2485,13 @@ export const DshPluginCatalogEntrySchema = z
                   activatedAt: z.number().int().safe().nonnegative(),
                   diagnostic: z
                     .object({
-                      status: z.enum(['active', 'load-failed', 'restore-failed', 'dispose-failed']),
-                      phase: z.enum(['import', 'apply', 'update', 'dispose', 'restore']),
+                      status: z.enum(['active', 'pending', 'load-failed', 'restore-failed', 'dispose-failed']),
+                      phase: z.enum(['import', 'dependency', 'apply', 'update', 'dispose', 'restore']),
                       message: z.string().optional(),
+                      /** Services a pending entry still waits for. */
+                      waitingFor: z.array(NonEmptyStringSchema).optional(),
+                      /** The waited-for services this entry can never receive, since only official plugins get them. */
+                      restrictedServices: z.array(NonEmptyStringSchema).optional(),
                       observedAt: z.number().int().safe().nonnegative(),
                     })
                     .optional(),
@@ -2239,6 +2606,9 @@ export type HostSseEvent = z.output<typeof HostSseEventSchema>
 /** Request content a model accepts; `image` enables native vision for agents using the model. */
 export const LlmModelInputModalitiesSchema = z.array(z.enum(['text', 'image'])).min(1)
 
+/** Thinking levels a model offers, least to most; the ids are the adapter's own. */
+export const LlmModelReasoningEffortsSchema = z.array(NonEmptyStringSchema).min(1)
+
 export const LlmProviderModelSchema = z
   .object({
     id: NonEmptyStringSchema,
@@ -2246,6 +2616,7 @@ export const LlmProviderModelSchema = z
     contextWindow: z.number().int().positive().optional(),
     maxTokens: z.number().int().positive().optional(),
     inputModalities: LlmModelInputModalitiesSchema.optional(),
+    reasoningEfforts: LlmModelReasoningEffortsSchema.optional(),
   })
   .strict()
 
@@ -2256,6 +2627,7 @@ export const LlmDiscoveredModelSchema = z
     contextWindow: z.number().int().positive().optional(),
     maxTokens: z.number().int().positive().optional(),
     inputModalities: LlmModelInputModalitiesSchema.optional(),
+    reasoningEfforts: LlmModelReasoningEffortsSchema.optional(),
   })
   .strict()
 
@@ -2299,6 +2671,60 @@ export const LlmProviderViewSchema = z
     discoverable: z.boolean(),
     /** `null` when the current configuration was never tested; absent from hosts that do not record tests. */
     lastTest: LlmProviderTestResultSchema.nullable().optional(),
+    /** Present when the provider can sign in with a subscription account instead of an API key. */
+    subscription: z
+      .object({
+        label: NonEmptyStringSchema,
+        /** The route uses the signed-in account rather than an API key. */
+        active: z.boolean(),
+        accountLabel: z.string().nullable(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+
+export const SubscriptionStatusSchema = z
+  .object({
+    provider: NonEmptyStringSchema,
+    label: NonEmptyStringSchema,
+    usageUrl: z.url(),
+    available: z.boolean(),
+    mode: z.enum(['unconfigured', 'api-key', 'subscription']),
+    activeAccountId: z.string().nullable(),
+    accounts: z.array(
+      z
+        .object({
+          id: NonEmptyStringSchema,
+          label: NonEmptyStringSchema,
+          email: z.string().nullable(),
+          createdAt: z.number().int().nonnegative(),
+        })
+        .strict(),
+    ),
+    login: z
+      .object({
+        id: NonEmptyStringSchema,
+        status: z.enum(['running', 'authorized', 'cancelled', 'failed']),
+        notices: z.array(
+          z.object({ message: z.string(), url: z.string().optional(), code: z.string().optional() }).strict(),
+        ),
+        prompt: z
+          .object({
+            id: NonEmptyStringSchema,
+            kind: z.enum(['text', 'secret', 'select']),
+            message: z.string(),
+            placeholder: z.string().optional(),
+            options: z
+              .array(z.object({ id: z.string(), label: z.string(), description: z.string().optional() }).strict())
+              .optional(),
+          })
+          .strict()
+          .nullable(),
+        error: z.string().nullable(),
+      })
+      .strict()
+      .nullable(),
   })
   .strict()
 
@@ -2403,6 +2829,8 @@ const defineContract = <
 })
 
 const agentParam = z.object({ agentId: AgentIdSchema }).strict()
+const credentialParam = z.object({ credentialId: CredentialIdSchema }).strict()
+const linkedAccountParam = z.object({ accountId: LinkedAccountIdSchema }).strict()
 const agentRevisionParam = z.object({ agentId: AgentIdSchema, revisionId: AgentRevisionIdSchema }).strict()
 
 export const AgentRevisionChangedFieldSchema = z.enum([
@@ -2412,6 +2840,10 @@ export const AgentRevisionChangedFieldSchema = z.enum([
   'capabilities',
   'imagePolicy',
   'approvalPolicy',
+  'compaction',
+  'subConversationModels',
+  'fallbackModels',
+  'aliases',
 ])
 
 export const AgentRevisionHistorySchema = z
@@ -2441,6 +2873,22 @@ const agentExtensionParam = z.object({ agentId: AgentIdSchema, extensionId: Exte
 
 const PermissionApprovalSchema = z.object({ permissionDigest: z.string().regex(/^[a-f0-9]{64}$/u) }).strict()
 
+/**
+ * What keeps a version from being cleaned up: in use, enabled for an agent, released to a community, kept by hand,
+ * the start of a branch, the base of an open revision, needed by 回到上一个版本, or named by a pending request.
+ */
+export const ExtensionRevisionProtectionSchema = z.enum([
+  'installed',
+  'active',
+  'released',
+  'kept',
+  'branch',
+  'revising',
+  'undo',
+  'request',
+])
+export type ExtensionRevisionProtection = z.output<typeof ExtensionRevisionProtectionSchema>
+
 /** One version of one line in the lineage view of an extension family. */
 export const ExtensionLineageNodeSchema = z
   .object({
@@ -2452,6 +2900,10 @@ export const ExtensionLineageNodeSchema = z
     createdAt: z.number().int().nonnegative(),
     current: z.boolean(),
     releaseNumbers: z.array(z.number().int().positive()),
+    /** Marked by an administrator to keep. */
+    kept: z.boolean(),
+    /** Why the version cannot be cleaned up; absent when it can. */
+    protectedBy: ExtensionRevisionProtectionSchema.optional(),
   })
   .strict()
 
@@ -2577,6 +3029,41 @@ export const AdministratorSchema = z
   .strict()
 
 const extensionParam = z.object({ extensionId: ExtensionIdSchema }).strict()
+
+export const ExtensionConfigVersionSourceSchema = z.enum(['console', 'agent', 'chat-admin', 'revert', 'auto-revert'])
+export type ExtensionConfigVersionSource = z.output<typeof ExtensionConfigVersionSourceSchema>
+
+/**
+ * One saved state of an extension's host configuration or of one agent's configuration. Versions are numbered per
+ * extension, layer and agent; reverting writes an old one again as a new version. Secret fields only show whether
+ * they were set and which named credential they were bound to.
+ */
+export const ExtensionConfigVersionSchema = z
+  .object({
+    id: z.number().int().positive(),
+    extensionId: ExtensionIdSchema,
+    layer: z.enum(['host', 'agent']),
+    agentId: AgentIdSchema.nullable(),
+    version: z.number().int().positive(),
+    config: JsonValueSchema,
+    configuredSecrets: z.array(z.string()).optional(),
+    boundCredentials: z.record(z.string(), CredentialIdSchema).optional(),
+    source: ExtensionConfigVersionSourceSchema,
+    actorAgentId: AgentIdSchema.nullable(),
+    requesterMemberId: z.string().nullable(),
+    reason: z.string().nullable(),
+    createdAt: z.number().int().nonnegative(),
+  })
+  .strict()
+export type ExtensionConfigVersion = z.output<typeof ExtensionConfigVersionSchema>
+
+const extensionConfigVersionParam = z
+  .object({
+    extensionId: ExtensionIdSchema,
+    /** Decimal text of the version id; the path builder only takes strings. */
+    versionId: z.string().regex(/^[1-9]\d{0,15}$/u),
+  })
+  .strict()
 const dshPluginPackageParam = z.object({ packageId: DshPluginPackageIdSchema }).strict()
 const dshPluginEntryParam = z.object({ entryId: DshPluginEntryIdSchema }).strict()
 const extensionRevisionParam = z
@@ -2830,11 +3317,20 @@ export const HostApiContracts = {
       .object({
         task: AuthoringTaskSummarySchema,
         attempts: z.array(AuthoringAttemptSummarySchema),
-        /** Secret fields of the latest candidate and which have a test value for this task's dynamic runs. */
-        testSecrets: z
+        /**
+         * Test configuration of this task's dynamic runs: fields of the latest candidate the user can type, which
+         * credentials are set, the user's values and the values the agent provided.
+         */
+        testConfig: z
           .object({
-            fields: z.array(z.object({ key: z.string(), title: z.string() }).strict()),
+            fields: z.array(
+              z.object({ key: z.string(), title: z.string(), kind: z.enum(['secret', 'string', 'number']) }).strict(),
+            ),
             configured: z.array(z.string()),
+            values: z.record(z.string(), z.union([z.string(), z.number()])),
+            agentValues: z.record(z.string(), JsonValueSchema),
+            /** Secret fields bound to a named credential, by the user or else by the agent. */
+            boundCredentials: BoundCredentialsSchema.optional(),
           })
           .strict()
           .optional(),
@@ -2884,12 +3380,26 @@ export const HostApiContracts = {
     response: AuthoringTaskSummarySchema,
     error: HostApiErrorSchema,
   }),
-  setAuthoringTestSecrets: defineContract({
+  setAuthoringTestConfig: defineContract({
     method: 'PUT',
     path: '/api/authoring/tasks/:taskId/test-secrets',
     params: authoringTaskParam,
-    request: z.object({ secrets: z.record(z.string(), z.string().max(8192)) }).strict(),
-    response: z.object({ configured: z.array(z.string()) }).strict(),
+    request: z
+      .object({
+        secrets: z.record(z.string(), z.string().max(8192)),
+        /** Text and number values; an empty string goes back to the agent's value or the default. */
+        values: z.record(z.string(), z.union([z.string().max(8192), z.number()])).optional(),
+        /** Secret fields to bind to named credentials instead of a typed value; `null` leaves the field unset. */
+        credentialBindings: CredentialBindingsRequestSchema.optional(),
+      })
+      .strict(),
+    response: z
+      .object({
+        configured: z.array(z.string()),
+        values: z.record(z.string(), z.union([z.string(), z.number()])),
+        boundCredentials: BoundCredentialsSchema.optional(),
+      })
+      .strict(),
     error: HostApiErrorSchema,
   }),
   deleteAuthoringTask: defineContract({
@@ -3087,6 +3597,8 @@ export const HostApiContracts = {
         /** Messages from another local agent's account: `observe` keeps them as context unless they @ this agent. */
         localAgentMessages: z.enum(['observe', 'trigger']).optional(),
         activityTriggerOverrides: ActivityTriggerOverridesSchema.optional(),
+        /** Omitted keeps the binding's current timing; `{}` resets every field to its default. */
+        responseTiming: ResponseTimingSettingsSchema.optional(),
       })
       .strict(),
     response: z
@@ -3098,6 +3610,7 @@ export const HostApiContracts = {
         processingFeedback: z.enum(['auto', 'off']).default('auto'),
         localAgentMessages: z.enum(['observe', 'trigger']).optional(),
         activityTriggerOverrides: ActivityTriggerOverridesSchema.default({}),
+        responseTiming: ResponseTimingSettingsSchema.optional(),
         boundAt: z.number().int().safe().nonnegative(),
       })
       .strict(),
@@ -3121,6 +3634,23 @@ export const HostApiContracts = {
     response: WorkTreeOrderSchema,
     error: HostApiErrorSchema,
   }),
+  getChannelListView: defineContract({
+    method: 'GET',
+    path: '/api/channel-list-view',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: ChannelListViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateChannelListView: defineContract({
+    invalidatesSnapshot: true,
+    method: 'PUT',
+    path: '/api/channel-list-view',
+    params: EmptyParamsSchema,
+    request: ChannelListViewSchema,
+    response: ChannelListViewSchema,
+    error: HostApiErrorSchema,
+  }),
   listChannelMessages: defineContract({
     method: 'GET',
     path: '/api/channels/:channelId/messages',
@@ -3369,6 +3899,39 @@ export const HostApiContracts = {
     response: MessagePacingSettingsSchema,
     error: HostApiErrorSchema,
   }),
+  getCompactionSettings: defineContract({
+    method: 'GET',
+    path: '/api/settings/compaction',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CompactionSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateCompactionSettings: defineContract({
+    invalidatesSnapshot: true,
+    method: 'PUT',
+    path: '/api/settings/compaction',
+    params: EmptyParamsSchema,
+    request: CompactionSettingsSchema,
+    response: CompactionSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  getModelFallbackSettings: defineContract({
+    method: 'GET',
+    path: '/api/settings/model-fallback',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: ModelFallbackSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateModelFallbackSettings: defineContract({
+    method: 'PUT',
+    path: '/api/settings/model-fallback',
+    params: EmptyParamsSchema,
+    request: ModelFallbackSettingsSchema,
+    response: ModelFallbackSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
   getUpgradeBackupSettings: defineContract({
     method: 'GET',
     path: '/api/settings/upgrade-backup',
@@ -3403,109 +3966,167 @@ export const HostApiContracts = {
     response: RetrievalStatusSchema,
     error: HostApiErrorSchema,
   }),
-  downloadRetrievalModel: defineContract({
-    method: 'POST',
-    path: '/api/settings/retrieval/model/download',
+  getSpeechSettings: defineContract({
+    method: 'GET',
+    path: '/api/settings/speech',
     params: EmptyParamsSchema,
     request: NoRequestBodySchema,
-    response: RetrievalStatusSchema,
+    response: SpeechSettingsSchema,
     error: HostApiErrorSchema,
   }),
-  removeRetrievalModel: defineContract({
-    method: 'DELETE',
-    path: '/api/settings/retrieval/model',
+  updateSpeechSettings: defineContract({
+    method: 'PUT',
+    path: '/api/settings/speech',
+    params: EmptyParamsSchema,
+    request: z.object({ cloud: SpeechCloudSettingsSchema.nullable() }).strict(),
+    response: SpeechSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  listAddons: defineContract({
+    method: 'GET',
+    path: '/api/addons',
     params: EmptyParamsSchema,
     request: NoRequestBodySchema,
-    response: RetrievalStatusSchema,
+    response: z.object({ addons: z.array(AddonStatusSchema) }).strict(),
     error: HostApiErrorSchema,
   }),
-  downloadCodeRunNode: defineContract({
+  installAddonProvider: defineContract({
     invalidatesSnapshot: true,
     method: 'POST',
-    path: '/api/runtimes/code-run-node/download',
-    params: EmptyParamsSchema,
+    path: '/api/addons/:id/providers/:provider/install',
+    params: z.object({ id: AddonIdSchema, provider: NonEmptyStringSchema }).strict(),
     request: NoRequestBodySchema,
-    response: CodeRunAvailabilitySchema,
+    response: AddonStatusSchema,
     error: HostApiErrorSchema,
   }),
-  removeCodeRunNode: defineContract({
+  removeAddonProvider: defineContract({
     invalidatesSnapshot: true,
     method: 'DELETE',
-    path: '/api/runtimes/code-run-node',
-    params: EmptyParamsSchema,
+    path: '/api/addons/:id/providers/:provider',
+    params: z.object({ id: AddonIdSchema, provider: NonEmptyStringSchema }).strict(),
     request: NoRequestBodySchema,
-    response: CodeRunAvailabilitySchema,
+    response: AddonStatusSchema,
     error: HostApiErrorSchema,
   }),
-  downloadGithubCli: defineContract({
+  selectAddonProvider: defineContract({
     invalidatesSnapshot: true,
-    method: 'POST',
-    path: '/api/runtimes/github-cli/download',
-    params: EmptyParamsSchema,
-    request: NoRequestBodySchema,
-    response: GithubCliAvailabilitySchema,
+    method: 'PUT',
+    path: '/api/addons/:id/selection',
+    params: z.object({ id: AddonIdSchema }).strict(),
+    request: z.object({ provider: NonEmptyStringSchema }).strict(),
+    response: AddonStatusSchema,
     error: HostApiErrorSchema,
   }),
-  removeGithubCli: defineContract({
-    invalidatesSnapshot: true,
-    method: 'DELETE',
-    path: '/api/runtimes/github-cli',
+  getLinkedAccounts: defineContract({
+    method: 'GET',
+    path: '/api/settings/linked-accounts',
     params: EmptyParamsSchema,
     request: NoRequestBodySchema,
-    response: GithubCliAvailabilitySchema,
+    response: LinkedAccountsViewSchema,
     error: HostApiErrorSchema,
   }),
-  downloadVerificationBrowser: defineContract({
+  addLinkedAccount: defineContract({
     invalidatesSnapshot: true,
     method: 'POST',
-    path: '/api/runtimes/verification-browser/download',
+    path: '/api/settings/linked-accounts',
     params: EmptyParamsSchema,
-    request: NoRequestBodySchema,
-    response: VerificationBrowserAvailabilitySchema,
+    request: AddLinkedAccountRequestSchema,
+    response: LinkedAccountsViewSchema,
     error: HostApiErrorSchema,
   }),
-  removeVerificationBrowser: defineContract({
+  replaceLinkedAccountToken: defineContract({
     invalidatesSnapshot: true,
-    method: 'DELETE',
-    path: '/api/runtimes/verification-browser',
-    params: EmptyParamsSchema,
+    method: 'PUT',
+    path: '/api/settings/linked-accounts/:accountId/token',
+    params: linkedAccountParam,
+    request: ReplaceLinkedAccountTokenRequestSchema,
+    response: LinkedAccountsViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  removeLinkedAccount: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/settings/linked-accounts/:accountId/remove',
+    params: linkedAccountParam,
+    request: RemoveLinkedAccountRequestSchema,
+    response: RemoveLinkedAccountResultSchema,
+    error: HostApiErrorSchema,
+  }),
+  getLinkedAccountUses: defineContract({
+    method: 'GET',
+    path: '/api/settings/linked-accounts/:accountId/uses',
+    params: linkedAccountParam,
     request: NoRequestBodySchema,
-    response: VerificationBrowserAvailabilitySchema,
+    response: LinkedAccountUsesViewSchema,
     error: HostApiErrorSchema,
   }),
-  getCommandAccounts: defineContract({
+  getCredentials: defineContract({
     method: 'GET',
-    path: '/api/settings/command-accounts',
+    path: '/api/settings/credentials',
     params: EmptyParamsSchema,
     request: NoRequestBodySchema,
-    response: CommandAccountsViewSchema,
+    response: CredentialsViewSchema,
     error: HostApiErrorSchema,
   }),
-  addCommandAccount: defineContract({
+  createCredential: defineContract({
     invalidatesSnapshot: true,
     method: 'POST',
-    path: '/api/settings/command-accounts',
+    path: '/api/settings/credentials',
     params: EmptyParamsSchema,
-    request: AddCommandAccountRequestSchema,
-    response: CommandAccountsViewSchema,
+    request: CreateCredentialRequestSchema,
+    response: CredentialsViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateCredential: defineContract({
+    invalidatesSnapshot: true,
+    method: 'PATCH',
+    path: '/api/settings/credentials/:credentialId',
+    params: credentialParam,
+    request: UpdateCredentialRequestSchema,
+    response: CredentialsViewSchema,
     error: HostApiErrorSchema,
   }),
-  replaceCommandAccountToken: defineContract({
+  replaceCredentialValue: defineContract({
     invalidatesSnapshot: true,
     method: 'PUT',
-    path: '/api/settings/command-accounts/:accountId',
-    params: z.object({ accountId: NonEmptyStringSchema.max(64) }).strict(),
-    request: AddCommandAccountRequestSchema,
-    response: CommandAccountsViewSchema,
+    path: '/api/settings/credentials/:credentialId/value',
+    params: credentialParam,
+    request: ReplaceCredentialValueRequestSchema,
+    response: CredentialsViewSchema,
     error: HostApiErrorSchema,
   }),
-  removeCommandAccount: defineContract({
+  removeCredential: defineContract({
     invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/settings/credentials/:credentialId/remove',
+    params: credentialParam,
+    request: RemoveCredentialRequestSchema,
+    response: RemoveCredentialResultSchema,
+    error: HostApiErrorSchema,
+  }),
+  getCredentialUses: defineContract({
+    method: 'GET',
+    path: '/api/settings/credentials/:credentialId/uses',
+    params: credentialParam,
+    request: NoRequestBodySchema,
+    response: CredentialUsesViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  dismissCredentialRequest: defineContract({
     method: 'DELETE',
-    path: '/api/settings/command-accounts/:accountId',
-    params: z.object({ accountId: NonEmptyStringSchema.max(64) }).strict(),
+    path: '/api/settings/credentials/requests/:requestId',
+    params: z.object({ requestId: NonEmptyStringSchema.max(64) }).strict(),
     request: NoRequestBodySchema,
-    response: CommandAccountsViewSchema,
+    response: CredentialsViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  setModelProviderAccess: defineContract({
+    invalidatesSnapshot: true,
+    method: 'PUT',
+    path: '/api/settings/credentials/model-providers/:provider',
+    params: z.object({ provider: NonEmptyStringSchema.max(128) }).strict(),
+    request: SetModelProviderAccessRequestSchema,
+    response: CredentialsViewSchema,
     error: HostApiErrorSchema,
   }),
   getChannelMemberNotes: defineContract({
@@ -3782,6 +4403,14 @@ export const HostApiContracts = {
     response: z.object({ disabled: z.literal(true) }).strict(),
     error: HostApiErrorSchema,
   }),
+  setDshPluginImageSubmission: defineContract({
+    method: 'PUT',
+    path: '/api/dsh/plugin-installs/:packageId/image-submission',
+    params: dshPluginPackageParam,
+    request: z.object({ allowed: z.boolean() }).strict(),
+    response: z.object({ allowed: z.boolean() }).strict(),
+    error: HostApiErrorSchema,
+  }),
   removeDshPluginPackage: defineContract({
     invalidatesSnapshot: true,
     method: 'DELETE',
@@ -4000,19 +4629,24 @@ export const HostApiContracts = {
         /** 排序方式，默认最近更新；游标只在同一种排序下有效。 */
         sort: CommunityExtensionSortSchema.optional(),
         cursor: z.string().max(200).optional(),
+        /** 跳过本机缓存，重新向社区读取。 */
+        refresh: z.enum(['1']).optional(),
       })
       .strict(),
     request: NoRequestBodySchema,
-    response: z.object({ items: z.array(CommunityExtensionSummarySchema), nextCursor: z.string().nullable() }).strict(),
+    response: z
+      .object({ items: z.array(CommunityExtensionSummarySchema), nextCursor: z.string().nullable() })
+      .extend(CommunityFreshnessSchema.shape)
+      .strict(),
     error: HostApiErrorSchema,
   }),
   getCommunityExtension: defineContract({
     timeoutMs: 30_000,
     method: 'GET',
     path: '/api/community/extensions/:extensionId',
-    params: z.object({ extensionId: ExtensionIdSchema }).strict(),
+    params: z.object({ extensionId: ExtensionIdSchema, refresh: z.enum(['1']).optional() }).strict(),
     request: NoRequestBodySchema,
-    response: CommunityExtensionDetailSchema,
+    response: CommunityExtensionDetailSchema.extend(CommunityFreshnessSchema.shape),
     error: HostApiErrorSchema,
   }),
   /** 下载社区发布并按包摘要校验，结果与本地文件导入的检查相同，再经 `commitExtensionImport` 确认。 */
@@ -4139,19 +4773,24 @@ export const HostApiContracts = {
         tag: z.string().trim().min(1).max(40).optional(),
         official: z.literal('1').optional(),
         cursor: z.string().min(1).max(500).optional(),
+        /** 跳过本机缓存，重新向社区读取。 */
+        refresh: z.enum(['1']).optional(),
       })
       .strict(),
     request: NoRequestBodySchema,
-    response: z.object({ items: z.array(CommunityPersonaSummarySchema), nextCursor: z.string().nullable() }).strict(),
+    response: z
+      .object({ items: z.array(CommunityPersonaSummarySchema), nextCursor: z.string().nullable() })
+      .extend(CommunityFreshnessSchema.shape)
+      .strict(),
     error: HostApiErrorSchema,
   }),
   getCommunityPersona: defineContract({
     timeoutMs: 30_000,
     method: 'GET',
     path: '/api/community/personas/:personaId',
-    params: z.object({ personaId: CommunityPersonaIdSchema }).strict(),
+    params: z.object({ personaId: CommunityPersonaIdSchema, refresh: z.enum(['1']).optional() }).strict(),
     request: NoRequestBodySchema,
-    response: CommunityPersonaDetailSchema,
+    response: CommunityPersonaDetailSchema.extend(CommunityFreshnessSchema.shape),
     error: HostApiErrorSchema,
   }),
   /**
@@ -4346,6 +4985,31 @@ export const HostApiContracts = {
     response: LlmProviderSettingsSchema,
     error: HostApiErrorSchema,
   }),
+  llmSubscriptionStatus: defineContract({
+    method: 'GET',
+    path: '/api/llm/subscriptions/:provider',
+    params: llmProviderParam,
+    request: NoRequestBodySchema,
+    response: SubscriptionStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  llmSubscriptionAction: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/llm/subscriptions/:provider',
+    params: llmProviderParam,
+    request: z.discriminatedUnion('action', [
+      z.object({ action: z.literal('use-subscription'), expectedRevision: z.number().int().nonnegative() }).strict(),
+      z.object({ action: z.enum(['login', 'cancel']) }).strict(),
+      z.object({ action: z.literal('answer'), promptId: NonEmptyStringSchema, value: z.string().max(4096) }).strict(),
+      z.object({ action: z.enum(['activate', 'remove']), accountId: NonEmptyStringSchema }).strict(),
+      z
+        .object({ action: z.literal('rename'), accountId: NonEmptyStringSchema, label: z.string().min(1).max(80) })
+        .strict(),
+    ]),
+    response: z.object({ status: SubscriptionStatusSchema, revocationConfirmed: z.boolean().optional() }).strict(),
+    error: HostApiErrorSchema,
+  }),
   llmDiscoverModels: defineContract({
     method: 'POST',
     path: '/api/llm/discover-models',
@@ -4755,6 +5419,7 @@ export const HostApiContracts = {
             extensionRevisionId: ExtensionRevisionIdSchema,
             config: JsonValueSchema,
             configuredSecrets: z.array(z.string()).optional(),
+            boundCredentials: BoundCredentialsSchema.optional(),
             activatedAt: z.number().int().safe().nonnegative(),
           })
           .strict()
@@ -4775,6 +5440,16 @@ export const HostApiContracts = {
     response: z.object({ disabled: z.literal(true), pending: ExtensionActivationTransitionSchema.optional() }).strict(),
     error: HostApiErrorSchema,
   }),
+  putAgentOutboundOrder: defineContract({
+    invalidatesSnapshot: true,
+    method: 'PUT',
+    path: '/api/agents/:agentId/outbound-order',
+    params: agentParam,
+    /** Every enabled extension that processes the agent's messages before sending, in the new order. */
+    request: z.object({ extensionIds: z.array(ExtensionIdSchema).max(64) }).strict(),
+    response: z.object({ extensionIds: z.array(ExtensionIdSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
   updateExtensionActivationConfig: defineContract({
     invalidatesSnapshot: true,
     method: 'PUT',
@@ -4785,9 +5460,17 @@ export const HostApiContracts = {
         config: JsonValueSchema,
         /** Write-only credential drafts keyed by secret field; an absent or empty draft keeps the stored one. */
         secrets: z.record(z.string(), z.string().max(8192)).optional(),
+        /** Secret fields to bind to named credentials instead of a typed value; a field takes one or the other. */
+        credentialBindings: CredentialBindingsRequestSchema.optional(),
+      })
+      .strict(),
+    response: z
+      .object({
+        config: JsonValueSchema,
+        configuredSecrets: z.array(z.string()).optional(),
+        boundCredentials: BoundCredentialsSchema.optional(),
       })
       .strict(),
-    response: z.object({ config: JsonValueSchema, configuredSecrets: z.array(z.string()).optional() }).strict(),
     error: HostApiErrorSchema,
   }),
   updateHostExtensionConfig: defineContract({
@@ -4801,9 +5484,37 @@ export const HostApiContracts = {
         config: JsonValueSchema,
         /** Write-only credential drafts keyed by secret field; an absent or empty draft keeps the stored one. */
         secrets: z.record(z.string(), z.string().max(8192)).optional(),
+        /** Secret fields to bind to named credentials instead of a typed value; a field takes one or the other. */
+        credentialBindings: CredentialBindingsRequestSchema.optional(),
+      })
+      .strict(),
+    response: z
+      .object({
+        config: JsonValueSchema,
+        configuredSecrets: z.array(z.string()).optional(),
+        boundCredentials: BoundCredentialsSchema.optional(),
       })
       .strict(),
-    response: z.object({ config: JsonValueSchema, configuredSecrets: z.array(z.string()).optional() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  /** Configuration history of one extension, newest first: the host layer and every agent's configuration. */
+  getExtensionConfigVersions: defineContract({
+    method: 'GET',
+    path: '/api/extensions/:extensionId/config-versions',
+    params: extensionParam,
+    request: NoRequestBodySchema,
+    response: z.object({ versions: z.array(ExtensionConfigVersionSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  /** Writes an earlier configuration again as a new version of the same layer (and agent). */
+  revertExtensionConfig: defineContract({
+    invalidatesSnapshot: true,
+    timeoutMs: 300_000,
+    method: 'POST',
+    path: '/api/extensions/:extensionId/config-versions/:versionId/revert',
+    params: extensionConfigVersionParam,
+    request: z.object({ reason: z.string().trim().max(500).optional() }).strict(),
+    response: z.object({ version: ExtensionConfigVersionSchema }).strict(),
     error: HostApiErrorSchema,
   }),
   installHostExtension: defineContract({
@@ -4914,6 +5625,20 @@ export const HostApiContracts = {
     response: z.object({ dismissed: z.literal(true), revision: z.string().min(1) }).strict(),
     error: HostApiErrorSchema,
   }),
+  dismissAttentionBatch: defineContract({
+    method: 'POST',
+    path: '/api/attention/dismiss',
+    params: EmptyParamsSchema,
+    request: z
+      .object({
+        ids: z.array(z.string().min(1).max(200)).max(200),
+        /** Causes to keep quiet until they recover; new items of these causes are not shown meanwhile. */
+        causes: z.array(z.string().min(1).max(200)).max(200),
+      })
+      .strict(),
+    response: z.object({ dismissed: z.literal(true), revision: z.string().min(1) }).strict(),
+    error: HostApiErrorSchema,
+  }),
   getChannelPending: defineContract({
     method: 'GET',
     path: '/api/channels/:channelId/pending',
@@ -5028,6 +5753,23 @@ export const HostApiContracts = {
     response: ExtensionLineageSchema,
     error: HostApiErrorSchema,
   }),
+  setExtensionRevisionKept: defineContract({
+    method: 'POST',
+    path: '/api/extensions/:extensionId/revisions/:revisionId/keep',
+    params: z.object({ extensionId: ExtensionIdSchema, revisionId: ExtensionRevisionIdSchema }).strict(),
+    request: z.object({ kept: z.boolean() }).strict(),
+    response: z.object({ kept: z.boolean() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  deleteExtensionRevisions: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/extensions/:extensionId/revisions/delete',
+    params: extensionParam,
+    request: z.object({ revisionIds: z.array(ExtensionRevisionIdSchema).min(1).max(200) }).strict(),
+    response: z.object({ deleted: z.number().int().nonnegative() }).strict(),
+    error: HostApiErrorSchema,
+  }),
   branchExtension: defineContract({
     invalidatesSnapshot: true,
     timeoutMs: 300_000,
@@ -5243,9 +5985,11 @@ const buildValidatedHostApiPath = (
   const consumed = new Set<string>()
   const pathname = contract.path.replace(pathParameterPattern, (_placeholder, key: string) => {
     const value = params[key]
-    if (typeof value !== 'string') throw new TypeError(`Host API path parameter ${key} must be a string.`)
+    if (typeof value !== 'string' && typeof value !== 'number') {
+      throw new TypeError(`Host API path parameter ${key} must be a string or number.`)
+    }
     consumed.add(key)
-    return encodeURIComponent(value)
+    return encodeURIComponent(String(value))
   })
   const query = new URLSearchParams()
   for (const [key, value] of Object.entries(params)) {