@nekro-nxt/contracts 0.2.0 → 0.4.0

package/src/host-api.ts

@@ -33,6 +33,8 @@ import { ConfigSchemaDocumentSchema } from './config-schema.js'
 import {
   CommunityExtensionDetailSchema,
   CommunityExtensionSummarySchema,
+  CommunityExtensionSortSchema,
+  CommunityListingInputSchema,
   CommunityReleaseIdSchema,
   CommunityReviewStatusSchema,
   CommunityStatusSchema,
@@ -42,6 +44,16 @@ import {
   CommunityMyExtensionSchema,
   CommunityReviewReportSchema,
 } from './community.js'
+import {
+  COMMUNITY_PERSONA_AVATAR_TYPES,
+  COMMUNITY_PERSONA_MAX_LENGTH,
+  CommunityMyPersonaSchema,
+  CommunityMyPersonasSchema,
+  CommunityPersonaDetailSchema,
+  CommunityPersonaIdSchema,
+  CommunityPersonaRevisionIdSchema,
+  CommunityPersonaSummarySchema,
+} from './community-personas.js'
 import {
   DshNxtHostUiSchema,
   EMPTY_EXTENSION_UI_CONTRIBUTIONS,
@@ -54,6 +66,9 @@ import {
   HostUiPageGeometryEvidenceSchema,
   HostUiPageEntrySchema,
   HostUiPermissionDeclarationSchema,
+  ExtensionPanelAnchorSchema,
+  ExtensionPermissionsSchema,
+  ExtensionProvideSchema,
 } from './extension-ui.js'
 
 const EmptyParamsSchema = z.object({}).strict()
@@ -214,6 +229,32 @@ const AgentModelSchema = z
   })
   .strict()
 
+/**
+ * An enable or disable request of one agent extension that has not settled: `waiting` until the agent reaches a safe
+ * gap (its current reply ends), or `failed` with the reason until the next request replaces it.
+ */
+/** What one approval asks the user to grant and whether the current grant already covers it. */
+export const ExtensionPermissionRequirementSchema = z
+  .object({
+    declaration: HostUiPermissionDeclarationSchema,
+    permissionDigest: z.string().regex(/^[a-f0-9]{64}$/u),
+    approvalRequired: z.boolean(),
+  })
+  .strict()
+
+export type ExtensionPermissionRequirement = z.output<typeof ExtensionPermissionRequirementSchema>
+
+export const ExtensionActivationTransitionSchema = z
+  .object({
+    agentId: AgentIdSchema,
+    target: z.enum(['enabled', 'disabled']),
+    extensionRevisionId: ExtensionRevisionIdSchema.optional(),
+    state: z.enum(['waiting', 'failed']),
+    message: z.string().optional(),
+    since: z.number().int().safe().nonnegative(),
+  })
+  .strict()
+
 export const ImageUnderstandingPolicyApiSchema = z
   .object({
     history: z
@@ -251,6 +292,10 @@ const AgentCapabilitiesSchema = z
     unrestrictedFileAccess: z.boolean(),
     /** Absent in older clients means on. */
     scheduledTasks: z.boolean().default(true),
+    /** Tools are called from one TypeScript program (`run_code`); takes effect only with `developmentShell`. */
+    codeRun: z.boolean().default(false),
+    /** Network for commands; absent in older clients means on. */
+    commandNetwork: z.boolean().default(true),
   })
   .strict()
 
@@ -345,9 +390,14 @@ const ReviseAgentRequestSchema = AgentRevisionRequestContentSchema.extend({
   validatePersonaDocumentProjection(value, context)
 })
 
-// The default that fills `scheduledTasks` for older clients must not turn it on in a partial update.
+// The defaults that fill `scheduledTasks`, `codeRun` and `commandNetwork` for older clients must not reset them in a
+// partial update.
 const UpdateAgentCapabilitiesRequestSchema = AgentCapabilitiesSchema.partial()
-  .extend({ scheduledTasks: z.boolean().optional() })
+  .extend({
+    scheduledTasks: z.boolean().optional(),
+    codeRun: z.boolean().optional(),
+    commandNetwork: z.boolean().optional(),
+  })
   .strict()
   .refine((value) => Object.values(value).some((entry) => entry !== undefined), '至少提供一个能力。')
 
@@ -393,7 +443,15 @@ export const HostSnapshotMessageSchema = z
     channelId: ChannelIdSchema,
     role: z.enum(['member', 'agent', 'system']),
     parts: z.array(SnapshotMessagePartSchema),
-    sender: z.object({ memberId: ChannelMemberIdSchema, displayName: z.string().optional() }).strict().optional(),
+    sender: z
+      .object({
+        memberId: ChannelMemberIdSchema,
+        displayName: z.string().optional(),
+        /** The sender is the account of this agent on this host, answering the channel through another connection. */
+        localAgentId: AgentIdSchema.optional(),
+      })
+      .strict()
+      .optional(),
     mentionedConnectionAccount: z.boolean().optional(),
     activityKey: AdapterActivityKeySchema.optional(),
     targetLogicalMessageId: LogicalMessageIdSchema.optional(),
@@ -521,17 +579,25 @@ export const ChannelRuntimeUsageSchema = z
   })
   .strict()
 
+const channelRuntimeToolFields = {
+  callId: NonEmptyStringSchema,
+  name: NonEmptyStringSchema,
+  displayName: NonEmptyStringSchema,
+  state: z.enum(['running', 'succeeded', 'failed']),
+  inputPreview: z.string().optional(),
+  resultPreview: z.string().optional(),
+  wroteToChannel: z.boolean().optional(),
+  deliveryState: z.enum(['sent', 'partially-sent', 'failed', 'unknown']).optional(),
+  durationMs: z.number().int().nonnegative().optional(),
+}
+
 export const ChannelRuntimeToolSchema = z
   .object({
-    callId: NonEmptyStringSchema,
-    name: NonEmptyStringSchema,
-    displayName: NonEmptyStringSchema,
-    state: z.enum(['running', 'succeeded', 'failed']),
-    inputPreview: z.string().optional(),
-    resultPreview: z.string().optional(),
-    wroteToChannel: z.boolean().optional(),
-    deliveryState: z.enum(['sent', 'partially-sent', 'failed', 'unknown']).optional(),
-    durationMs: z.number().int().nonnegative().optional(),
+    ...channelRuntimeToolFields,
+    /** Source of a `run_code` program. */
+    code: z.string().optional(),
+    /** Tools a `run_code` program called, in the order they started. */
+    children: z.array(z.object(channelRuntimeToolFields).strict()).optional(),
   })
   .strict()
 
@@ -553,6 +619,19 @@ export const ChannelRuntimeStepSchema = z
   })
   .strict()
 
+/** One message that entered the model's input during a turn: channel admissions and host or DSH injections. */
+export const ChannelRuntimeInputSchema = z
+  .object({
+    messageId: z.string().min(1),
+    /** DSH `user/message` source kind, e.g. `nekro-nxt-channel` or `nekro-nxt-handoff`. */
+    source: z.string().min(1),
+    /** Channel Events carried by a channel admission. */
+    eventCount: z.number().int().positive().optional(),
+    preview: z.string().optional(),
+    at: z.number().int().safe().nonnegative().optional(),
+  })
+  .strict()
+
 export const ChannelRuntimeTurnSchema = z
   .object({
     turn: z.number().int().nonnegative(),
@@ -568,6 +647,8 @@ export const ChannelRuntimeTurnSchema = z
     endedAt: z.number().int().safe().nonnegative().optional(),
     /** Newest Channel Event of the admission that opened this turn; absent for non-channel turns. */
     triggerEventId: ChannelEventIdSchema.optional(),
+    /** Messages that entered the model's input during the turn, in log order; absent when there were none. */
+    inputs: z.array(ChannelRuntimeInputSchema).optional(),
   })
   .strict()
 
@@ -583,6 +664,8 @@ export const ChannelRuntimeOccupancySchema = z
       })
       .strict()
       .optional(),
+    /** Pictures in the conversation; their tokens are not in the breakdown, so they make up most of the rest. */
+    imageCount: z.number().int().nonnegative().optional(),
   })
   .strict()
 
@@ -658,6 +741,54 @@ export const ChannelRuntimePerformanceSchema = z
   })
   .strict()
 
+/** What the agent remembered or looked up, newest first; the admin sees it, the model does not. */
+export const ChannelMemoryActivitySchema = z.discriminatedUnion('kind', [
+  z
+    .object({
+      kind: z.literal('backlog-folded'),
+      at: z.number().nonnegative().optional(),
+      foldedCount: z.number().int().nonnegative(),
+      shownCount: z.number().int().nonnegative(),
+      foldedImageCount: z.number().int().nonnegative(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('history-search'),
+      at: z.number().nonnegative().optional(),
+      query: z.string(),
+      hits: z.number().int().nonnegative(),
+      sender: z.string().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('notes-updated'),
+      at: z.number().nonnegative().optional(),
+      revision: z.number().int().nonnegative(),
+      chars: z.number().int().nonnegative(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('member-notes-updated'),
+      at: z.number().nonnegative().optional(),
+      memberId: z.string(),
+      name: z.string().optional(),
+      chars: z.number().int().nonnegative(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('idle-review'),
+      at: z.number().nonnegative().optional(),
+      quietMinutes: z.number().int().nonnegative(),
+    })
+    .strict(),
+])
+
+export type ChannelMemoryActivity = z.output<typeof ChannelMemoryActivitySchema>
+
 export const ChannelRuntimeProjectionSchema = z
   .object({
     channelId: ChannelIdSchema,
@@ -669,6 +800,7 @@ export const ChannelRuntimeProjectionSchema = z
     occupancy: ChannelRuntimeOccupancySchema.optional(),
     cache: ChannelRuntimeCacheSchema.optional(),
     performance: ChannelRuntimePerformanceSchema.optional(),
+    memory: z.array(ChannelMemoryActivitySchema).optional(),
     turns: z.array(ChannelRuntimeTurnSchema),
   })
   .strict()
@@ -678,6 +810,201 @@ export const ChannelRuntimeSseDataSchema = ChannelRuntimeProjectionSchema.extend
   truncated: z.boolean().optional(),
 }).strict()
 
+export const ChannelRuntimeContextSchema = z
+  .object({
+    available: z.boolean(),
+    route: z
+      .object({
+        provider: z.string(),
+        model: z.string(),
+        contextWindow: z.number().int().positive().optional(),
+        reasoningEffort: z.string().optional(),
+        temperature: z.number().optional(),
+        maxTokens: z.number().int().positive().optional(),
+      })
+      .strict()
+      .optional(),
+    instructions: z.array(
+      z.object({ role: z.enum(['system', 'developer']), text: z.string(), truncated: z.boolean() }).strict(),
+    ),
+    tools: z.array(
+      z.object({ name: z.string(), description: z.string().optional(), parameters: z.string().optional() }).strict(),
+    ),
+    changes: z.array(
+      z
+        .object({
+          at: z.number().nonnegative().optional(),
+          reason: z.enum(['initial', 'resume', 'change', 'series']),
+          toolCount: z.number().int().nonnegative(),
+        })
+        .strict(),
+    ),
+  })
+  .strict()
+
+const ChannelPromptPartSchema = z
+  .object({
+    document: PromptDocumentV1Schema,
+    /** Notes only: the agent may not rewrite them. */
+    locked: z.boolean(),
+    /** 0 before the first save; send it back as `expectedRevision`. */
+    revision: z.number().int().nonnegative(),
+    maxChars: z.number().int().positive(),
+    updatedBy: z.enum(['admin', 'agent']).optional(),
+    updatedAt: z.number().int().nonnegative().optional(),
+    revisions: z.array(
+      z
+        .object({
+          revision: z.number().int().positive(),
+          document: PromptDocumentV1Schema,
+          updatedBy: z.enum(['admin', 'agent']),
+          updatedAt: z.number().int().nonnegative(),
+        })
+        .strict(),
+    ),
+  })
+  .strict()
+
+/**
+ * What the agent answering a channel reads about it, each part with recent earlier versions to restore: the admin's
+ * instructions (system prompt) and the agent's own notes (runtime context).
+ */
+export const ChannelPromptViewSchema = z
+  .object({ instructions: ChannelPromptPartSchema, notes: ChannelPromptPartSchema })
+  .strict()
+
+/**
+ * How much of a channel's unread backlog reaches the agent at once, and when it looks back on its own. Uncertain
+ * trade-offs stay per channel: a busy meme group and a long tabletop session want different budgets.
+ */
+export const ChannelContextPolicySchema = z
+  .object({
+    /** Text characters of a backlog read message by message; older messages collapse into one line. 0: no limit. */
+    backlogTextChars: z.number().int().nonnegative().max(1_000_000),
+    /** Backlog images shown as pictures, newest first; the rest stay references the agent can open. */
+    backlogImages: z.number().int().nonnegative().max(20),
+    /** Quiet minutes after which the agent reviews the conversation and updates its notes. 0: off. */
+    idleReviewMinutes: z
+      .number()
+      .int()
+      .nonnegative()
+      .max(24 * 60),
+  })
+  .strict()
+
+export type ChannelContextPolicy = z.output<typeof ChannelContextPolicySchema>
+
+export const DEFAULT_CHANNEL_CONTEXT_POLICY: ChannelContextPolicy = Object.freeze({
+  backlogTextChars: 40_000,
+  backlogImages: 6,
+  idleReviewMinutes: 45,
+})
+
+export const ChannelContextPolicyViewSchema = z
+  .object({
+    policy: ChannelContextPolicySchema,
+    defaults: ChannelContextPolicySchema,
+    /** False while the channel follows the defaults. */
+    custom: z.boolean(),
+  })
+  .strict()
+
+export type ChannelContextPolicyView = z.output<typeof ChannelContextPolicyViewSchema>
+
+/** Whether a newer release exists on the build's own channel; development builds are never compared. */
+export const ProductUpdateStatusSchema = z
+  .object({
+    channel: z.enum(['stable', 'preview', 'development']),
+    currentVersion: z.string(),
+    /** Short commit of a release build. */
+    currentCommit: z.string().optional(),
+    state: z.enum(['unknown', 'up-to-date', 'available', 'failed', 'unsupported']),
+    latest: z
+      .object({
+        version: z.string(),
+        commit: z.string().optional(),
+        url: z.string().url(),
+        publishedAt: z.number().int().nonnegative().optional(),
+      })
+      .strict()
+      .optional(),
+    checkedAt: z.number().int().nonnegative().optional(),
+    error: z.string().optional(),
+    autoCheck: z.boolean(),
+  })
+  .strict()
+
+export type ProductUpdateStatus = z.output<typeof ProductUpdateStatusSchema>
+
+/** Pause between consecutive messages an agent sends to one channel; longer messages wait a little longer. */
+export const MessagePacingSchema = z.enum(['off', 'fast', 'normal', 'slow'])
+
+export type MessagePacing = z.output<typeof MessagePacingSchema>
+
+export const DEFAULT_MESSAGE_PACING: MessagePacing = 'normal'
+
+export const MessagePacingSettingsSchema = z.object({ pacing: MessagePacingSchema }).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>
+
+/** Search used by extension indexes (表情包与扩展素材能力 §6.4). */
+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(),
+        embedded: z.number().int().nonnegative(),
+        state: z.enum(['idle', 'running', 'ready']),
+        error: z.string().optional(),
+      })
+      .strict(),
+  })
+  .strict()
+export type RetrievalStatus = z.output<typeof RetrievalStatusSchema>
+
+/** What the agent keeps about individual members of one channel; each note comes with that member's messages. */
+export const ChannelMemberNotesViewSchema = z
+  .object({
+    notes: z.array(
+      z
+        .object({
+          memberId: ChannelMemberIdSchema,
+          displayName: z.string().optional(),
+          text: z.string(),
+          updatedBy: z.enum(['admin', 'agent']),
+          updatedAt: z.number().int().nonnegative(),
+        })
+        .strict(),
+    ),
+    maxChars: z.number().int().positive(),
+  })
+  .strict()
+
+export type ChannelMemberNotesView = z.output<typeof ChannelMemberNotesViewSchema>
+
 export type ChannelRuntimePhase = z.output<typeof ChannelRuntimePhaseSchema>
 export type ChannelRuntimeUsage = z.output<typeof ChannelRuntimeUsageSchema>
 export type ChannelRuntimeOccupancy = z.output<typeof ChannelRuntimeOccupancySchema>
@@ -686,6 +1013,9 @@ export type ChannelRuntimeCache = z.output<typeof ChannelRuntimeCacheSchema>
 export type ChannelRuntimePerformanceSample = z.output<typeof ChannelRuntimePerformanceSampleSchema>
 export type ChannelRuntimePerformance = z.output<typeof ChannelRuntimePerformanceSchema>
 export type ChannelRuntimeProjection = z.output<typeof ChannelRuntimeProjectionSchema>
+export type ChannelRuntimeContext = z.output<typeof ChannelRuntimeContextSchema>
+export type ChannelRuntimeInput = z.output<typeof ChannelRuntimeInputSchema>
+export type ChannelPromptView = z.output<typeof ChannelPromptViewSchema>
 export type ChannelRuntimeSseData = z.output<typeof ChannelRuntimeSseDataSchema>
 export type ChannelFactSseData = z.output<typeof ChannelFactSseDataSchema>
 
@@ -716,6 +1046,7 @@ const AdapterConnectionDescriptorSchema = z
           icon: HostIconNameSchema.optional(),
           triggerable: z.boolean(),
           channelKinds: z.array(z.enum(['internal', 'direct', 'group'])).optional(),
+          directedAt: z.enum(['member', 'message']).optional(),
         })
         .strict(),
     ),
@@ -959,6 +1290,27 @@ 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
+  .object({
+    available: z.boolean(),
+    source: z.enum(['host', 'system', 'downloaded']).optional(),
+    version: z.string().optional(),
+    download: 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(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+
+export type CodeRunAvailability = z.output<typeof CodeRunAvailabilitySchema>
+
 export const HostSnapshotSchema = z
   .object({
     upgrade: HostUpgradeSummarySchema.optional(),
@@ -991,6 +1343,10 @@ export const HostSnapshotSchema = z
     capabilityAvailability: z
       .object({
         subagents: z.object({ available: z.boolean() }).strict(),
+        /** Optional in older hosts, which never offer `run_code`. */
+        codeRun: CodeRunAvailabilitySchema.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({
             provider: z.literal('deepseek-official'),
@@ -1074,6 +1430,8 @@ export const HostSnapshotSchema = z
           boundAgentId: AgentIdSchema.optional(),
           runtimePhase: ChannelRuntimePhaseSchema.default('idle'),
           activity: ChannelActivitySummarySchema.default({ unreadCount: 0, unreadCapped: false }),
+          /** Other agents on this host that answer the same platform channel through another connection; absent when none. */
+          localAgentIds: z.array(AgentIdSchema).min(1).optional(),
           bindings: z.array(
             z
               .object({
@@ -1081,6 +1439,8 @@ export const HostSnapshotSchema = z
                 agentId: AgentIdSchema,
                 triggerPolicy: TriggerPolicySchema,
                 processingFeedback: z.enum(['auto', 'off']).default('auto'),
+                /** Absent means `observe`. */
+                localAgentMessages: z.enum(['observe', 'trigger']).optional(),
                 activityTriggerOverrides: ActivityTriggerOverridesSchema.default({}),
                 boundAt: z.number().int().safe().nonnegative(),
               })
@@ -1160,7 +1520,8 @@ export const HostSnapshotSchema = z
       z
         .object({
           id: ExtensionIdSchema,
-          scope: z.enum(['agent', 'host-adapter', 'host-ui']),
+          /** What the latest Revision provides; listing and filtering only. */
+          provides: z.array(ExtensionProvideSchema),
           slug: NonEmptyStringSchema,
           displayName: z.string(),
           description: z.string(),
@@ -1172,11 +1533,21 @@ export const HostSnapshotSchema = z
                 revisionNumber: z.number().int().positive(),
                 format: z.enum(['current', 'unavailable']).optional(),
                 ui: ExtensionUiContributionsSchema.default(EMPTY_EXTENSION_UI_CONTRIBUTIONS),
-                configSchema: ConfigSchemaDocumentSchema.optional(),
+                /** The host instance's configuration form (`config.host`). */
+                hostConfigSchema: ConfigSchemaDocumentSchema.optional(),
+                /** Each enabled agent's configuration form (`config.agent`). */
+                agentConfigSchema: ConfigSchemaDocumentSchema.optional(),
+                /** 扩展包自带图标的读取路径（同源、按摘要寻址、可长期缓存）；没有图标时缺省。 */
+                iconUrl: z
+                  .string()
+                  .regex(/^\/api\/extensions\/[^/]+\/revisions\/[^/]+\/icon\/[a-f0-9]{64}\.(?:svg|png|webp)$/u)
+                  .optional(),
                 createdAt: z.number().int().safe().nonnegative(),
-                /** 从社区安装的保存记录的来源；本机保存与文件导入没有来源。 */
+                /** 从社区安装的版本的来源；本机保存与文件导入没有来源。 */
                 source: CommunitySourceSchema.optional(),
-                scope: z.enum(['agent', 'host-adapter', 'host-ui']),
+                provides: z.array(ExtensionProvideSchema),
+                /** Whether this Revision can be enabled for agents (agent-layer contributions or capabilities). */
+                agentLayer: z.boolean(),
                 contributions: z.array(z.string()),
                 verification: z
                   .object({
@@ -1194,12 +1565,11 @@ export const HostSnapshotSchema = z
                     renderedPages: z.array(HostPageContributionSchema).max(8).optional(),
                     usedUiComponents: z.array(HostUiKitComponentNameSchema).optional(),
                     pageGeometry: z.array(HostUiPageGeometryEvidenceSchema).max(8).optional(),
-                    permissions: HostUiPermissionDeclarationSchema.optional(),
-                    permissionDigest: z
-                      .string()
-                      .regex(/^[a-f0-9]{64}$/u)
-                      .optional(),
-                    permissionApprovalRequired: z.boolean().optional(),
+                    permissions: ExtensionPermissionsSchema.optional(),
+                    /** Installing this Revision on the machine, against the current host grant. */
+                    hostPermission: ExtensionPermissionRequirementSchema.optional(),
+                    /** Enabling this Revision for an agent that has no grant yet. */
+                    agentPermission: ExtensionPermissionRequirementSchema.optional(),
                     adapter: z
                       .object({
                         apiVersion: z.literal(2),
@@ -1253,11 +1623,15 @@ export const HostSnapshotSchema = z
               })
               .strict(),
           ),
+          /** Present only while some agent's enable or disable request is waiting or has failed. */
+          activationTransitions: z.array(ExtensionActivationTransitionSchema).optional(),
           installation: z
             .object({
               extensionRevisionId: ExtensionRevisionIdSchema,
               installedAt: z.number().int().safe().nonnegative(),
+              /** Secret fields are removed; `configuredSecrets` lists those the Host stores. */
               config: JsonValueSchema.default({}),
+              configuredSecrets: z.array(z.string()).optional(),
               runtime: z
                 .object({
                   status: z.enum(['active', 'restore-failed', 'dispose-failed']),
@@ -1268,14 +1642,8 @@ export const HostSnapshotSchema = z
             })
             .strict()
             .optional(),
-          hostUiPermission: z
-            .object({
-              declaration: HostUiPermissionDeclarationSchema,
-              permissionDigest: z.string().regex(/^[a-f0-9]{64}$/u),
-              approvalRequired: z.boolean(),
-            })
-            .strict()
-            .optional(),
+          /** Installing the latest Revision on this machine, against the current host grant. */
+          hostPermission: ExtensionPermissionRequirementSchema.optional(),
           hostClientDiagnostic: z
             .object({
               revisionId: ExtensionRevisionIdSchema,
@@ -1618,6 +1986,22 @@ export const LlmProviderCredentialSchema = z
   .object({ configured: z.boolean(), source: z.string().optional(), writable: z.boolean() })
   .strict()
 
+/**
+ * The latest connection test that still describes the provider's saved address, protocol and API key. Tests made
+ * before one of those changed are dropped. Never carries a key, request or response body.
+ */
+export const LlmProviderTestResultSchema = z
+  .object({
+    /** Epoch milliseconds when the test finished. */
+    at: z.number().int().nonnegative(),
+    ok: z.boolean(),
+    /** Short failure reason shown to the user; absent when the test passed. */
+    message: z.string().max(240).optional(),
+    /** The model the test asked. */
+    model: NonEmptyStringSchema.optional(),
+  })
+  .strict()
+
 export const LlmProviderViewSchema = z
   .object({
     provider: NonEmptyStringSchema,
@@ -1636,6 +2020,8 @@ export const LlmProviderViewSchema = z
     modelsCustomized: z.boolean(),
     /** The provider's adapter can list the models its endpoint offers. */
     discoverable: z.boolean(),
+    /** `null` when the current configuration was never tested; absent from hosts that do not record tests. */
+    lastTest: LlmProviderTestResultSchema.nullable().optional(),
   })
   .strict()
 
@@ -1715,7 +2101,7 @@ export const ExtensionImportInspectionSchema = z
     revisionId: ExtensionRevisionIdSchema,
     slug: NonEmptyStringSchema,
     displayName: NonEmptyStringSchema,
-    scope: z.enum(['agent', 'host-adapter', 'host-ui']),
+    provides: z.array(ExtensionProvideSchema),
     idempotent: z.boolean(),
     slugConflict: z.boolean(),
   })
@@ -1775,6 +2161,8 @@ export type AgentRevisionHistory = z.output<typeof AgentRevisionHistorySchema>
 const channelParam = z.object({ channelId: ChannelIdSchema }).strict()
 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()
 const extensionParam = z.object({ extensionId: ExtensionIdSchema }).strict()
 const dshPluginPackageParam = z.object({ packageId: DshPluginPackageIdSchema }).strict()
 const dshPluginEntryParam = z.object({ entryId: DshPluginEntryIdSchema }).strict()
@@ -2110,6 +2498,8 @@ export const HostApiContracts = {
         channelId: ChannelIdSchema,
         triggerPolicy: TriggerPolicySchema,
         processingFeedback: z.enum(['auto', 'off']).optional(),
+        /** 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(),
       })
       .strict(),
@@ -2119,6 +2509,7 @@ export const HostApiContracts = {
         agentId: AgentIdSchema,
         triggerPolicy: TriggerPolicySchema,
         processingFeedback: z.enum(['auto', 'off']).default('auto'),
+        localAgentMessages: z.enum(['observe', 'trigger']).optional(),
         activityTriggerOverrides: ActivityTriggerOverridesSchema.default({}),
         boundAt: z.number().int().safe().nonnegative(),
       })
@@ -2215,6 +2606,183 @@ export const HostApiContracts = {
       .strict(),
     error: HostApiErrorSchema,
   }),
+  getChannelRuntimeContext: defineContract({
+    method: 'GET',
+    path: '/api/channels/:channelId/runtime/context',
+    params: channelParam,
+    request: NoRequestBodySchema,
+    // What the live session sends the model: route, rendered instructions and tool schemas. Read on demand; the runtime
+    // projection pushed over SSE never carries it. `available: false` when no session of the channel is in memory.
+    response: ChannelRuntimeContextSchema,
+    error: HostApiErrorSchema,
+  }),
+  getChannelRuntimeInput: defineContract({
+    method: 'GET',
+    path: '/api/channels/:channelId/runtime/inputs/:messageId',
+    params: z.object({ channelId: ChannelIdSchema, messageId: z.string().trim().min(1).max(200) }).strict(),
+    request: NoRequestBodySchema,
+    // The full text of one input message as the model received it; the runtime projection only carries a preview.
+    // `available: false` when the session has left memory.
+    response: z
+      .object({
+        messageId: z.string(),
+        available: z.boolean(),
+        source: z.string().optional(),
+        text: z.string().optional(),
+        truncated: z.boolean(),
+      })
+      .strict(),
+    error: HostApiErrorSchema,
+  }),
+  getChannelPrompt: defineContract({
+    method: 'GET',
+    path: '/api/channels/:channelId/prompt',
+    params: channelParam,
+    request: NoRequestBodySchema,
+    response: ChannelPromptViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateChannelPrompt: defineContract({
+    method: 'PUT',
+    path: '/api/channels/:channelId/prompt',
+    params: channelParam,
+    request: z
+      .object({
+        kind: z.enum(['instructions', 'notes']),
+        document: PromptDocumentV1Schema,
+        /** Notes only; ignored for instructions. */
+        locked: z.boolean(),
+        /** The revision the edit started from; a newer stored revision rejects the save. */
+        expectedRevision: z.number().int().nonnegative(),
+      })
+      .strict(),
+    response: ChannelPromptViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  getProductUpdates: defineContract({
+    method: 'GET',
+    path: '/api/product/updates',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: ProductUpdateStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  checkProductUpdates: defineContract({
+    method: 'POST',
+    path: '/api/product/updates/check',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: ProductUpdateStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateProductUpdateSettings: defineContract({
+    method: 'PUT',
+    path: '/api/product/updates/settings',
+    params: EmptyParamsSchema,
+    request: z.object({ autoCheck: z.boolean() }).strict(),
+    response: ProductUpdateStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  getMessagePacingSettings: defineContract({
+    method: 'GET',
+    path: '/api/settings/message-pacing',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: MessagePacingSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateMessagePacingSettings: defineContract({
+    method: 'PUT',
+    path: '/api/settings/message-pacing',
+    params: EmptyParamsSchema,
+    request: MessagePacingSettingsSchema,
+    response: MessagePacingSettingsSchema,
+    error: HostApiErrorSchema,
+  }),
+  getRetrievalStatus: defineContract({
+    method: 'GET',
+    path: '/api/settings/retrieval',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: RetrievalStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateRetrievalMode: defineContract({
+    method: 'PUT',
+    path: '/api/settings/retrieval',
+    params: EmptyParamsSchema,
+    request: z.object({ mode: RetrievalModeSchema }).strict(),
+    response: RetrievalStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  downloadRetrievalModel: defineContract({
+    method: 'POST',
+    path: '/api/settings/retrieval/model/download',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: RetrievalStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  removeRetrievalModel: defineContract({
+    method: 'DELETE',
+    path: '/api/settings/retrieval/model',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: RetrievalStatusSchema,
+    error: HostApiErrorSchema,
+  }),
+  downloadCodeRunNode: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/runtimes/code-run-node/download',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CodeRunAvailabilitySchema,
+    error: HostApiErrorSchema,
+  }),
+  removeCodeRunNode: defineContract({
+    invalidatesSnapshot: true,
+    method: 'DELETE',
+    path: '/api/runtimes/code-run-node',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CodeRunAvailabilitySchema,
+    error: HostApiErrorSchema,
+  }),
+  getChannelMemberNotes: defineContract({
+    method: 'GET',
+    path: '/api/channels/:channelId/member-notes',
+    params: channelParam,
+    request: NoRequestBodySchema,
+    response: ChannelMemberNotesViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateChannelMemberNote: defineContract({
+    method: 'PUT',
+    path: '/api/channels/:channelId/member-notes/:memberId',
+    params: z.object({ channelId: ChannelIdSchema, memberId: ChannelMemberIdSchema }).strict(),
+    /** An empty text forgets the member. */
+    request: z.object({ text: z.string().max(2000) }).strict(),
+    response: ChannelMemberNotesViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  getChannelContextPolicy: defineContract({
+    method: 'GET',
+    path: '/api/channels/:channelId/context-policy',
+    params: channelParam,
+    request: NoRequestBodySchema,
+    response: ChannelContextPolicyViewSchema,
+    error: HostApiErrorSchema,
+  }),
+  updateChannelContextPolicy: defineContract({
+    method: 'PUT',
+    path: '/api/channels/:channelId/context-policy',
+    params: channelParam,
+    /** `null` returns the channel to the defaults. */
+    request: z.object({ policy: ChannelContextPolicySchema.nullable() }).strict(),
+    response: ChannelContextPolicyViewSchema,
+    error: HostApiErrorSchema,
+  }),
   resetChannelContext: defineContract({
     invalidatesSnapshot: true,
     method: 'POST',
@@ -2528,7 +3096,11 @@ export const HostApiContracts = {
     params: z
       .object({
         query: z.string().trim().max(80).optional(),
-        scope: z.enum(['agent', 'host-adapter', 'host-ui']).optional(),
+        provides: ExtensionProvideSchema.optional(),
+        /** 只列社区后台认定的官方扩展。 */
+        official: z.enum(['1']).optional(),
+        /** 排序方式，默认最近更新；游标只在同一种排序下有效。 */
+        sort: CommunityExtensionSortSchema.optional(),
         cursor: z.string().max(200).optional(),
       })
       .strict(),
@@ -2643,6 +3215,8 @@ export const HostApiContracts = {
         extensionId: ExtensionIdSchema,
         revisionId: ExtensionRevisionIdSchema,
         notes: z.string().max(2000),
+        /** 作者填写的条目信息；省略的字段不改动社区上已有的内容。 */
+        listing: CommunityListingInputSchema.optional(),
       })
       .strict(),
     response: z
@@ -2656,6 +3230,114 @@ export const HostApiContracts = {
       .strict(),
     error: HostApiErrorSchema,
   }),
+  listCommunityPersonas: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/personas',
+    params: z
+      .object({
+        query: z.string().trim().min(1).max(200).optional(),
+        tag: z.string().trim().min(1).max(40).optional(),
+        official: z.literal('1').optional(),
+        cursor: z.string().min(1).max(500).optional(),
+      })
+      .strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ items: z.array(CommunityPersonaSummarySchema), nextCursor: z.string().nullable() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  getCommunityPersona: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/personas/:personaId',
+    params: z.object({ personaId: CommunityPersonaIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityPersonaDetailSchema,
+    error: HostApiErrorSchema,
+  }),
+  /**
+   * 把社区人设装进本机：新建一个智能体，或为现有智能体保存一次只换设定（及可选名称）的新配置。头像下载后作为
+   * 智能体头像；下载失败不影响安装。`expectedRevisionId` 是用户看过的修订，社区已更新时拒绝，避免装入未看过的内容。
+   */
+  installCommunityPersona: defineContract({
+    invalidatesSnapshot: true,
+    timeoutMs: 60_000,
+    method: 'POST',
+    path: '/api/community/personas/:personaId/install',
+    params: z.object({ personaId: CommunityPersonaIdSchema }).strict(),
+    request: z.discriminatedUnion('target', [
+      z
+        .object({
+          target: z.literal('new'),
+          expectedRevisionId: CommunityPersonaRevisionIdSchema,
+          displayName: z.string().trim().min(1).max(80),
+          model: AgentModelSchema,
+          useAvatar: z.boolean(),
+        })
+        .strict(),
+      z
+        .object({
+          target: z.literal('replace'),
+          expectedRevisionId: CommunityPersonaRevisionIdSchema,
+          agentId: AgentIdSchema,
+          expectedCurrentRevisionId: AgentRevisionIdSchema,
+          /** 同时改名；省略时保留原名称。 */
+          displayName: z.string().trim().min(1).max(80).optional(),
+          useAvatar: z.boolean(),
+        })
+        .strict(),
+    ]),
+    response: z
+      .object({
+        agentId: AgentIdSchema,
+        channelId: ChannelIdSchema.nullable(),
+        currentRevisionId: AgentRevisionIdSchema,
+        avatar: z.enum(['applied', 'none', 'failed']),
+      })
+      .strict(),
+    error: HostApiErrorSchema,
+  }),
+  listCommunityMyPersonas: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/mine/personas',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CommunityMyPersonasSchema,
+    error: HostApiErrorSchema,
+  }),
+  /** 把智能体的设定分享到社区；带 `personaId` 时更新自己已发布的人设（生成新修订并重新审查）。 */
+  publishCommunityPersona: defineContract({
+    timeoutMs: 60_000,
+    method: 'POST',
+    path: '/api/community/personas/publish',
+    params: EmptyParamsSchema,
+    request: z
+      .object({
+        agentId: AgentIdSchema,
+        personaId: CommunityPersonaIdSchema.optional(),
+        name: z.string().trim().min(1).max(80),
+        summary: z.string().trim().min(1).max(200),
+        description: z.string().max(20_000),
+        tags: z.array(z.string().trim().min(1).max(40)).max(16),
+        persona: z.string().trim().min(1).max(COMMUNITY_PERSONA_MAX_LENGTH),
+        notes: z.string().max(2000).optional(),
+        /** 页面缩放后的头像（Base64）；省略时不上传头像，更新时保留社区上的原头像。 */
+        avatar: z
+          .object({
+            mediaType: z.enum(COMMUNITY_PERSONA_AVATAR_TYPES),
+            base64: z
+              .string()
+              .min(1)
+              .max(Math.ceil((512 * 1024 * 4) / 3) + 4),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict(),
+    response: CommunityMyPersonaSchema,
+    error: HostApiErrorSchema,
+  }),
   testMcpServer: defineContract({
     timeoutMs: 30_000,
     method: 'POST',
@@ -3112,8 +3794,19 @@ export const HostApiContracts = {
     method: 'POST',
     path: '/api/extensions/:extensionId/revisions/:revisionId/call',
     params: extensionRevisionParam,
+    /**
+     * A panel's call to its extension's host instance. The Host checks the anchor (the agent has the extension
+     * enabled; the channel or connection exists) and hands the extension the resolved caller.
+     */
     request: z
-      .object({ agentId: AgentIdSchema, method: NonEmptyStringSchema, input: JsonValueSchema.optional() })
+      .object({
+        /** Absent: the call comes from the extension itself, like a page call. */
+        anchor: z.object({ kind: ExtensionPanelAnchorSchema, id: NonEmptyStringSchema }).strict().optional(),
+        /** The agent the panel is shown for; must be the responding agent of an anchored channel. */
+        agentId: AgentIdSchema.optional(),
+        method: NonEmptyStringSchema,
+        input: JsonValueSchema.optional(),
+      })
       .strict(),
     response: z.object({ value: JsonValueSchema }).strict(),
     error: HostApiErrorSchema,
@@ -3148,12 +3841,16 @@ export const HostApiContracts = {
     request: z
       .object({
         revisionId: ExtensionRevisionIdSchema,
-        permissionApproval: z
-          .object({ permissionDigest: z.string().regex(/^[a-f0-9]{64}$/u) })
-          .strict()
-          .optional(),
+        /** Approval of the agent-layer capabilities. */
+        permissionApproval: PermissionApprovalSchema.optional(),
+        /** Approval of the host layer when enabling also installs or switches the extension on this machine. */
+        hostPermissionApproval: PermissionApprovalSchema.optional(),
       })
       .strict(),
+    /**
+     * The committed Activation, or — while the agent is still replying — `pending` with the accepted request; it then
+     * takes effect at the agent's next safe gap and its progress appears in the snapshot's `activationTransitions`.
+     */
     response: z
       .object({
         activation: z
@@ -3165,9 +3862,12 @@ export const HostApiContracts = {
             configuredSecrets: z.array(z.string()).optional(),
             activatedAt: z.number().int().safe().nonnegative(),
           })
-          .strict(),
+          .strict()
+          .optional(),
+        pending: ExtensionActivationTransitionSchema.optional(),
       })
-      .strict(),
+      .strict()
+      .refine((value) => (value.activation === undefined) !== (value.pending === undefined), '启用结果必须二选一。'),
     error: HostApiErrorSchema,
   }),
   deactivateExtension: defineContract({
@@ -3176,7 +3876,8 @@ export const HostApiContracts = {
     path: '/api/agents/:agentId/extensions/:extensionId/activation',
     params: agentExtensionParam,
     request: NoRequestBodySchema,
-    response: z.object({ disabled: z.literal(true) }).strict(),
+    /** `pending` is present when the agent is still replying; the Activation is removed at its next safe gap. */
+    response: z.object({ disabled: z.literal(true), pending: ExtensionActivationTransitionSchema.optional() }).strict(),
     error: HostApiErrorSchema,
   }),
   updateExtensionActivationConfig: defineContract({
@@ -3200,8 +3901,14 @@ export const HostApiContracts = {
     method: 'PUT',
     path: '/api/extensions/:extensionId/installation/config',
     params: extensionParam,
-    request: z.object({ config: JsonValueSchema }).strict(),
-    response: z.object({ config: JsonValueSchema }).strict(),
+    request: z
+      .object({
+        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(),
+      })
+      .strict(),
+    response: z.object({ config: JsonValueSchema, configuredSecrets: z.array(z.string()).optional() }).strict(),
     error: HostApiErrorSchema,
   }),
   installHostExtension: defineContract({
@@ -3213,10 +3920,10 @@ export const HostApiContracts = {
     request: z
       .object({
         revisionId: ExtensionRevisionIdSchema,
-        permissionApproval: z
-          .object({ permissionDigest: z.string().regex(/^[a-f0-9]{64}$/u) })
-          .strict()
-          .optional(),
+        /** Approval of the host layer (browser permissions and `permissions.host`). */
+        permissionApproval: PermissionApprovalSchema.optional(),
+        /** Approval of expanded agent-layer capabilities for the agents that move to this Revision. */
+        agentPermissionApproval: PermissionApprovalSchema.optional(),
       })
       .strict(),
     response: z