@nekro-nxt/contracts 0.6.0 → 0.7.0

package/src/host-api.ts

@@ -315,7 +315,7 @@ export const ImageUnderstandingPolicyApiSchema = z
         restoreAfterCompaction: z
           .object({
             recentMessages: z.number().int().min(1).max(100),
-            maxImages: z.number().int().min(1).max(50),
+            maxImages: z.number().int().min(0).max(50),
           })
           .strict(),
       })
@@ -365,6 +365,8 @@ const AgentCapabilitiesSchema = z
     /** Network for commands; absent in older clients means on. */
     commandNetwork: z.boolean().default(true),
     communityFeedbackAuto: z.boolean().default(false),
+    /** Voice messages reach the agent with a transcript (附加功能 F10). */
+    voiceTranscription: z.boolean().default(false),
     /** Linked accounts this agent's commands act as, one per platform; absent in older clients means none. */
     commandAccounts: z.array(CommandAccountGrantSchema).max(8).default([]),
     /**
@@ -621,6 +623,7 @@ const UpdateAgentCapabilitiesRequestSchema = AgentCapabilitiesSchema.partial()
     codeRun: z.boolean().optional(),
     commandNetwork: z.boolean().optional(),
     communityFeedbackAuto: z.boolean().optional(),
+    voiceTranscription: z.boolean().optional(),
     commandAccounts: z.array(CommandAccountGrantSchema).max(8).optional(),
     extensionAutonomy: z.enum(['manual', 'confirm', 'autonomous']).optional(),
     extensionRequesters: z.enum(['everyone', 'admins']).optional(),
@@ -726,6 +729,8 @@ export const HostSnapshotMessageSchema = z
         trigger: z.enum(['default', 'suppress', 'force']),
         hidden: z.boolean(),
         annotation: z.string().optional(),
+        /** What NekroNXT itself added for the agent, such as the transcript of a voice message. */
+        hostAnnotations: z.array(z.object({ label: z.string(), text: z.string() }).strict()).optional(),
         extensions: z.array(z.string()),
         problems: z.array(z.string()).optional(),
       })
@@ -860,6 +865,12 @@ export const ChannelRuntimeUsageSchema = z
   })
   .strict()
 
+/** The latest progress a running extension tool reported. */
+export const ChannelRuntimeToolProgressSchema = z
+  .object({ text: z.string().min(1).max(200), fraction: z.number().min(0).max(1).optional() })
+  .strict()
+export type ChannelRuntimeToolProgress = z.output<typeof ChannelRuntimeToolProgressSchema>
+
 const channelRuntimeToolFields = {
   callId: NonEmptyStringSchema,
   name: NonEmptyStringSchema,
@@ -871,6 +882,8 @@ const channelRuntimeToolFields = {
   /** `cancelled`: an extension stopped the message before it was sent. */
   deliveryState: z.enum(['sent', 'partially-sent', 'failed', 'unknown', 'cancelled']).optional(),
   durationMs: z.number().int().nonnegative().optional(),
+  /** Set while the tool runs and has reported progress. */
+  progress: ChannelRuntimeToolProgressSchema.optional(),
 }
 
 export const ChannelRuntimeToolSchema = z
@@ -1208,6 +1221,20 @@ export const ChannelContextPolicyViewSchema = z
 
 export type ChannelContextPolicyView = z.output<typeof ChannelContextPolicyViewSchema>
 
+/** One desktop installer of a release; `urls` lists the sources to try in order. */
+export const ProductDownloadSchema = z
+  .object({
+    platform: z.enum(['mac', 'win', 'linux']),
+    arch: z.enum(['arm64', 'x64']),
+    name: z.string().min(1),
+    size: z.number().int().positive(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    urls: z.array(z.string().url()).min(1),
+  })
+  .strict()
+
+export type ProductDownload = z.output<typeof ProductDownloadSchema>
+
 /** Whether a newer release exists on the build's own channel; development builds are never compared. */
 export const ProductUpdateStatusSchema = z
   .object({
@@ -1222,6 +1249,8 @@ export const ProductUpdateStatusSchema = z
         commit: z.string().optional(),
         url: z.string().url(),
         publishedAt: z.number().int().nonnegative().optional(),
+        /** Desktop installers of this release; the desktop app downloads its own and checks size and digest. */
+        downloads: z.array(ProductDownloadSchema).optional(),
       })
       .strict()
       .optional(),
@@ -1282,30 +1311,10 @@ export const SubConversationSettingsSchema = z.object({ retention: SubConversati
 export const RetrievalModeSchema = z.enum(['keyword', 'builtin'])
 export type RetrievalMode = z.output<typeof RetrievalModeSchema>
 
-/** Search used by extension indexes (表情包与扩展素材能力 §6.4). */
+/** Search used by extension indexes (表情包与扩展素材能力 §6.4); the model itself is the `retrieval` add-on. */
 export const RetrievalStatusSchema = z
   .object({
     mode: RetrievalModeSchema,
-    builtin: z
-      .object({
-        model: z.string(),
-        /** False where no inference runtime is published for this system and processor. */
-        supported: z.boolean(),
-        downloadBytes: z.number().int().nonnegative(),
-        install: z.discriminatedUnion('state', [
-          z.object({ state: z.literal('not-installed') }).strict(),
-          z
-            .object({
-              state: z.literal('downloading'),
-              receivedBytes: z.number().int().nonnegative(),
-              totalBytes: z.number().int().nonnegative(),
-            })
-            .strict(),
-          z.object({ state: z.literal('installed') }).strict(),
-          z.object({ state: z.literal('failed'), error: z.string() }).strict(),
-        ]),
-      })
-      .strict(),
     vectors: z
       .object({
         documents: z.number().int().nonnegative(),
@@ -1541,6 +1550,14 @@ export const AttentionItemSchema = z
         label: z.string().min(1).max(40),
       })
       .strict(),
+    /**
+     * The shared cause several items come from: a connection (its outage and the deliveries it failed) or an agent
+     * (its failed turns and unusable models). Dismissing by cause keeps it quiet until the cause recovers.
+     */
+    cause: z
+      .object({ key: z.string().min(1).max(200), label: z.string().min(1).max(120) })
+      .strict()
+      .optional(),
     occurredAt: z.number().int().safe().nonnegative(),
   })
   .strict()
@@ -1661,42 +1678,128 @@ export const ScheduledTaskSchema = z
 
 export type ScheduledTask = z.output<typeof ScheduledTaskSchema>
 
-/** The Node that runs `run_code` programs, and the download the desktop app offers when there is none. */
-export const CodeRunAvailabilitySchema = z
+/** Programs and models NekroNXT installs on request (附加功能); `<data root>/runtimes`, left out of backups. */
+export const AddonIdSchema = z.enum(['media', 'speech', 'retrieval', 'node', 'github-cli', 'browser'])
+export type AddonId = z.output<typeof AddonIdSchema>
+
+/** `extension`: used by extensions; `agent`: used by agents' commands; `host`: used by NekroNXT itself. */
+export const AddonGroupSchema = z.enum(['extension', 'agent', 'host'])
+export type AddonGroup = z.output<typeof AddonGroupSchema>
+
+/**
+ * `installed`: downloaded and ready; `available`: usable without installing (bundled, found on this device, cloud);
+ * `needs-config`: usable once configured (cloud).
+ */
+export const AddonStateSchema = z.enum([
+  'not-installed',
+  'installing',
+  'installed',
+  'failed',
+  'unsupported',
+  'available',
+  'needs-config',
+])
+export type AddonState = z.output<typeof AddonStateSchema>
+
+const AddonProgressSchema = z
   .object({
-    available: z.boolean(),
-    source: z.enum(['host', 'system', 'downloaded']).optional(),
+    receivedBytes: z.number().int().nonnegative(),
+    totalBytes: z.number().int().nonnegative().optional(),
+  })
+  .strict()
+
+/** One way an add-on can be provided, such as a program found on this device or one NekroNXT downloads. */
+export const AddonProviderStatusSchema = z
+  .object({
+    id: NonEmptyStringSchema,
+    title: NonEmptyStringSchema,
+    summary: z.string(),
+    state: AddonStateSchema,
+    /** `bundled`: installed with NekroNXT; `system`: found on this device; `downloaded`: fetched by NekroNXT. */
+    source: z.enum(['bundled', 'system', 'downloaded', 'cloud']).optional(),
+    /** The installed version, or the one an install fetches. */
     version: z.string().optional(),
-    download: z
+    resources: z
       .object({
-        version: z.string(),
-        state: z.enum(['idle', 'downloading', 'failed']),
-        receivedBytes: z.number().int().nonnegative().optional(),
-        totalBytes: z.number().int().nonnegative().optional(),
-        error: z.string().optional(),
+        /** Approximate for this system and processor. */
+        downloadBytes: z.number().int().nonnegative().optional(),
+        /** Measured from its own folder after install. */
+        installedBytes: z.number().int().nonnegative().optional(),
+        memoryBytes: z.number().int().nonnegative().optional(),
+        /** Short differences worth comparing, such as languages or speed. */
+        notes: z.array(z.string()).default([]),
       })
-      .strict()
-      .optional(),
+      .strict(),
+    /** One entry per component that carries its own license. */
+    licenses: z
+      .array(z.object({ component: z.string().optional(), name: NonEmptyStringSchema, url: z.url() }).strict())
+      .default([]),
+    /** Where downloads come from, for display. */
+    sources: z.array(z.string()).default([]),
+    progress: AddonProgressSchema.optional(),
+    error: z.string().optional(),
+    /** Other add-ons it needs to work. */
+    dependsOn: z.array(AddonIdSchema).default([]),
+    installable: z.boolean(),
+    removable: z.boolean(),
   })
   .strict()
+export type AddonProviderStatus = z.output<typeof AddonProviderStatusSchema>
 
-export type CodeRunAvailability = z.output<typeof CodeRunAvailabilitySchema>
+/** One add-on (a capability) as 设置 → 附加功能 shows it; the registry on the server is its only source. */
+export const AddonStatusSchema = z
+  .object({
+    id: AddonIdSchema,
+    group: AddonGroupSchema,
+    title: NonEmptyStringSchema,
+    summary: z.string(),
+    /** Who relies on it, as labels people recognise. */
+    usedBy: z.array(z.string()),
+    /** The selected provider's state, or, while none can be used, the one closest to usable. */
+    state: AddonStateSchema,
+    progress: AddonProgressSchema.optional(),
+    /** The provider in use; absent while none can be used. */
+    selected: NonEmptyStringSchema.optional(),
+    /** In declared order; providers that do not exist on this device are left out. */
+    providers: z.array(AddonProviderStatusSchema),
+  })
+  .strict()
+export type AddonStatus = z.output<typeof AddonStatusSchema>
 
-/** The GitHub CLI commands call: found on this machine, or downloaded by NekroNXT where it can. */
-export const GithubCliAvailabilitySchema = CodeRunAvailabilitySchema
-export type GithubCliAvailability = z.output<typeof GithubCliAvailabilitySchema>
+/** Languages speech recognition can be asked for; `auto` lets the provider tell. */
+export const SpeechLanguageSchema = z.enum(['auto', 'zh', 'en', 'ja', 'ko', 'yue'])
+export type SpeechLanguage = z.output<typeof SpeechLanguageSchema>
+
+/** The cloud provider of the `speech` add-on: a provider from 设置 → 模型 and the transcription model it serves. */
+export const SpeechCloudSettingsSchema = z
+  .object({
+    provider: NonEmptyStringSchema,
+    model: z.string().trim().min(1).max(200),
+    /** Used when a caller does not name a language. */
+    language: SpeechLanguageSchema.optional(),
+  })
+  .strict()
+export type SpeechCloudSettings = z.output<typeof SpeechCloudSettingsSchema>
+
+export const SpeechSettingsSchema = z
+  .object({
+    cloud: SpeechCloudSettingsSchema.nullable(),
+    /** Configured providers with an OpenAI-compatible address, the ones cloud transcription can use. */
+    providers: z.array(z.object({ provider: NonEmptyStringSchema, displayName: z.string() }).strict()),
+  })
+  .strict()
+export type SpeechSettings = z.output<typeof SpeechSettingsSchema>
 
-/** The optional headless Chromium that loads and checks creation candidates when no page is open. */
-export const VerificationBrowserAvailabilitySchema = CodeRunAvailabilitySchema
-export type VerificationBrowserAvailability = z.output<typeof VerificationBrowserAvailabilitySchema>
+/** Whether a capability that needs an add-on can run now; details live in `addons`. */
+export const AddonAvailabilitySchema = z.object({ available: z.boolean() }).strict()
+export type AddonAvailability = z.output<typeof AddonAvailabilitySchema>
 
 /** A platform's own program that linked accounts work through, such as the GitHub CLI. */
 export const LinkedAccountPlatformToolSchema = z
   .object({
-    /** The runtime download routes it is managed by (`downloadGithubCli`, `removeGithubCli`). */
+    /** The add-on it is installed as (`AddonStatus.id`). */
     id: z.enum(['github-cli']),
     name: z.string(),
-    availability: GithubCliAvailabilitySchema,
   })
   .strict()
 
@@ -1735,7 +1838,7 @@ export const ExtensionRequestSchema = z
     channelId: ChannelIdSchema.nullable(),
     extensionId: ExtensionIdSchema.nullable(),
     summary: z.string(),
-    status: z.enum(['pending', 'approved', 'rejected', 'expired', 'completed', 'failed']),
+    status: z.enum(['pending', 'approved', 'rejected', 'expired', 'completed', 'failed', 'superseded', 'withdrawn']),
     autonomous: z.boolean(),
     resultMessage: z.string().nullable(),
     decidedBy: z.string().nullable(),
@@ -1787,12 +1890,14 @@ 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(),
-        /** Optional in older hosts, which never offer command accounts. */
-        githubCli: GithubCliAvailabilitySchema.optional(),
-        /** Optional in older hosts, which check candidates only in an open page. */
-        verificationBrowser: VerificationBrowserAvailabilitySchema.optional(),
+        /** The `node` add-on that `run_code` needs. */
+        codeRun: AddonAvailabilitySchema.optional(),
+        /** The `github-cli` add-on that commands use with a GitHub account. */
+        githubCli: AddonAvailabilitySchema.optional(),
+        /** The `browser` add-on that checks candidates when no page is open. */
+        verificationBrowser: AddonAvailabilitySchema.optional(),
+        /** The `speech` add-on that voice message transcription needs. */
+        speechRecognition: AddonAvailabilitySchema.optional(),
         /** What this host can confine for commands beyond file writes; optional in older hosts. */
         commandConfinement: z.object({ readScope: z.boolean(), networkControl: z.boolean() }).strict().optional(),
         webSearch: z
@@ -2224,6 +2329,7 @@ export const HostSnapshotSchema = z
     authoringTasks: z.array(AuthoringTaskSummarySchema).default([]),
     /** Open sub-conversations, and the most recently ended ones of each channel. */
     subConversations: z.array(SubConversationSchema).default([]),
+    addons: z.array(AddonStatusSchema).default([]),
     scheduledTasks: z.array(ScheduledTaskSchema).default([]),
     /** Extension requests waiting for an administrator. */
     extensionRequests: z.array(ExtensionRequestSchema).default([]),
@@ -2352,6 +2458,8 @@ export const DshPluginCatalogEntrySchema = z
     installSource: z.enum(['registry', 'tarball', 'imported']).optional(),
     /** Published by the DSH maintainers on npm for the DSH release this build runs. */
     official: z.boolean().optional(),
+    /** Third-party installed plugins: whether an administrator allowed them to submit images to the model. */
+    imageSubmission: z.boolean().optional(),
     installedAt: z.number().int().safe().nonnegative().optional(),
     clientUiDetected: z.boolean().optional(),
     hostUi: DshNxtHostUiSchema.optional(),
@@ -2765,6 +2873,22 @@ const agentExtensionParam = z.object({ agentId: AgentIdSchema, extensionId: Exte
 
 const PermissionApprovalSchema = z.object({ permissionDigest: z.string().regex(/^[a-f0-9]{64}$/u) }).strict()
 
+/**
+ * What keeps a version from being cleaned up: in use, enabled for an agent, released to a community, kept by hand,
+ * the start of a branch, the base of an open revision, needed by 回到上一个版本, or named by a pending request.
+ */
+export const ExtensionRevisionProtectionSchema = z.enum([
+  'installed',
+  'active',
+  'released',
+  'kept',
+  'branch',
+  'revising',
+  'undo',
+  'request',
+])
+export type ExtensionRevisionProtection = z.output<typeof ExtensionRevisionProtectionSchema>
+
 /** One version of one line in the lineage view of an extension family. */
 export const ExtensionLineageNodeSchema = z
   .object({
@@ -2776,6 +2900,10 @@ export const ExtensionLineageNodeSchema = z
     createdAt: z.number().int().nonnegative(),
     current: z.boolean(),
     releaseNumbers: z.array(z.number().int().positive()),
+    /** Marked by an administrator to keep. */
+    kept: z.boolean(),
+    /** Why the version cannot be cleaned up; absent when it can. */
+    protectedBy: ExtensionRevisionProtectionSchema.optional(),
   })
   .strict()
 
@@ -3838,74 +3966,55 @@ export const HostApiContracts = {
     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',
+  getSpeechSettings: defineContract({
+    method: 'GET',
+    path: '/api/settings/speech',
     params: EmptyParamsSchema,
     request: NoRequestBodySchema,
-    response: RetrievalStatusSchema,
+    response: SpeechSettingsSchema,
     error: HostApiErrorSchema,
   }),
-  downloadCodeRunNode: defineContract({
-    invalidatesSnapshot: true,
-    method: 'POST',
-    path: '/api/runtimes/code-run-node/download',
+  updateSpeechSettings: defineContract({
+    method: 'PUT',
+    path: '/api/settings/speech',
     params: EmptyParamsSchema,
-    request: NoRequestBodySchema,
-    response: CodeRunAvailabilitySchema,
+    request: z.object({ cloud: SpeechCloudSettingsSchema.nullable() }).strict(),
+    response: SpeechSettingsSchema,
     error: HostApiErrorSchema,
   }),
-  removeCodeRunNode: defineContract({
-    invalidatesSnapshot: true,
-    method: 'DELETE',
-    path: '/api/runtimes/code-run-node',
+  listAddons: defineContract({
+    method: 'GET',
+    path: '/api/addons',
     params: EmptyParamsSchema,
     request: NoRequestBodySchema,
-    response: CodeRunAvailabilitySchema,
+    response: z.object({ addons: z.array(AddonStatusSchema) }).strict(),
     error: HostApiErrorSchema,
   }),
-  downloadGithubCli: defineContract({
+  installAddonProvider: defineContract({
     invalidatesSnapshot: true,
     method: 'POST',
-    path: '/api/runtimes/github-cli/download',
-    params: EmptyParamsSchema,
+    path: '/api/addons/:id/providers/:provider/install',
+    params: z.object({ id: AddonIdSchema, provider: NonEmptyStringSchema }).strict(),
     request: NoRequestBodySchema,
-    response: GithubCliAvailabilitySchema,
+    response: AddonStatusSchema,
     error: HostApiErrorSchema,
   }),
-  removeGithubCli: defineContract({
+  removeAddonProvider: defineContract({
     invalidatesSnapshot: true,
     method: 'DELETE',
-    path: '/api/runtimes/github-cli',
-    params: EmptyParamsSchema,
-    request: NoRequestBodySchema,
-    response: GithubCliAvailabilitySchema,
-    error: HostApiErrorSchema,
-  }),
-  downloadVerificationBrowser: defineContract({
-    invalidatesSnapshot: true,
-    method: 'POST',
-    path: '/api/runtimes/verification-browser/download',
-    params: EmptyParamsSchema,
+    path: '/api/addons/:id/providers/:provider',
+    params: z.object({ id: AddonIdSchema, provider: NonEmptyStringSchema }).strict(),
     request: NoRequestBodySchema,
-    response: VerificationBrowserAvailabilitySchema,
+    response: AddonStatusSchema,
     error: HostApiErrorSchema,
   }),
-  removeVerificationBrowser: defineContract({
+  selectAddonProvider: defineContract({
     invalidatesSnapshot: true,
-    method: 'DELETE',
-    path: '/api/runtimes/verification-browser',
-    params: EmptyParamsSchema,
-    request: NoRequestBodySchema,
-    response: VerificationBrowserAvailabilitySchema,
+    method: 'PUT',
+    path: '/api/addons/:id/selection',
+    params: z.object({ id: AddonIdSchema }).strict(),
+    request: z.object({ provider: NonEmptyStringSchema }).strict(),
+    response: AddonStatusSchema,
     error: HostApiErrorSchema,
   }),
   getLinkedAccounts: defineContract({
@@ -4294,6 +4403,14 @@ export const HostApiContracts = {
     response: z.object({ disabled: z.literal(true) }).strict(),
     error: HostApiErrorSchema,
   }),
+  setDshPluginImageSubmission: defineContract({
+    method: 'PUT',
+    path: '/api/dsh/plugin-installs/:packageId/image-submission',
+    params: dshPluginPackageParam,
+    request: z.object({ allowed: z.boolean() }).strict(),
+    response: z.object({ allowed: z.boolean() }).strict(),
+    error: HostApiErrorSchema,
+  }),
   removeDshPluginPackage: defineContract({
     invalidatesSnapshot: true,
     method: 'DELETE',
@@ -5508,6 +5625,20 @@ export const HostApiContracts = {
     response: z.object({ dismissed: z.literal(true), revision: z.string().min(1) }).strict(),
     error: HostApiErrorSchema,
   }),
+  dismissAttentionBatch: defineContract({
+    method: 'POST',
+    path: '/api/attention/dismiss',
+    params: EmptyParamsSchema,
+    request: z
+      .object({
+        ids: z.array(z.string().min(1).max(200)).max(200),
+        /** Causes to keep quiet until they recover; new items of these causes are not shown meanwhile. */
+        causes: z.array(z.string().min(1).max(200)).max(200),
+      })
+      .strict(),
+    response: z.object({ dismissed: z.literal(true), revision: z.string().min(1) }).strict(),
+    error: HostApiErrorSchema,
+  }),
   getChannelPending: defineContract({
     method: 'GET',
     path: '/api/channels/:channelId/pending',
@@ -5622,6 +5753,23 @@ export const HostApiContracts = {
     response: ExtensionLineageSchema,
     error: HostApiErrorSchema,
   }),
+  setExtensionRevisionKept: defineContract({
+    method: 'POST',
+    path: '/api/extensions/:extensionId/revisions/:revisionId/keep',
+    params: z.object({ extensionId: ExtensionIdSchema, revisionId: ExtensionRevisionIdSchema }).strict(),
+    request: z.object({ kept: z.boolean() }).strict(),
+    response: z.object({ kept: z.boolean() }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  deleteExtensionRevisions: defineContract({
+    invalidatesSnapshot: true,
+    method: 'POST',
+    path: '/api/extensions/:extensionId/revisions/delete',
+    params: extensionParam,
+    request: z.object({ revisionIds: z.array(ExtensionRevisionIdSchema).min(1).max(200) }).strict(),
+    response: z.object({ deleted: z.number().int().nonnegative() }).strict(),
+    error: HostApiErrorSchema,
+  }),
   branchExtension: defineContract({
     invalidatesSnapshot: true,
     timeoutMs: 300_000,