@nekro-nxt/contracts 0.5.0 → 0.7.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
 }