@nekro-nxt/contracts 0.5.0 → 0.7.0

package/src/index.ts

@@ -5,6 +5,8 @@ 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'
 
@@ -12,3 +14,4 @@ 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/management-api.ts

@@ -124,7 +124,7 @@ export const ClientNotificationSchema = z
     route: z
       .string()
       .regex(
-        /^\/(?:(?:live|channels|agents|workshop|wiring|settings|community|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)])