@nekro-nxt/contracts 0.4.0 → 0.6.0

package/src/index.ts

@@ -5,5 +5,13 @@ export * from './host-api.js'
 export * from './management-api.js'
 export * from './runtime-compatibility.js'
 export * from './extension-capabilities.js'
+export * from './credentials.js'
+export * from './linked-accounts.js'
 export * from './community.js'
 export * from './community-personas.js'
+
+export * from './commands.js'
+export * from './logs.js'
+export * from './community-feedback.js'
+export * from './community-feedback-host.js'
+export * from './response-timing.js'

package/src/linked-accounts.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod'
+import { AgentIdSchema, ChannelIdSchema, LinkedAccountIdSchema } from './domain.js'
+
+/**
+ * Linked accounts (设置 → 关联账号): third-party accounts that agents' commands act as. The library only keeps them;
+ * an agent's commands receive an account only through its `commandAccounts` grant (命令账号授权 A1、A2). Tokens are
+ * write-only; every view below carries metadata only.
+ */
+
+/** Platforms the host can link accounts of; each grant names one account per platform. */
+export const LinkedAccountPlatformIdSchema = z.enum(['github'])
+export type LinkedAccountPlatformId = z.output<typeof LinkedAccountPlatformIdSchema>
+
+/** How an account is added: a typed token, or the token of a login the platform's local CLI holds (read once). */
+export const LinkedAccountMethodSchema = z.enum(['token', 'gh-login'])
+export type LinkedAccountMethod = z.output<typeof LinkedAccountMethodSchema>
+
+/** A login the local `gh` holds, offered as a quick way to link a GitHub account. */
+export const LocalGithubLoginSchema = z.object({ login: z.string().trim().min(1), active: z.boolean() }).strict()
+
+const tokenFields = { method: z.literal('token'), token: z.string().trim().min(1).max(512) }
+const ghLoginFields = { method: z.literal('gh-login'), login: z.string().trim().min(1).max(128) }
+
+/** Where a token comes from: typed, or read once from a login of the platform's local CLI. */
+export const LinkedAccountTokenSourceSchema = z.discriminatedUnion('method', [
+  z.object(tokenFields).strict(),
+  z.object(ghLoginFields).strict(),
+])
+export type LinkedAccountTokenSource = z.output<typeof LinkedAccountTokenSourceSchema>
+
+export const LinkedAccountViewSchema = z
+  .object({
+    id: LinkedAccountIdSchema,
+    platform: LinkedAccountPlatformIdSchema,
+    /** The account name on the platform, as the platform reported it when the token was verified. */
+    login: z.string(),
+    /** Token scopes where the platform reports them (GitHub classic tokens); `null` otherwise. */
+    scopes: z.array(z.string()).nullable(),
+    source: LinkedAccountMethodSchema,
+    /** False when the stored token cannot be read any more; the account stays so it can be replaced or removed. */
+    available: z.boolean(),
+    /** Agents whose capabilities grant this account. */
+    grantedAgentIds: z.array(AgentIdSchema),
+    createdAt: z.number().int().nonnegative(),
+    updatedAt: z.number().int().nonnegative(),
+    lastUsedAt: z.number().int().nonnegative().nullable(),
+  })
+  .strict()
+export type LinkedAccountView = z.output<typeof LinkedAccountViewSchema>
+
+/** Links an account: the platform plus how its token is given. */
+export const AddLinkedAccountRequestSchema = z.discriminatedUnion('method', [
+  z.object({ platform: LinkedAccountPlatformIdSchema, ...tokenFields }).strict(),
+  z.object({ platform: LinkedAccountPlatformIdSchema, ...ghLoginFields }).strict(),
+])
+export type AddLinkedAccountRequest = z.output<typeof AddLinkedAccountRequestSchema>
+
+/** A new token for an account; it must belong to the same account on the platform. */
+export const ReplaceLinkedAccountTokenRequestSchema = LinkedAccountTokenSourceSchema
+export type ReplaceLinkedAccountTokenRequest = z.output<typeof ReplaceLinkedAccountTokenRequestSchema>
+
+/** Removing a granted account needs `confirm`; without it the result lists the agents it is granted to. */
+export const RemoveLinkedAccountRequestSchema = z.object({ confirm: z.boolean().default(false) }).strict()
+
+/** One recorded use: an agent's command environment carried the account. Newest 500 per account, none over 90 days. */
+export const LinkedAccountUseSchema = z
+  .object({
+    at: z.number().int().nonnegative(),
+    agentId: AgentIdSchema.nullable(),
+    channelId: ChannelIdSchema.nullable(),
+    consumerKind: z.enum(['command']),
+    consumerId: z.string(),
+  })
+  .strict()
+export type LinkedAccountUse = z.output<typeof LinkedAccountUseSchema>
+
+export const LinkedAccountUsesViewSchema = z.object({ uses: z.array(LinkedAccountUseSchema) }).strict()

package/src/logs.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod'
+
+/** Log summaries are labels; leave structured diagnostics and stacks untouched. */
+export function formatLogMessage(message: string): string {
+  return message.trimEnd().replace(/[。.]$/u, '')
+}
+
+export const hostLogLevelSchema = z.enum(['debug', 'info', 'warn', 'error'])
+export type HostLogLevel = z.infer<typeof hostLogLevelSchema>
+/** Write-only, owner-bound SDK capability. No caller-supplied identity fields. */
+export interface NxtLogger {
+  debug(message: string, details?: unknown): void
+  info(message: string, details?: unknown): void
+  warn(message: string, details?: unknown): void
+  error(message: string, details?: unknown): void
+}
+export const hostLogSourceKindSchema = z.enum(['system', 'dsh-plugin', 'extension', 'connection', 'unknown'])
+export type HostLogSourceKind = z.infer<typeof hostLogSourceKindSchema>
+export const hostLogSourceSchema = z
+  .object({
+    kind: hostLogSourceKindSchema,
+    id: z.string().min(1).max(512),
+    name: z.string().min(1).max(512),
+    version: z.string().max(512).optional(),
+    component: z.string().max(512).optional(),
+  })
+  .strict()
+export type HostLogSource = z.infer<typeof hostLogSourceSchema>
+export const hostLogScopeSchema = z
+  .object({
+    extensionId: z.string().max(512).optional(),
+    revisionId: z.string().max(512).optional(),
+    connectionId: z.string().max(512).optional(),
+    agentId: z.string().max(512).optional(),
+    channelId: z.string().max(512).optional(),
+    sessionId: z.string().max(512).optional(),
+    episodeId: z.string().max(512).optional(),
+    operationId: z.string().max(512).optional(),
+  })
+  .strict()
+export type HostLogScope = z.infer<typeof hostLogScopeSchema>
+export const hostLogEntrySchema = z
+  .object({
+    id: z.string(),
+    sequence: z.number().int().nonnegative(),
+    timestamp: z.iso.datetime(),
+    runId: z.string(),
+    level: hostLogLevelSchema,
+    message: z.string(),
+    source: hostLogSourceSchema,
+    scope: hostLogScopeSchema.optional(),
+    details: z.json().optional(),
+    code: z.string().optional(),
+    redacted: z.boolean(),
+    truncated: z.boolean(),
+  })
+  .strict()
+export type HostLogEntry = z.infer<typeof hostLogEntrySchema>
+export interface HostLogInput {
+  formatArgs?: readonly unknown[]
+  level: HostLogLevel
+  message: string
+  source: HostLogSource
+  scope?: HostLogScope
+  details?: unknown
+  code?: string
+}
+export const hostLogQuerySchema = z
+  .object({
+    levels: z.array(hostLogLevelSchema).max(4).optional(),
+    sourceKinds: z.array(hostLogSourceKindSchema).max(5).optional(),
+    sourceIds: z.array(z.string().max(512)).max(100).optional(),
+    sources: z
+      .array(hostLogSourceSchema.pick({ kind: true, id: true }))
+      .max(100)
+      .optional(),
+    scope: hostLogScopeSchema.optional(),
+    keyword: z.string().max(1000).optional(),
+    from: z.iso.datetime().optional(),
+    to: z.iso.datetime().optional(),
+    olderCursor: z.string().max(128).optional(),
+    afterCursor: z.string().max(128).optional(),
+    headCursor: z.string().max(128).optional(),
+    limit: z.number().int().min(1).max(500).optional(),
+  })
+  .strict()
+export type HostLogQuery = z.infer<typeof hostLogQuerySchema>
+export const hostLogPageSchema = z
+  .object({
+    entries: z.array(hostLogEntrySchema),
+    olderCursor: z.string().nullable(),
+    headCursor: z.string(),
+    hasMore: z.boolean(),
+    gap: z.enum(['expired', 'reset']).optional(),
+  })
+  .strict()
+export type HostLogPage = z.infer<typeof hostLogPageSchema>
+export const hostLogSettingsSchema = z
+  .object({
+    retentionDays: z.number().int().min(1).max(30),
+    maxSizeMiB: z.number().int().min(64).max(2048),
+    revision: z.number().int().nonnegative(),
+  })
+  .strict()
+export type HostLogSettings = z.infer<typeof hostLogSettingsSchema>
+export const hostLogSettingsUpdateSchema = hostLogSettingsSchema
+export const hostLogDebugRequestSchema = z
+  .object({
+    source: hostLogSourceSchema.pick({ kind: true, id: true }).optional(),
+    durationMinutes: z.union([z.literal(5), z.literal(15), z.literal(30)]).default(15),
+  })
+  .strict()
+export type HostLogDebugRequest = z.infer<typeof hostLogDebugRequestSchema>
+export const hostLogDebugLeaseSchema = hostLogDebugRequestSchema.extend({ id: z.string(), expiresAt: z.iso.datetime() })
+export type HostLogDebugLease = z.infer<typeof hostLogDebugLeaseSchema>
+export const hostLogStatusSchema = z
+  .object({
+    state: z.enum(['ready', 'degraded', 'closed']),
+    runId: z.string(),
+    headCursor: z.string(),
+    bytes: z.number().nonnegative(),
+    count: z.number().int().nonnegative(),
+    oldestTimestamp: z.iso.datetime().nullable(),
+    newestTimestamp: z.iso.datetime().nullable(),
+    queuedBytes: z.number().nonnegative(),
+    droppedCount: z.number().int().nonnegative(),
+    debugLeases: z.array(hostLogDebugLeaseSchema),
+    error: z.string().optional(),
+  })
+  .strict()
+export type HostLogStatus = z.infer<typeof hostLogStatusSchema>
+export const hostLogStreamEventSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('entries'), entries: z.array(hostLogEntrySchema), cursor: z.string() }),
+  z.object({ type: z.literal('gap'), reason: z.enum(['expired', 'reset', 'overflow']), cursor: z.string() }),
+  z.object({ type: z.literal('status'), status: hostLogStatusSchema }),
+])
+export type HostLogStreamEvent = z.infer<typeof hostLogStreamEventSchema>
+export type HostLogExportFormat = 'text' | 'jsonl'

package/src/management-api.ts

@@ -124,7 +124,7 @@ export const ClientNotificationSchema = z
     route: z
       .string()
       .regex(
-        /^\/(?:(?:live|channels|agents|workshop|wiring|settings|apps|work|connections|users|extensions)(?:\/[^?#]*)?)?$/u,
+        /^\/(?:(?:live|channels|agents|workshop|wiring|settings|community|apps|work|connections|users|extensions)(?:\/[^?#]*)?)?(?:\?[^#]*)?$/u,
       )
       .optional(),
   })

package/src/response-timing.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod'
+
+/** Bounds of the numeric response timing settings; the host rejects values outside them. */
+export const RESPONSE_TIMING_LIMITS = {
+  waitMaxQuietSeconds: { min: 5, max: 300 },
+  waitMaxTotalSeconds: { min: 10, max: 900 },
+  debounceSeconds: { min: 0, max: 30 },
+  debounceMaxSeconds: { min: 1, max: 120 },
+  debounceMaxMessages: { min: 1, max: 20 },
+  attentionSeconds: { min: 5, max: 600 },
+  midWakesPerMinute: { min: 1, max: 30 },
+} as const
+
+const bounded = (key: keyof typeof RESPONSE_TIMING_LIMITS) =>
+  z.number().int().min(RESPONSE_TIMING_LIMITS[key].min).max(RESPONSE_TIMING_LIMITS[key].max).optional()
+
+/**
+ * Per-binding timing of when the agent speaks (Decision 2026-10-31 响应时机与智能响应). Every field is optional: an
+ * omitted one uses {@link RESPONSE_TIMING_DEFAULTS}. Waiting applies to every policy that answers messages; the rest
+ * only to `smart`.
+ */
+export const ResponseTimingSettingsSchema = z
+  .object({
+    /** The agent may end a turn with `waiting-for-more` and be woken when the speaker goes quiet. */
+    waitEnabled: z.boolean().optional(),
+    /** Longest quiet period one wait may ask for. */
+    waitMaxQuietSeconds: bounded('waitMaxQuietSeconds'),
+    /** Longest the agent may keep waiting for one person, counted from the first wait. */
+    waitMaxTotalSeconds: bounded('waitMaxTotalSeconds'),
+    /** Smart: wait for the speaker to stay quiet this long before a turn starts; 0 starts at once. */
+    debounceSeconds: bounded('debounceSeconds'),
+    /** Smart: start anyway once this long has passed since the first message. */
+    debounceMaxSeconds: bounded('debounceMaxSeconds'),
+    /** Smart: start anyway once this many messages from the speaker are collected. */
+    debounceMaxMessages: bounded('debounceMaxMessages'),
+    /** Smart: a message that contains the agent's name or an alias wakes it. */
+    nameWake: z.boolean().optional(),
+    /** Smart: after someone talks with the agent, their next messages wake it for a while. */
+    attentionWake: z.boolean().optional(),
+    attentionSeconds: bounded('attentionSeconds'),
+    /** Smart: name and attention wakes per channel per minute; strong signals are never limited. */
+    midWakesPerMinute: bounded('midWakesPerMinute'),
+  })
+  .strict()
+
+export type ResponseTimingSettings = z.infer<typeof ResponseTimingSettingsSchema>
+
+export type ResolvedResponseTiming = {
+  readonly [K in keyof ResponseTimingSettings]-?: NonNullable<ResponseTimingSettings[K]>
+}
+
+export const RESPONSE_TIMING_DEFAULTS: ResolvedResponseTiming = {
+  waitEnabled: true,
+  waitMaxQuietSeconds: 60,
+  waitMaxTotalSeconds: 120,
+  debounceSeconds: 3,
+  debounceMaxSeconds: 30,
+  debounceMaxMessages: 5,
+  nameWake: true,
+  attentionWake: true,
+  attentionSeconds: 60,
+  midWakesPerMinute: 3,
+}
+
+/** Shortest quiet period a wait may ask for, whatever the channel allows. */
+export const RESPONSE_WAIT_MIN_QUIET_SECONDS = 5
+
+export const resolveResponseTiming = (settings: ResponseTimingSettings | undefined): ResolvedResponseTiming => ({
+  ...RESPONSE_TIMING_DEFAULTS,
+  ...Object.fromEntries(Object.entries(settings ?? {}).filter(([, value]) => value !== undefined)),
+})
+
+/** Extra names that wake the agent in smart mode; the display name always counts too. */
+export const AgentAliasesSchema = z
+  .array(z.string().trim().min(1).max(32))
+  .max(16)
+  .transform((aliases) => [...new Set(aliases)])