@nekro-nxt/contracts 0.3.0 → 0.4.0

package/src/host-api.ts

@@ -292,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()
 
@@ -386,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), '至少提供一个能力。')
 
@@ -570,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()
 
@@ -647,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()
 
@@ -722,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,
@@ -733,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()
@@ -774,11 +842,10 @@ export const ChannelRuntimeContextSchema = z
   })
   .strict()
 
-/** A channel's own instructions for whoever answers it, with recent earlier versions to restore. */
-export const ChannelPromptViewSchema = z
+const ChannelPromptPartSchema = z
   .object({
     document: PromptDocumentV1Schema,
-    /** The agent may not rewrite a locked prompt. */
+    /** 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(),
@@ -798,6 +865,146 @@ export const ChannelPromptViewSchema = z
   })
   .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>
@@ -839,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(),
     ),
@@ -1082,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(),
@@ -1114,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'),
@@ -1310,7 +1543,7 @@ export const HostSnapshotSchema = z
                   .regex(/^\/api\/extensions\/[^/]+\/revisions\/[^/]+\/icon\/[a-f0-9]{64}\.(?:svg|png|webp)$/u)
                   .optional(),
                 createdAt: z.number().int().safe().nonnegative(),
-                /** 从社区安装的保存记录的来源；本机保存与文件导入没有来源。 */
+                /** 从社区安装的版本的来源；本机保存与文件导入没有来源。 */
                 source: CommunitySourceSchema.optional(),
                 provides: z.array(ExtensionProvideSchema),
                 /** Whether this Revision can be enabled for agents (agent-layer contributions or capabilities). */
@@ -2415,7 +2648,9 @@ export const HostApiContracts = {
     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(),
@@ -2424,6 +2659,130 @@ export const HostApiContracts = {
     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',