@nekro-nxt/contracts 0.5.0 → 0.6.0

package/src/credentials.ts

@@ -0,0 +1,260 @@
+import { z } from 'zod'
+import { AgentIdSchema, ChannelIdSchema, CredentialIdSchema, ExtensionIdSchema } from './domain.js'
+import { ExtensionNetworkDomainSchema } from './extension-capabilities.js'
+
+/**
+ * Named credentials (智能体扩展配置与凭据 C1–C5): one entry is added once and reused by extensions, MCP servers and
+ * commands. The value is write-only; every view below carries metadata only. Accounts on platforms such as GitHub are
+ * linked accounts (`linked-accounts.ts`), granted per agent, not credentials.
+ */
+
+export const CREDENTIAL_NAME_MAX_CHARS = 64
+export const CREDENTIAL_DESCRIPTION_MAX_CHARS = 500
+export const CREDENTIAL_VALUE_MAX_CHARS = 16_384
+/** Values shorter than this are not hidden from tool results; the form warns when one is saved. */
+export const CREDENTIAL_REDACTABLE_MIN_CHARS = 8
+
+/** How a credential reaches code: `request` only as a placeholder filled by `nxt.http.fetch`; `program` as the value. */
+export const CredentialUsageSchema = z.enum(['request', 'program'])
+export type CredentialUsage = z.output<typeof CredentialUsageSchema>
+
+/** Agents that may use a credential: every agent, or the listed ones. */
+export const CredentialAgentScopeSchema = z.union([
+  z.object({ all: z.literal(true) }).strict(),
+  z.object({ agentIds: z.array(AgentIdSchema).max(256) }).strict(),
+])
+export type CredentialAgentScope = z.output<typeof CredentialAgentScopeSchema>
+
+/** Shown in redaction markers (`[凭据:名称]`), so brackets and control characters are not allowed. */
+export const CredentialNameSchema = z
+  .string()
+  .trim()
+  .min(1, '名称不能为空。')
+  .max(CREDENTIAL_NAME_MAX_CHARS, `名称最多 ${CREDENTIAL_NAME_MAX_CHARS} 个字符。`)
+  // eslint-disable-next-line no-control-regex -- Control characters are exactly what the name must not contain.
+  .regex(/^[^\u0000-\u001f\u007f[\]]+$/u, '名称不能包含方括号或控制字符。')
+
+export const CredentialDescriptionSchema = z
+  .string()
+  .trim()
+  .max(CREDENTIAL_DESCRIPTION_MAX_CHARS, `说明最多 ${CREDENTIAL_DESCRIPTION_MAX_CHARS} 个字符。`)
+
+export const CredentialDomainsSchema = z.array(ExtensionNetworkDomainSchema).max(32)
+
+/**
+ * Names a credential's environment variable cannot take: the shell, the tools' own configuration, and the variables
+ * linked accounts give commands (`GH_TOKEN` and the `gh` settings).
+ */
+const RESERVED_COMMAND_ENV = new Set([
+  'PATH',
+  'HOME',
+  'USER',
+  'LOGNAME',
+  'SHELL',
+  'PWD',
+  'OLDPWD',
+  'TMPDIR',
+  'TEMP',
+  'TMP',
+  'LANG',
+  'TERM',
+  'NODE_OPTIONS',
+  'NODE_PATH',
+  'GH_TOKEN',
+  'GH_CONFIG_DIR',
+  'GH_PROMPT_DISABLED',
+  'GH_NO_UPDATE_NOTIFIER',
+  'GH_NO_EXTENSION_UPDATE_NOTIFIER',
+  'GIT_TERMINAL_PROMPT',
+  'GIT_CONFIG_COUNT',
+])
+const RESERVED_COMMAND_ENV_PREFIXES = ['LC_', 'LD_', 'DYLD_', 'GIT_CONFIG_', 'NEKRO_', 'DSH_']
+
+/** The environment variable a program credential reaches commands under. */
+export const CredentialEnvNameSchema = z
+  .string()
+  .trim()
+  .max(64)
+  .regex(/^[A-Z_][A-Z0-9_]*$/u, '环境变量名只能使用大写字母、数字和下划线，且不能以数字开头。')
+  .refine(
+    (name) =>
+      !RESERVED_COMMAND_ENV.has(name) && !RESERVED_COMMAND_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)),
+    '这个环境变量名由系统使用，请换一个。',
+  )
+
+export const CredentialValueSchema = z.string().min(1).max(CREDENTIAL_VALUE_MAX_CHARS)
+
+/** What uses one credential right now: extension secret fields bound to it and agents whose commands receive it. */
+export const CredentialUsersSchema = z
+  .object({
+    extensions: z.array(
+      z
+        .object({
+          extensionId: ExtensionIdSchema,
+          name: z.string(),
+          /** Agents whose own configuration binds it; empty when only the host configuration does. */
+          agentIds: z.array(AgentIdSchema),
+          host: z.boolean(),
+        })
+        .strict(),
+    ),
+    /** Agents with commands enabled whose commands receive it. */
+    commandAgents: z.array(AgentIdSchema),
+  })
+  .strict()
+export type CredentialUsers = z.output<typeof CredentialUsersSchema>
+
+export const CredentialViewSchema = z
+  .object({
+    id: CredentialIdSchema,
+    name: CredentialNameSchema,
+    description: z.string(),
+    usage: CredentialUsageSchema,
+    domains: z.array(z.string()),
+    agentScope: CredentialAgentScopeSchema,
+    autoUse: z.boolean(),
+    /** Program credentials: the environment variable agents' commands receive it under, or `null` when they do not. */
+    envName: z.string().nullable(),
+    /** Agents an administrator let use it while automatic use is off. */
+    approvedAgentIds: z.array(AgentIdSchema),
+    /** False when the stored value is too short to hide from tool results, or cannot be read. */
+    redactable: z.boolean(),
+    /** False when the stored value cannot be read any more; the entry stays so it can be replaced. */
+    available: z.boolean(),
+    usedBy: CredentialUsersSchema,
+    createdAt: z.number().int().nonnegative(),
+    updatedAt: z.number().int().nonnegative(),
+    lastUsedAt: z.number().int().nonnegative().nullable(),
+  })
+  .strict()
+export type CredentialView = z.output<typeof CredentialViewSchema>
+
+/** A model provider listed with the credentials; `open` lets agents and extensions call it through the host. */
+export const ModelProviderAccessSchema = z
+  .object({
+    provider: z.string().min(1),
+    name: z.string(),
+    open: z.boolean(),
+  })
+  .strict()
+export type ModelProviderAccess = z.output<typeof ModelProviderAccessSchema>
+
+/**
+ * An agent asked for a credential that does not exist yet. The settings link pre-fills the add form; saving a
+ * credential with this name wakes the agent in the channel it asked from.
+ */
+export const CredentialRequestViewSchema = z
+  .object({
+    id: z.string().min(1).max(64),
+    name: CredentialNameSchema,
+    purpose: z.string(),
+    domains: z.array(z.string()),
+    usage: CredentialUsageSchema,
+    agentId: AgentIdSchema,
+    channelId: ChannelIdSchema.nullable(),
+    createdAt: z.number().int().nonnegative(),
+    /** Settings route that opens the add form pre-filled, see {@link credentialRequestRoute}. */
+    route: z.string(),
+  })
+  .strict()
+export type CredentialRequestView = z.output<typeof CredentialRequestViewSchema>
+
+export const CredentialsViewSchema = z
+  .object({
+    credentials: z.array(CredentialViewSchema),
+    modelProviders: z.array(ModelProviderAccessSchema),
+    requests: z.array(CredentialRequestViewSchema),
+  })
+  .strict()
+export type CredentialsView = z.output<typeof CredentialsViewSchema>
+
+export const CreateCredentialRequestSchema = z
+  .object({
+    name: CredentialNameSchema,
+    description: CredentialDescriptionSchema.default(''),
+    agentScope: CredentialAgentScopeSchema.default({ all: true }),
+    autoUse: z.boolean().default(true),
+    usage: CredentialUsageSchema.default('request'),
+    domains: CredentialDomainsSchema.default([]),
+    /** Program credentials only. */
+    envName: CredentialEnvNameSchema.optional(),
+    value: CredentialValueSchema,
+    /** The agent request this form was opened from, if any. */
+    requestId: z.string().min(1).max(64).optional(),
+  })
+  .strict()
+export type CreateCredentialRequest = z.input<typeof CreateCredentialRequestSchema>
+
+/** Metadata changes; omitted fields keep their value. */
+export const UpdateCredentialRequestSchema = z
+  .object({
+    name: CredentialNameSchema.optional(),
+    description: CredentialDescriptionSchema.optional(),
+    usage: CredentialUsageSchema.optional(),
+    domains: CredentialDomainsSchema.optional(),
+    agentScope: CredentialAgentScopeSchema.optional(),
+    autoUse: z.boolean().optional(),
+    /** `null` stops giving it to commands; only program credentials take one. */
+    envName: CredentialEnvNameSchema.nullable().optional(),
+    /** Replaces the agents allowed to use it while automatic use is off, for example to withdraw an approval. */
+    approvedAgentIds: z.array(AgentIdSchema).max(256).optional(),
+  })
+  .strict()
+export type UpdateCredentialRequest = z.output<typeof UpdateCredentialRequestSchema>
+
+export const ReplaceCredentialValueRequestSchema = z.object({ value: CredentialValueSchema }).strict()
+export type ReplaceCredentialValueRequest = z.output<typeof ReplaceCredentialValueRequestSchema>
+
+/** Removing a credential that is in use needs `confirm`; without it the result lists who uses it. */
+export const RemoveCredentialRequestSchema = z.object({ confirm: z.boolean().default(false) }).strict()
+
+export const RemoveCredentialResultSchema = z.discriminatedUnion('removed', [
+  z.object({ removed: z.literal(true), view: CredentialsViewSchema }).strict(),
+  z.object({ removed: z.literal(false), usedBy: CredentialUsersSchema }).strict(),
+])
+export type RemoveCredentialResult = z.output<typeof RemoveCredentialResultSchema>
+
+export const CredentialConsumerKindSchema = z.enum(['extension', 'command', 'mcp', 'model'])
+
+/** One recorded use. The newest 500 per credential are kept, none older than 90 days. */
+export const CredentialUseSchema = z
+  .object({
+    at: z.number().int().nonnegative(),
+    agentId: AgentIdSchema.nullable(),
+    channelId: ChannelIdSchema.nullable(),
+    requesterMemberId: z.string().nullable(),
+    consumerKind: CredentialConsumerKindSchema,
+    consumerId: z.string(),
+    /** Extension display name or MCP server name, when it is still known. */
+    consumerName: z.string().nullable(),
+    targetHost: z.string().nullable(),
+  })
+  .strict()
+export type CredentialUse = z.output<typeof CredentialUseSchema>
+
+export const CredentialUsesViewSchema = z.object({ uses: z.array(CredentialUseSchema) }).strict()
+
+export const SetModelProviderAccessRequestSchema = z.object({ open: z.boolean() }).strict()
+
+/**
+ * The settings route that opens the add form pre-filled from an agent's request: the credential section with `add=1`
+ * plus `name`, `purpose`, `domains` (comma separated), `usage` and `request` (the request id) as query parameters.
+ */
+export const credentialRequestRoute = (request: {
+  readonly id: string
+  readonly name: string
+  readonly purpose: string
+  readonly domains: readonly string[]
+  readonly usage: CredentialUsage
+}): string => {
+  const query = new URLSearchParams({ add: '1', name: request.name, request: request.id, usage: request.usage })
+  if (request.purpose !== '') query.set('purpose', request.purpose)
+  if (request.domains.length > 0) query.set('domains', request.domains.join(','))
+  return `/settings/credentials?${query.toString()}`
+}
+
+/** Secret fields of an extension configuration layer bound to a named credential, by field. */
+export const BoundCredentialsSchema = z.record(z.string(), CredentialIdSchema)
+
+/** Binds secret fields to named credentials; `null` removes the binding and leaves the field unset. */
+export const CredentialBindingsRequestSchema = z.record(z.string(), CredentialIdSchema.nullable())

package/src/domain.ts

@@ -18,6 +18,15 @@ export const MessageDeliverySummarySchema = z
       )
       .max(20),
     omittedIssues: z.number().int().nonnegative().optional(),
+    /** Extensions that changed the message before it was sent, the content they produced and what they appended. */
+    processing: z
+      .object({
+        processedBy: z.array(z.string()),
+        parts: z.array(z.unknown()).optional(),
+        followUps: z.array(z.string()).optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict()
 
@@ -50,9 +59,13 @@ export const HostUiPageInstanceIdSchema = brandedId('hup', 'HostUiPageInstanceId
 export const AuthoringTaskIdSchema = brandedId('aut', 'AuthoringTaskId')
 export const AuthoringAttemptIdSchema = brandedId('aua', 'AuthoringAttemptId')
 export const SubConversationIdSchema = brandedId('cnv', 'SubConversationId')
+export const CredentialIdSchema = brandedId('crd', 'CredentialId')
+export const LinkedAccountIdSchema = brandedId('acc', 'LinkedAccountId')
 
 export type AgentId = z.infer<typeof AgentIdSchema>
 export type SubConversationId = z.infer<typeof SubConversationIdSchema>
+export type CredentialId = z.infer<typeof CredentialIdSchema>
+export type LinkedAccountId = z.infer<typeof LinkedAccountIdSchema>
 export type AgentRevisionId = z.infer<typeof AgentRevisionIdSchema>
 export type ConnectionId = z.infer<typeof ConnectionIdSchema>
 export type ConnectionEventId = z.infer<typeof ConnectionEventIdSchema>
@@ -228,8 +241,8 @@ export interface DshPluginActivationRecord {
 export interface DshPluginDiagnosticRecord {
   readonly entryId: DshPluginEntryId
   readonly targetKey: string
-  readonly status: 'active' | 'load-failed' | 'restore-failed' | 'dispose-failed'
-  readonly phase: 'import' | 'apply' | 'update' | 'dispose' | 'restore'
+  readonly status: 'active' | 'pending' | 'load-failed' | 'restore-failed' | 'dispose-failed'
+  readonly phase: 'import' | 'dependency' | 'apply' | 'update' | 'dispose' | 'restore'
   readonly message?: string
   readonly observedAt: number
 }

package/src/extension-capabilities.ts

@@ -6,8 +6,13 @@ import { z } from 'zod'
  * ships; never reuse a level for a different meaning. Level 7 is Manifest V7 (host instance + agent attachments); level 8 adds the asset library, image info, tool result
  * images, the search index and host-layer model calls. Level 9 adds the structured logger and explicit chat commands. Level 10 adds version lineage, the data version with its
  * migration hook and administrator-only commands. Level 11 lists the pictures of an inbound message to inbound hooks.
+ * Level 12 adds credential placeholders (`secrets.placeholder`) that `http.fetch` fills for the credential's domains.
+ * Level 13 adds outbound processing (`harness.onOutbound`, `permissions.agent.outbound`).
  */
-export const EXTENSION_SDK_LEVEL = 11
+export const EXTENSION_SDK_LEVEL = 13
+
+/** Outbound processing needs this level; packages that declare `permissions.agent.outbound` declare it. */
+export const EXTENSION_OUTBOUND_SDK_LEVEL = 13
 
 /** Lineage, `dataVersion` and administrator-only commands need this level; packages that carry them declare it. */
 export const EXTENSION_GOVERNANCE_SDK_LEVEL = 10
@@ -23,6 +28,8 @@ export const EXTENSION_SDK_RELEASES: readonly { readonly level: number; readonly
   { level: 9, version: '0.6.0' },
   { level: 10, version: '0.6.0' },
   { level: 11, version: '0.6.0' },
+  { level: 12, version: '0.7.0' },
+  { level: 13, version: '0.7.0' },
 ]
 
 /** The oldest NekroNXT version that supports `level`; undefined for a level no release supports yet. */
@@ -128,6 +135,32 @@ export const ExtensionInboundHookCapabilitySchema = z
   .strict()
 export type ExtensionInboundHookCapability = z.output<typeof ExtensionInboundHookCapabilitySchema>
 
+export const EXTENSION_OUTBOUND_MAX_TIMEOUT_MS = 15_000
+
+/**
+ * Outbound processing of the agent's own messages. `read` sees each message after it was delivered; `transform` may
+ * replace its content or append messages before it is sent; `cancel` may stop it. `onTimeout` decides what happens
+ * when the handler times out or throws before sending: `send` (default) sends the message as it is.
+ */
+export const ExtensionOutboundCapabilitySchema = z
+  .object({
+    read: z.literal(true).optional(),
+    transform: z.literal(true).optional(),
+    cancel: z.literal(true).optional(),
+    timeoutMs: z.number().int().min(100).max(EXTENSION_OUTBOUND_MAX_TIMEOUT_MS),
+    onTimeout: z.enum(['send', 'cancel']).optional(),
+  })
+  .strict()
+  .refine(
+    (value) => value.read === true || value.transform === true || value.cancel === true,
+    'outbound 至少声明 read、transform 或 cancel 中的一项。',
+  )
+export type ExtensionOutboundCapability = z.output<typeof ExtensionOutboundCapabilitySchema>
+
+/** Whether the extension takes part before sending (and so in the agent's processing order). */
+export const outboundProcessesBeforeSend = (outbound: ExtensionOutboundCapability | undefined): boolean =>
+  outbound?.transform === true || outbound?.cancel === true
+
 export const EXTENSION_JOB_MAX_RUNTIME = 50
 
 export const ExtensionDeclaredJobSchema = z
@@ -255,10 +288,14 @@ export const ExtensionModelsCapabilitySchema = z
   .strict()
 export type ExtensionModelsCapability = z.output<typeof ExtensionModelsCapabilitySchema>
 
-/** A header or environment value: literal text, or the current value of a `meta.role: 'secret'` config field. */
+/**
+ * A header or environment value: literal text, the current value of a `meta.role: 'secret'` config field, or a named
+ * credential (by id or name) that the agent may use.
+ */
 export const ExtensionMcpValueSchema = z.union([
   z.string().max(4096),
   z.object({ secret: z.string().trim().min(1).max(64) }).strict(),
+  z.object({ credential: z.string().trim().min(1).max(64) }).strict(),
 ])
 export type ExtensionMcpValue = z.output<typeof ExtensionMcpValueSchema>
 
@@ -315,6 +352,8 @@ const McpFormValueSchema = z
     name: z.string().regex(/^[A-Za-z_][A-Za-z0-9_-]{0,127}$/u, '名称只能包含字母、数字、下划线和连字符。'),
     value: z.string().max(4096),
     secret: z.boolean().default(false),
+    /** Takes the value from this named credential instead; `value` and `secret` are then ignored. */
+    credential: z.string().trim().min(1).max(64).optional(),
   })
   .strict()
 
@@ -344,7 +383,7 @@ export const mcpSecretFields = (mcp: ExtensionMcpCapability | undefined): readon
   ...new Set(
     (mcp?.servers ?? []).flatMap((server) =>
       Object.values(server.transport === 'stdio' ? server.env : server.headers).flatMap((value) =>
-        typeof value === 'string' ? [] : [value.secret],
+        typeof value === 'string' || !('secret' in value) ? [] : [value.secret],
       ),
     ),
   ),
@@ -373,6 +412,7 @@ export const ExtensionCapabilitiesSchema = z
       .strict()
       .optional(),
     inboundHook: ExtensionInboundHookCapabilitySchema.optional(),
+    outbound: ExtensionOutboundCapabilitySchema.optional(),
     jobs: ExtensionJobsCapabilitySchema.optional(),
     platform: ExtensionPlatformCapabilitySchema.optional(),
     llm: ExtensionLlmCapabilitySchema.optional(),
@@ -484,6 +524,18 @@ export const extensionCapabilitiesExpand = (
   ) {
     return true
   }
+  const outbound = next.outbound
+  const previousOutbound = previous?.outbound
+  if (
+    outbound !== undefined &&
+    (previousOutbound === undefined ||
+      (outbound.read === true && previousOutbound.read !== true) ||
+      (outbound.transform === true && previousOutbound.transform !== true) ||
+      (outbound.cancel === true && previousOutbound.cancel !== true) ||
+      (outbound.onTimeout === 'cancel' && previousOutbound.onTimeout !== 'cancel'))
+  ) {
+    return true
+  }
   if (
     next.jobs?.runtime !== undefined &&
     (previous?.jobs?.runtime === undefined || next.jobs.runtime.maxActive > previous.jobs.runtime.maxActive)
@@ -598,6 +650,21 @@ export const summarizeExtensionCapabilities = (
       ...(effects === '' ? {} : { detail: `可以${effects}` }),
     })
   }
+  const outbound = capabilities.outbound
+  if (outbound !== undefined) {
+    if (outbound.transform === true) {
+      items.push({ key: 'outbound.transform', risk: 'high', label: '在智能体的消息发出前修改内容或追加消息' })
+    }
+    if (outbound.cancel === true) {
+      items.push({ key: 'outbound.cancel', risk: 'high', label: '取消智能体要发出的消息' })
+    }
+    if (outbound.read === true) {
+      items.push({ key: 'outbound.read', risk: 'sensitive', label: '查看智能体发出的每条消息' })
+    }
+    if (outbound.onTimeout === 'cancel' && (outbound.transform === true || outbound.cancel === true)) {
+      items.push({ key: 'outbound.onTimeout', risk: 'high', label: '这个扩展出错时，智能体的消息会发不出去' })
+    }
+  }
   const jobs = capabilities.jobs
   if (jobs?.declared !== undefined && jobs.declared.length > 0) {
     items.push({

package/src/extension-ui.ts

@@ -4,6 +4,7 @@ import {
   HostLayerCapabilitiesSchema,
   hostLayerAsCapabilities,
   EXTENSION_SDK_BASE_LEVEL,
+  EXTENSION_OUTBOUND_SDK_LEVEL,
 } from './extension-capabilities.js'
 import { ExtensionIdSchema, ExtensionRevisionIdSchema, HostUiPageInstanceIdSchema } from './domain.js'
 import { ConfigSchemaDocumentSchema } from './config-schema.js'
@@ -554,6 +555,8 @@ export const requiredExtensionSdkLevel = (
     permissions?.host?.index === undefined && permissions?.agent?.index === undefined ? undefined : '检索索引',
     permissions?.host?.models === undefined ? undefined : '本机层模型调用',
   ].filter((name): name is string => name !== undefined)
+  if (permissions?.agent?.outbound !== undefined)
+    return { level: EXTENSION_OUTBOUND_SDK_LEVEL, capabilities: ['出站处理'] }
   return level8.length > 0
     ? { level: 8, capabilities: [...new Set(level8)] }
     : { level: EXTENSION_SDK_BASE_LEVEL, capabilities: [] }