@nekro-nxt/contracts 0.1.0 → 0.3.0

package/src/host-api.ts

@@ -33,10 +33,27 @@ import { ConfigSchemaDocumentSchema } from './config-schema.js'
 import {
   CommunityExtensionDetailSchema,
   CommunityExtensionSummarySchema,
+  CommunityExtensionSortSchema,
+  CommunityListingInputSchema,
   CommunityReleaseIdSchema,
   CommunityReviewStatusSchema,
   CommunityStatusSchema,
+  CommunitySourceSchema,
+  CommunityEndpointSchema,
+  CommunityInstalledSchema,
+  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,
@@ -49,6 +66,9 @@ import {
   HostUiPageGeometryEvidenceSchema,
   HostUiPageEntrySchema,
   HostUiPermissionDeclarationSchema,
+  ExtensionPanelAnchorSchema,
+  ExtensionPermissionsSchema,
+  ExtensionProvideSchema,
 } from './extension-ui.js'
 
 const EmptyParamsSchema = z.object({}).strict()
@@ -209,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
@@ -388,7 +434,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(),
@@ -548,6 +602,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(),
@@ -563,6 +630,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()
 
@@ -673,6 +742,62 @@ 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()
+
+/** A channel's own instructions for whoever answers it, with recent earlier versions to restore. */
+export const ChannelPromptViewSchema = z
+  .object({
+    document: PromptDocumentV1Schema,
+    /** The agent may not rewrite a locked prompt. */
+    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()
+
 export type ChannelRuntimePhase = z.output<typeof ChannelRuntimePhaseSchema>
 export type ChannelRuntimeUsage = z.output<typeof ChannelRuntimeUsageSchema>
 export type ChannelRuntimeOccupancy = z.output<typeof ChannelRuntimeOccupancySchema>
@@ -681,6 +806,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>
 
@@ -1069,6 +1197,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({
@@ -1076,6 +1206,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(),
               })
@@ -1155,7 +1287,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(),
@@ -1167,9 +1300,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(),
-                scope: z.enum(['agent', 'host-adapter', 'host-ui']),
+                /** 从社区安装的保存记录的来源；本机保存与文件导入没有来源。 */
+                source: CommunitySourceSchema.optional(),
+                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({
@@ -1187,12 +1332,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),
@@ -1246,11 +1390,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']),
@@ -1261,14 +1409,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,
@@ -1611,6 +1753,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,
@@ -1629,6 +1787,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()
 
@@ -1708,7 +1868,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(),
   })
@@ -1768,6 +1928,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()
@@ -2103,6 +2265,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(),
@@ -2112,6 +2276,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(),
       })
@@ -2208,6 +2373,57 @@ 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({
+        document: PromptDocumentV1Schema,
+        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,
+  }),
   resetChannelContext: defineContract({
     invalidatesSnapshot: true,
     method: 'POST',
@@ -2521,7 +2737,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(),
@@ -2539,6 +2759,84 @@ export const HostApiContracts = {
     error: HostApiErrorSchema,
   }),
   /** 下载社区发布并按包摘要校验，结果与本地文件导入的检查相同，再经 `commitExtensionImport` 确认。 */
+  getCommunityEndpoint: defineContract({
+    method: 'GET',
+    path: '/api/community/endpoint',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CommunityEndpointSchema,
+    error: HostApiErrorSchema,
+  }),
+  /** 修改社区地址；`url: null` 恢复为环境变量或默认地址。非加密的局域网地址需要确认风险。 */
+  updateCommunityEndpoint: defineContract({
+    method: 'PUT',
+    path: '/api/community/endpoint',
+    params: EmptyParamsSchema,
+    request: z.object({ url: z.string().max(300).nullable(), acknowledgeInsecure: z.boolean() }).strict(),
+    response: CommunityEndpointSchema,
+    error: HostApiErrorSchema,
+  }),
+  testCommunityEndpoint: defineContract({
+    timeoutMs: 30_000,
+    method: 'POST',
+    path: '/api/community/endpoint/test',
+    params: EmptyParamsSchema,
+    request: z.object({ url: z.string().max(300), acknowledgeInsecure: z.boolean() }).strict(),
+    response: z
+      .object({
+        ok: z.boolean(),
+        message: z.string(),
+        name: z.string().optional(),
+        environment: z.enum(['production', 'staging', 'development']).optional(),
+      })
+      .strict(),
+    error: HostApiErrorSchema,
+  }),
+  listCommunityInstalled: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/installed',
+    params: z.object({ refresh: z.enum(['1']).optional() }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityInstalledSchema,
+    error: HostApiErrorSchema,
+  }),
+  listCommunityMine: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/mine',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: z.object({ items: z.array(CommunityMyExtensionSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  getCommunityReleaseReview: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/releases/:releaseId/review',
+    params: z.object({ releaseId: CommunityReleaseIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityReviewReportSchema,
+    error: HostApiErrorSchema,
+  }),
+  requestCommunityReview: defineContract({
+    timeoutMs: 30_000,
+    method: 'POST',
+    path: '/api/community/releases/:releaseId/review',
+    params: z.object({ releaseId: CommunityReleaseIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  withdrawCommunityRelease: defineContract({
+    timeoutMs: 30_000,
+    method: 'POST',
+    path: '/api/community/releases/:releaseId/withdraw',
+    params: z.object({ releaseId: CommunityReleaseIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
   importCommunityRelease: defineContract({
     timeoutMs: 120_000,
     method: 'POST',
@@ -2558,6 +2856,8 @@ export const HostApiContracts = {
         extensionId: ExtensionIdSchema,
         revisionId: ExtensionRevisionIdSchema,
         notes: z.string().max(2000),
+        /** 作者填写的条目信息；省略的字段不改动社区上已有的内容。 */
+        listing: CommunityListingInputSchema.optional(),
       })
       .strict(),
     response: z
@@ -2571,6 +2871,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',
@@ -3027,8 +3435,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,
@@ -3063,12 +3482,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
@@ -3080,9 +3503,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({
@@ -3091,7 +3517,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({
@@ -3115,8 +3542,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({
@@ -3128,10 +3561,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