@nekro-nxt/contracts 0.2.0 → 0.3.0

package/src/extension-capabilities.ts

@@ -2,10 +2,10 @@ import { z } from 'zod'
 
 /**
  * Host capability level this build implements. A Revision that declares `requires.sdk` above it is rejected at
- * import with an "upgrade NekroNXT" message instead of an opaque schema error. Bump only when a new optional
- * Manifest capability ships; never reuse a level for a different meaning.
+ * import with an "upgrade NekroNXT" message instead of an opaque schema error. Bump when a Manifest capability
+ * ships; never reuse a level for a different meaning. Level 7 is Manifest V7 (host instance + agent attachments).
  */
-export const EXTENSION_SDK_LEVEL = 6
+export const EXTENSION_SDK_LEVEL = 7
 
 export const ExtensionRequiresSchema = z.object({ sdk: z.number().int().min(1).max(1000) }).strict()
 export type ExtensionRequires = z.output<typeof ExtensionRequiresSchema>
@@ -252,8 +252,8 @@ const mcpTarget = (server: ExtensionMcpServer): string =>
     : JSON.stringify(['streamable-http', server.name, server.url])
 
 /**
- * Optional Host capabilities of an agent-scope Revision. Every field is additive to Manifest V6: an absent field
- * means the Revision cannot use that capability, exactly as before the field existed.
+ * Agent-layer capabilities (`permissions.agent`): what the extension may do inside the agents it is enabled for. An
+ * absent field means the extension cannot use that capability.
  */
 export const ExtensionCapabilitiesSchema = z
   .object({
@@ -281,6 +281,37 @@ export const ExtensionCapabilitiesSchema = z
   .strict()
 export type ExtensionCapabilities = z.output<typeof ExtensionCapabilitiesSchema>
 
+/**
+ * Host-layer capabilities (`permissions.host`): what the extension's single host instance may do through the `nxt`
+ * service its factory receives. Host storage is the extension's `shared` partition.
+ */
+export const HostLayerCapabilitiesSchema = z
+  .object({
+    network: ExtensionNetworkCapabilitySchema.optional(),
+    storage: z
+      .object({ quotaBytes: z.number().int().min(1024).max(EXTENSION_STORAGE_MAX_QUOTA_BYTES).optional() })
+      .strict()
+      .optional(),
+  })
+  .strict()
+export type HostLayerCapabilities = z.output<typeof HostLayerCapabilitiesSchema>
+
+/** Host-layer capabilities in the agent-capability shape, so digests, expansion and summaries share one implementation. */
+export const hostLayerAsCapabilities = (host: HostLayerCapabilities | undefined): ExtensionCapabilities | undefined =>
+  host === undefined || Object.keys(host).length === 0
+    ? undefined
+    : {
+        ...(host.network === undefined ? {} : { network: host.network }),
+        ...(host.storage === undefined
+          ? {}
+          : {
+              storage: {
+                scopes: ['shared'],
+                ...(host.storage.quotaBytes === undefined ? {} : { quotaBytes: host.storage.quotaBytes }),
+              },
+            }),
+      }
+
 const NETWORK_MODE_RANK = { domains: 0, config: 1, unrestricted: 2 } as const
 
 const networkExpands = (
@@ -360,9 +391,17 @@ export interface ExtensionCapabilitySummaryItem {
   readonly detail?: string
 }
 
-/** User-facing summary of declared capabilities, in a stable order, for approval and inspection pages. */
+/**
+ * User-facing summary of declared capabilities, in a stable order, for approval and inspection pages. `layer: 'host'`
+ * phrases host-layer capabilities (passed through {@link hostLayerAsCapabilities}) for the host instance.
+ */
 export const summarizeExtensionCapabilities = (
   capabilities: ExtensionCapabilities | undefined,
+  options: {
+    readonly layer?: 'host' | 'agent'
+    /** Display name of a config field, so `network.mode: 'config'` names the fields as the user knows them. */
+    readonly fieldTitle?: (key: string) => string
+  } = {},
 ): readonly ExtensionCapabilitySummaryItem[] => {
   if (capabilities === undefined) return []
   const items: ExtensionCapabilitySummaryItem[] = []
@@ -370,11 +409,18 @@ export const summarizeExtensionCapabilities = (
   if (network?.mode === 'domains') {
     items.push({ key: 'network', risk: 'normal', label: '访问指定网站', detail: network.domains.join('、') })
   } else if (network?.mode === 'config') {
-    items.push({ key: 'network', risk: 'normal', label: '访问你在配置中填写的地址', detail: network.fields.join('、') })
+    items.push({
+      key: 'network',
+      risk: 'normal',
+      label: '访问你在配置中填写的地址',
+      detail: network.fields.map((field) => options.fieldTitle?.(field) ?? field).join('、'),
+    })
   } else if (network?.mode === 'unrestricted') {
     items.push({ key: 'network', risk: 'high', label: '访问任意公网地址', detail: network.purpose })
   }
-  if (capabilities.storage !== undefined) {
+  if (capabilities.storage !== undefined && options.layer === 'host') {
+    items.push({ key: 'storage', risk: 'normal', label: '在本机保存扩展数据，页面与启用它的智能体共用' })
+  } else if (capabilities.storage !== undefined) {
     const shared = capabilities.storage.scopes.includes('shared')
     items.push({
       key: 'storage',

package/src/extension-ui.ts

@@ -1,5 +1,9 @@
 import { z } from 'zod'
-import { ExtensionCapabilitiesSchema } from './extension-capabilities.js'
+import {
+  ExtensionCapabilitiesSchema,
+  HostLayerCapabilitiesSchema,
+  hostLayerAsCapabilities,
+} from './extension-capabilities.js'
 import { ExtensionIdSchema, ExtensionRevisionIdSchema, HostUiPageInstanceIdSchema } from './domain.js'
 import { ConfigSchemaDocumentSchema } from './config-schema.js'
 
@@ -132,11 +136,23 @@ export const HostPageContributionSchema = z
       .string()
       .trim()
       .regex(/^(?:[a-z0-9][a-z0-9/_-]*)?$/u),
+    /** Registers a navigation rail entry for this page; at most one page of an extension may declare it. */
+    rail: z
+      .object({ order: z.number().int().min(0).max(999).optional() })
+      .strict()
+      .optional(),
   })
   .strict()
 
 export type HostPageContribution = z.output<typeof HostPageContributionSchema>
 
+/** Rail position of a page that registers a rail entry without an explicit order. */
+export const HOST_PAGE_DEFAULT_RAIL_ORDER = 100
+
+/** The stored rail position of a page; `null` when the page has no rail entry. */
+export const hostPageRailOrder = (page: Pick<HostPageContribution, 'rail'>): number | null =>
+  page.rail === undefined ? null : (page.rail.order ?? HOST_PAGE_DEFAULT_RAIL_ORDER)
+
 export const HostUiNavigationItemSchema = z
   .object({
     id: z.string().trim().min(1).max(80),
@@ -189,32 +205,77 @@ export const HostUiNetworkOriginSchema = z
     return url.origin
   })
 
+const checkBrowserPermissions = (
+  value: { readonly permissions: readonly HostUiPermission[]; readonly networkOrigins: readonly string[] },
+  context: z.RefinementCtx,
+): void => {
+  if (new Set(value.permissions).size !== value.permissions.length) {
+    context.addIssue({ code: 'custom', path: ['permissions'], message: 'Host UI permissions must be unique.' })
+  }
+  if (new Set(value.networkOrigins).size !== value.networkOrigins.length) {
+    context.addIssue({ code: 'custom', path: ['networkOrigins'], message: 'Host UI network origins must be unique.' })
+  }
+  if (value.networkOrigins.length > 0 && !value.permissions.includes('network.request')) {
+    context.addIssue({
+      code: 'custom',
+      path: ['networkOrigins'],
+      message: 'Host UI network origins require network.request.',
+    })
+  }
+}
+
+/**
+ * One approval: browser-side permissions plus the capabilities of one layer. Grants, digests and the approval page
+ * use this shape for both the host approval and each agent approval.
+ */
 export const HostUiPermissionDeclarationSchema = z
   .object({
     permissions: z.array(HostUiPermissionSchema).max(HostUiPermissionSchema.options.length),
     networkOrigins: z.array(HostUiNetworkOriginSchema).max(32).default([]),
-    /** Host capabilities of an agent-scope Revision; absent keeps the pre-capability digest unchanged. */
     capabilities: ExtensionCapabilitiesSchema.optional(),
   })
   .strict()
-  .superRefine((value, context) => {
-    if (new Set(value.permissions).size !== value.permissions.length) {
-      context.addIssue({ code: 'custom', path: ['permissions'], message: 'Host UI permissions must be unique.' })
-    }
-    if (new Set(value.networkOrigins).size !== value.networkOrigins.length) {
-      context.addIssue({ code: 'custom', path: ['networkOrigins'], message: 'Host UI network origins must be unique.' })
-    }
-    if (value.networkOrigins.length > 0 && !value.permissions.includes('network.request')) {
-      context.addIssue({
-        code: 'custom',
-        path: ['networkOrigins'],
-        message: 'Host UI network origins require network.request.',
-      })
-    }
-  })
+  .superRefine(checkBrowserPermissions)
 
 export type HostUiPermissionDeclaration = z.output<typeof HostUiPermissionDeclarationSchema>
 
+/**
+ * Manifest V7 `permissions`: browser-side permissions of pages and panels (`host.call`), host-layer capabilities used
+ * by the single host instance, and agent-layer capabilities used inside each enabled agent.
+ */
+export const ExtensionPermissionsSchema = z
+  .object({
+    permissions: z.array(HostUiPermissionSchema).max(HostUiPermissionSchema.options.length).default([]),
+    networkOrigins: z.array(HostUiNetworkOriginSchema).max(32).default([]),
+    host: HostLayerCapabilitiesSchema.optional(),
+    agent: ExtensionCapabilitiesSchema.optional(),
+  })
+  .strict()
+  .superRefine(checkBrowserPermissions)
+
+export type ExtensionPermissions = z.output<typeof ExtensionPermissionsSchema>
+
+export const EMPTY_EXTENSION_PERMISSIONS: ExtensionPermissions = { permissions: [], networkOrigins: [] }
+
+/** What installing the extension on this machine asks the user to approve. */
+export const hostPermissionDeclaration = (permissions: ExtensionPermissions): HostUiPermissionDeclaration => {
+  const capabilities = hostLayerAsCapabilities(permissions.host)
+  return {
+    permissions: [...permissions.permissions],
+    networkOrigins: [...permissions.networkOrigins],
+    ...(capabilities === undefined ? {} : { capabilities }),
+  }
+}
+
+/** What enabling the extension for one agent asks the user to approve. */
+export const agentPermissionDeclaration = (permissions: ExtensionPermissions): HostUiPermissionDeclaration => ({
+  permissions: [],
+  networkOrigins: [],
+  ...(permissions.agent === undefined || Object.keys(permissions.agent).length === 0
+    ? {}
+    : { capabilities: permissions.agent }),
+})
+
 export const HostUiOwnerSchema = z.discriminatedUnion('kind', [
   z
     .object({
@@ -246,6 +307,11 @@ export const HostUiPageEntrySchema = z
     startPath: z.string(),
     visible: z.boolean(),
     sortOrder: z.number().int().nonnegative(),
+    /** Present when the page registered a navigation rail entry; lower orders come first. */
+    rail: z
+      .object({ order: z.number().int().min(0).max(999) })
+      .strict()
+      .optional(),
     routeBase: z.string().regex(/^\/apps\/hup_[0-9A-Za-z]+$/u),
     client: z
       .object({
@@ -308,8 +374,17 @@ export type DshNxtHostUi = z.output<typeof DshNxtHostUiSchema>
 export const ExtensionPanelAnchorSchema = z.enum(['agent', 'channel', 'extension', 'connection'])
 export type ExtensionPanelAnchor = z.output<typeof ExtensionPanelAnchorSchema>
 
-export const AGENT_PANEL_ANCHORS = ['agent', 'channel', 'extension'] as const satisfies readonly ExtensionPanelAnchor[]
-export const ADAPTER_PANEL_ANCHORS = ['connection', 'channel'] as const satisfies readonly ExtensionPanelAnchor[]
+/**
+ * Which layer a panel belongs to. Agent and channel panels follow the agents the extension is enabled for (a channel
+ * panel also shows on channels of the extension's own adapter); extension and connection panels belong to the host
+ * instance.
+ */
+export const PANEL_ANCHOR_LAYER = {
+  agent: 'agent',
+  channel: 'agent',
+  extension: 'host',
+  connection: 'host',
+} as const satisfies Readonly<Record<ExtensionPanelAnchor, 'agent' | 'host'>>
 
 export const PanelDensitySchema = z.enum(['compact', 'full'])
 export type PanelDensity = z.output<typeof PanelDensitySchema>
@@ -402,10 +477,22 @@ export const MessageRendererContributionSchema = z
   .strict()
 export type MessageRendererContribution = z.output<typeof MessageRendererContributionSchema>
 
-/** Optional configuration surface shared by every extension scope. */
+/** What an extension provides, derived from its Manifest; for listing and filtering, never a lifecycle switch. */
+export const EXTENSION_PROVIDES = ['agent', 'page', 'adapter', 'mcp'] as const
+export const ExtensionProvideSchema = z.enum(EXTENSION_PROVIDES)
+export type ExtensionProvide = z.output<typeof ExtensionProvideSchema>
+
+/** One configuration form: a serialized Schemastery document. */
 export const ExtensionConfigDeclarationSchema = z.object({ schema: ConfigSchemaDocumentSchema }).strict()
 export type ExtensionConfigDeclaration = z.output<typeof ExtensionConfigDeclarationSchema>
 
+/** Manifest V7 `config`: the host instance's configuration and each enabled agent's configuration. */
+export const ExtensionLayeredConfigSchema = z
+  .object({ host: ExtensionConfigDeclarationSchema.optional(), agent: ExtensionConfigDeclarationSchema.optional() })
+  .strict()
+export type ExtensionLayeredConfig = z.output<typeof ExtensionLayeredConfigSchema>
+export type ExtensionConfigLayer = 'host' | 'agent'
+
 /** Product projection of what one Revision contributes to the shell. */
 export const ExtensionUiContributionsSchema = z
   .object({