advisers 0.2.0-preview.71 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/model.js CHANGED
@@ -4,6 +4,13 @@
4
4
  * Thinking-mode reasoning_content is returned only as wire state; callers must
5
5
  * never persist it or expose it as evidence.
6
6
  */
7
+ import {
8
+ inspectMessages,
9
+ normalizeProviderRefusal,
10
+ safetyErrorFrom,
11
+ buildAuditReason,
12
+ } from './safety/index.js'
13
+
7
14
  const RETRY_STATUS = new Set([429, 500, 502, 503, 504])
8
15
  const EFFORTS = new Set(['low', 'high', 'max'])
9
16
 
@@ -27,6 +34,102 @@ const TASK_EFFORT = {
27
34
  max: 'max',
28
35
  }
29
36
 
37
+ // ---------------------------------------------------------------------------
38
+ // content safety (local rule layer; never sends the original text anywhere)
39
+ //
40
+ // chatCompletion is the single choke point for every model call (chat, agent,
41
+ // capture, review, doc-review). Outbound messages and the returned assistant
42
+ // message are classified locally before/after the request:
43
+ // block -> ContentSafetyError (code/ruleIds/rulesetVersion,
44
+ // message has no original text; no network request is
45
+ // made for a blocked request)
46
+ // warn/confirm/redact -> request proceeds, safetyWarnings is attached to
47
+ // the result (additive optional field)
48
+ // The classifier surface is model.output (the registered surface for
49
+ // model-bound text; egress, no local-file downgrade). Wiring is documented in
50
+ // docs/CONTENT-SAFETY.md section 8.
51
+ // ---------------------------------------------------------------------------
52
+ const SAFETY_SURFACE = 'model.output'
53
+ /** Disable the optional DeepSeek safety_check network-side gate with '0'. */
54
+ const SAFETY_CLOUD_ENV = 'ADVISERS_SAFETY_CLOUD'
55
+
56
+ function safetyWarningOf(result, direction) {
57
+ if (!result || result.action === 'allow') return null
58
+ const surface = result.surface || SAFETY_SURFACE
59
+ const ruleIds = Array.isArray(result.ruleIds) ? [...result.ruleIds] : []
60
+ const auditReason = buildAuditReason({
61
+ rulesetVersion: result.rulesetVersion,
62
+ surface,
63
+ action: result.action,
64
+ code: result.code,
65
+ ruleIds,
66
+ evidenceHash: result.evidenceHash,
67
+ })
68
+ return {
69
+ direction,
70
+ action: result.action,
71
+ code: result.code,
72
+ categories: Array.isArray(result.categories) ? [...result.categories] : [],
73
+ ruleIds,
74
+ surface,
75
+ rulesetVersion: result.rulesetVersion,
76
+ evidenceHash: result.evidenceHash || null,
77
+ crisis: Boolean(result.crisis),
78
+ auditReason,
79
+ }
80
+ }
81
+
82
+ function safetyWarningsOf(result, direction) {
83
+ const warning = safetyWarningOf(result, direction)
84
+ return warning ? [warning] : []
85
+ }
86
+
87
+ /** Throw a typed, text-free error for a blocked pre-request classification. */
88
+ function throwIfBlocked(result, provider, direction) {
89
+ if (!result || result.action !== 'block') return
90
+ const error = safetyErrorFrom(result, { provider, surface: SAFETY_SURFACE })
91
+ error.direction = direction
92
+ throw error
93
+ }
94
+
95
+ /** Map a provider-side refusal/400 to a typed, text-free ContentSafetyError. */
96
+ function throwIfProviderRefused(payload, { provider, status, direction }) {
97
+ const refusal = normalizeProviderRefusal(payload, { status })
98
+ if (!refusal.blocked) return
99
+ const error = safetyErrorFrom(
100
+ { action: 'block', code: refusal.code, categories: [], ruleIds: [], surface: SAFETY_SURFACE, evidenceHash: null },
101
+ { provider: refusal.provider || provider, surface: SAFETY_SURFACE },
102
+ )
103
+ error.direction = direction
104
+ error.protocol = refusal.protocol
105
+ error.safetyTokens = refusal.safetyTokens
106
+ if (refusal.imagesBlocked?.length) error.imagesBlocked = [...refusal.imagesBlocked]
107
+ throw error
108
+ }
109
+
110
+ function cloudSafetyEnabled(env = process.env) {
111
+ const raw = String(env[SAFETY_CLOUD_ENV] ?? '').trim().toLowerCase()
112
+ if (!raw) return true
113
+ return !['0', 'off', 'false', 'no', 'disabled'].includes(raw)
114
+ }
115
+
116
+ /** Explicit option > env default; DeepSeek-only (other providers stay portable). */
117
+ function resolveCloudSafety(safetyCheck, env = process.env) {
118
+ if (safetyCheck === false) return null
119
+ if (safetyCheck === true) return { level: 'high' }
120
+ if (safetyCheck && typeof safetyCheck === 'object') return safetyCheck
121
+ return cloudSafetyEnabled(env) ? { level: 'high' } : null
122
+ }
123
+
124
+ function parseJsonObject(text) {
125
+ try {
126
+ const value = JSON.parse(String(text ?? ''))
127
+ return value && typeof value === 'object' ? value : null
128
+ } catch {
129
+ return null
130
+ }
131
+ }
132
+
30
133
  export function resolveThinking({ task = 'agent', explicit, env = process.env } = {}) {
31
134
  const mode = String(env.ADVISERS_THINKING || 'auto').toLowerCase()
32
135
  const explicitEffort = normalizeEffort(explicit ?? env.ADVISERS_THINKING_EFFORT)
@@ -50,6 +153,13 @@ function normalizeUsage(usage) {
50
153
  reasoningTokens: reasoning,
51
154
  cachedTokens: Number(usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens ?? 0),
52
155
  totalTokens: Number(usage.total_tokens ?? 0),
156
+ safetyTokens: Number(
157
+ usage.completion_tokens_details?.safety_tokens
158
+ ?? usage.output_tokens_details?.safety_tokens
159
+ ?? usage.input_tokens_details?.safety_tokens
160
+ ?? usage.safety_tokens
161
+ ?? 0,
162
+ ) || 0,
53
163
  }
54
164
  }
55
165
 
@@ -78,14 +188,28 @@ export async function chatCompletion({
78
188
  thinking,
79
189
  effort,
80
190
  signal,
191
+ safetyKey,
192
+ safetyCheck,
81
193
  }) {
82
194
  if (!apiKey) throw new ModelError('missing API key', { code: 'MISSING_API_KEY' })
83
195
  const policy = thinking === false ? { enabled: false } : { enabled: true, ...resolveThinking({ task, explicit: effort }) }
84
196
  if (thinking === true && !policy.enabled) policy.enabled = true
85
197
  const provider = (process.env.ADVISERS_PROVIDER || 'deepseek').toLowerCase()
198
+
199
+ // Local pre-flight classification: a blocked request never reaches the network.
200
+ const requestSafety = inspectMessages(messages, { surface: SAFETY_SURFACE, hmacKey: safetyKey })
201
+ throwIfBlocked(requestSafety, provider, 'input')
202
+ const safetyWarnings = safetyWarningsOf(requestSafety, 'input')
203
+
86
204
  const body = { model, messages, max_tokens: maxTokens }
87
205
  if (tools?.length) body.tools = tools
88
206
  if (provider === 'deepseek') {
207
+ // Optional network-side second net (DeepSeek supports safety_check on the
208
+ // chat completions endpoint; default on for this provider only). Set
209
+ // ADVISERS_SAFETY_CLOUD=0 to disable. Live compatibility is tracked as a
210
+ // documented TODO — the parameter is only added for the DeepSeek provider.
211
+ const cloudSafety = resolveCloudSafety(safetyCheck)
212
+ if (cloudSafety) body.safety_check = cloudSafety
89
213
  if (policy.enabled) {
90
214
  body.thinking = { type: 'enabled' }
91
215
  body.reasoning_effort = normalizeEffort(policy.effort) || 'high'
@@ -113,6 +237,16 @@ export async function chatCompletion({
113
237
  })
114
238
  if (!response.ok) {
115
239
  const text = await response.text().catch(() => '')
240
+ // Upstream content-risk refusals become typed ContentSafetyErrors (the
241
+ // upstream body is never copied into the error). Other HTTP errors keep
242
+ // their existing ModelError shape and retry policy.
243
+ if (provider === 'deepseek') {
244
+ throwIfProviderRefused(parseJsonObject(text) ?? { error: { message: text } }, {
245
+ provider,
246
+ status: response.status,
247
+ direction: 'input',
248
+ })
249
+ }
116
250
  const retryable = RETRY_STATUS.has(response.status)
117
251
  const error = new ModelError(`model HTTP ${response.status}`, { status: response.status, code: response.status === 401 || response.status === 403 ? 'AUTH' : response.status === 400 ? 'INVALID_REQUEST' : 'UPSTREAM', retryable })
118
252
  error.body = text
@@ -120,20 +254,35 @@ export async function chatCompletion({
120
254
  lastError = error
121
255
  } else {
122
256
  const data = await response.json()
257
+ // Documented rejection shapes (finish_reason=content_filter,
258
+ // stop_reason=refusal, message.refusal, image blocks) fail closed.
259
+ throwIfProviderRefused(data, { provider, status: response.status, direction: 'output' })
123
260
  const choice = data?.choices?.[0]
124
261
  const message = choice?.message
125
262
  if (!message) throw new ModelError('model returned no message', { code: 'EMPTY_RESPONSE' })
263
+ const content = typeof message.content === 'string' ? message.content : ''
264
+ const toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls : []
265
+ // Post-flight classification of the assistant message (text + tool args).
266
+ const outputSafety = inspectMessages([{ role: 'assistant', content, ...(toolCalls.length ? { tool_calls: toolCalls } : {}) }], {
267
+ surface: SAFETY_SURFACE,
268
+ hmacKey: safetyKey,
269
+ })
270
+ throwIfBlocked(outputSafety, provider, 'output')
271
+ safetyWarnings.push(...safetyWarningsOf(outputSafety, 'output'))
126
272
  return {
127
- content: typeof message.content === 'string' ? message.content : '',
273
+ content,
128
274
  reasoningContent: typeof message.reasoning_content === 'string' ? message.reasoning_content : '',
129
- toolCalls: Array.isArray(message.tool_calls) ? message.tool_calls : [],
275
+ toolCalls,
130
276
  finishReason: choice?.finish_reason,
131
277
  usage: normalizeUsage(data.usage),
132
278
  thinking: policy,
133
279
  model,
280
+ ...(safetyWarnings.length ? { safetyWarnings } : {}),
134
281
  }
135
282
  }
136
283
  } catch (error) {
284
+ // A content-safety block is terminal: never retried, never forwarded.
285
+ if (error?.name === 'ContentSafetyError') throw error
137
286
  lastError = error
138
287
  if (signal?.aborted) throw new ModelError('cancelled by user', { code: 'CANCELLED_BY_USER' })
139
288
  if (error.name === 'AbortError') throw new ModelError(`model timeout after ${timeoutMs}ms`, { code: 'TIMEOUT', retryable: true })
package/lib/notify.js CHANGED
@@ -1,12 +1,15 @@
1
1
  /**
2
2
  * E1-T3: best-effort local notification adapter.
3
3
  *
4
- * No cloud push. The caller decides the body; Advisers only sends a short
5
- * count-style body (not client names/quotes). If no channel is available the
6
- * caller keeps the local reminder log; this module reports `sent:false`.
4
+ * No implicit cloud push. The caller decides the body; Advisers only sends a
5
+ * short count-style body (not client names/quotes). If no local channel is
6
+ * available the caller keeps the local reminder log; this module reports
7
+ * `sent:false`. The only outbound channel is the explicit, off-by-default
8
+ * `ADVISERS_NOTIFY_WEBHOOK` adapter below, which sends counts/levels/dates only.
7
9
  */
8
10
  import { existsSync } from 'node:fs'
9
11
  import { spawn } from 'node:child_process'
12
+ import { localDay } from './remind.js'
10
13
 
11
14
  function run(cmd, args, timeoutMs = 5000) {
12
15
  return new Promise((resolve, reject) => {
@@ -31,6 +34,129 @@ function powershellToastScript(title, body) {
31
34
  ].join('; ')
32
35
  }
33
36
 
37
+
38
+ /** Env var that opts a machine into the outbound JSON webhook (off by default). */
39
+ export const WEBHOOK_ENV = 'ADVISERS_NOTIFY_WEBHOOK'
40
+ /** Versioned payload schema; consumers can reject unknown versions. */
41
+ export const WEBHOOK_SCHEMA = 'advisers.notify.webhook.v1'
42
+ const DEFAULT_WEBHOOK_TIMEOUT_MS = 5000
43
+ const MAX_WEBHOOK_DATES = 31
44
+
45
+ export function isWebhookConfigured(env = process.env) {
46
+ return String(env?.[WEBHOOK_ENV] ?? '').trim() !== ''
47
+ }
48
+
49
+ /**
50
+ * Reduce due reminders to the only data allowed to leave the machine: a count,
51
+ * per-level counts and the affected local dates. Titles, creditors, actions,
52
+ * evidence and quotes are never read.
53
+ */
54
+ export function summarizeReminders(reminders) {
55
+ if (!Array.isArray(reminders)) throw new TypeError('summarizeReminders requires an array of reminders')
56
+ const levels = { L1: 0, L2: 0, L3: 0 }
57
+ const dates = new Set()
58
+ let count = 0
59
+ for (const reminder of reminders) {
60
+ if (!reminder || typeof reminder !== 'object') continue
61
+ count += 1
62
+ if (reminder.level === 'L1' || reminder.level === 'L2' || reminder.level === 'L3') levels[reminder.level] += 1
63
+ const day = localDay(reminder.dueAt)
64
+ if (day) dates.add(day)
65
+ }
66
+ return {
67
+ schema: WEBHOOK_SCHEMA,
68
+ count,
69
+ levels,
70
+ dates: [...dates].sort().slice(0, MAX_WEBHOOK_DATES),
71
+ }
72
+ }
73
+
74
+ function resolveWebhookTarget(options) {
75
+ const raw = options.url === undefined ? process.env[WEBHOOK_ENV] : options.url
76
+ if (raw == null || String(raw).trim() === '') return { configured: false }
77
+ try {
78
+ const url = new URL(String(raw).trim())
79
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return { configured: true, error: 'unsupported-protocol' }
80
+ return { configured: true, url }
81
+ } catch {
82
+ return { configured: true, error: 'invalid-url' }
83
+ }
84
+ }
85
+
86
+ function truncateDetail(value, limit = 200) {
87
+ const text = typeof value === 'string' ? value : String(value ?? '')
88
+ return text.length > limit ? text.slice(0, limit) : text
89
+ }
90
+
91
+ /**
92
+ * Opt-in outbound webhook: POST the sanitized summary as JSON.
93
+ *
94
+ * Disabled unless `ADVISERS_NOTIFY_WEBHOOK` (or an explicit `url`) is set. The
95
+ * function never throws for network/config failures; it returns a structured
96
+ * result so the caller can fall back to the local log:
97
+ *
98
+ * { sent: true, channel: 'webhook', configured: true, status, payload }
99
+ * { sent: false, channel: 'webhook', configured: false, reason: 'not-configured' }
100
+ * { sent: false, channel: 'webhook', configured: true, error: 'network'|'timeout'|'http'|'invalid-url'|'unsupported-protocol', status?, detail? }
101
+ */
102
+ export async function sendWebhookNotification(reminders, options = {}) {
103
+ const opts = options ?? {}
104
+ const summary = summarizeReminders(reminders)
105
+ const target = resolveWebhookTarget(opts)
106
+ if (!target.configured) {
107
+ return { sent: false, channel: 'webhook', configured: false, reason: 'not-configured' }
108
+ }
109
+ if (target.error) {
110
+ return { sent: false, channel: 'webhook', configured: true, error: target.error }
111
+ }
112
+ const fetchImpl = opts.fetch ?? globalThis.fetch
113
+ if (typeof fetchImpl !== 'function') {
114
+ return { sent: false, channel: 'webhook', configured: true, error: 'fetch-unavailable' }
115
+ }
116
+ const timeoutMs = Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_WEBHOOK_TIMEOUT_MS
117
+ const signal = typeof AbortSignal?.timeout === 'function' ? AbortSignal.timeout(timeoutMs) : undefined
118
+ try {
119
+ const response = await fetchImpl(target.url.href, {
120
+ method: 'POST',
121
+ headers: { 'content-type': 'application/json', 'user-agent': 'advisers-webhook/1' },
122
+ body: JSON.stringify(summary),
123
+ signal,
124
+ })
125
+ if (!response || typeof response !== 'object') {
126
+ return { sent: false, channel: 'webhook', configured: true, error: 'network', detail: 'empty response' }
127
+ }
128
+ if (!response.ok) {
129
+ let detail
130
+ try {
131
+ detail = truncateDetail(await response.text())
132
+ } catch {
133
+ detail = undefined
134
+ }
135
+ return {
136
+ sent: false,
137
+ channel: 'webhook',
138
+ configured: true,
139
+ error: 'http',
140
+ status: response.status,
141
+ ...(detail ? { detail } : {}),
142
+ }
143
+ }
144
+ return { sent: true, channel: 'webhook', configured: true, status: response.status, payload: summary }
145
+ } catch (error) {
146
+ const name = String(error?.name ?? '')
147
+ if (name === 'TimeoutError' || name === 'AbortError') {
148
+ return { sent: false, channel: 'webhook', configured: true, error: 'timeout', detail: `no response within ${timeoutMs}ms` }
149
+ }
150
+ return {
151
+ sent: false,
152
+ channel: 'webhook',
153
+ configured: true,
154
+ error: 'network',
155
+ detail: truncateDetail(error?.message ?? error),
156
+ }
157
+ }
158
+ }
159
+
34
160
  export async function sendNotification({ title = 'Advisers', body = '', cmd = process.env.ADVISERS_NOTIFY_CMD } = {}) {
35
161
  if (cmd) {
36
162
  await run(cmd, [title, body])
package/lib/pdf.js CHANGED
@@ -26,14 +26,52 @@ export function findCjkFont() {
26
26
  return null
27
27
  }
28
28
 
29
- function wrap(text, font, size, maxWidth) {
29
+ /**
30
+ * P1-5: per-font/per-size width cache.
31
+ *
32
+ * The old wrap() measured every candidate prefix with
33
+ * font.widthOfTextAtSize(current + ch) — that re-shapes the whole line for
34
+ * every character, so one paragraph cost O(chars²) shaping work (1000 lines
35
+ * took ~900ms end to end). The CJK fonts Advisers supports have additive
36
+ * advance widths (no pair kerning), so measuring each character once and
37
+ * summing the advances yields the identical line breaks in O(chars).
38
+ */
39
+ const WIDTH_CACHES = new WeakMap()
40
+
41
+ function widthOfChar(font, size, ch) {
42
+ let cache = WIDTH_CACHES.get(font)
43
+ if (!cache) { cache = new Map(); WIDTH_CACHES.set(font, cache) }
44
+ const key = size + '\u0000' + ch
45
+ let width = cache.get(key)
46
+ if (width === undefined) {
47
+ width = font.widthOfTextAtSize(ch, size)
48
+ cache.set(key, width)
49
+ }
50
+ return width
51
+ }
52
+
53
+ /**
54
+ * Break one paragraph into lines at maxWidth.
55
+ *
56
+ * Exported so test/perf-regression.test.js can compare it against the original
57
+ * prefix-measuring algorithm (equivalence is asserted on an additive reference
58
+ * font, which is the class of fonts this builder supports).
59
+ */
60
+ export function wrapToWidth(text, font, size, maxWidth) {
30
61
  const lines = []
31
62
  let current = ''
63
+ let currentWidth = 0
32
64
  for (const ch of String(text)) {
33
- if (ch === '\n') { lines.push(current); current = ''; continue }
34
- const next = current + ch
35
- if (font.widthOfTextAtSize(next, size) > maxWidth && current) { lines.push(current); current = ch }
36
- else current = next
65
+ if (ch === '\n') { lines.push(current); current = ''; currentWidth = 0; continue }
66
+ const charWidth = widthOfChar(font, size, ch)
67
+ if (current && currentWidth + charWidth > maxWidth) {
68
+ lines.push(current)
69
+ current = ch
70
+ currentWidth = charWidth
71
+ } else {
72
+ current += ch
73
+ currentWidth += charWidth
74
+ }
37
75
  }
38
76
  if (current) lines.push(current)
39
77
  return lines
@@ -51,7 +89,7 @@ export async function buildSimplePdf({ title = 'Advisers', paragraphs = [], font
51
89
  const { width, height } = page.getSize()
52
90
  let y = height - margin
53
91
  const add = (text, fontSize = size) => {
54
- for (const line of wrap(text, font, fontSize, width - margin * 2)) {
92
+ for (const line of wrapToWidth(text, font, fontSize, width - margin * 2)) {
55
93
  if (y < margin + fontSize * 2) { page = doc.addPage([595, 842]); y = height - margin }
56
94
  page.drawText(line, { x: margin, y, size: fontSize, font })
57
95
  y -= fontSize * 1.55
package/lib/pet-brief.js CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Pet Brief producer — read-only, redacted, expiring projection from the
3
- * Advisers ledger to Famling / Pearl (contract v0.1, docs/PET-BRIEF.md).
3
+ * Advisers ledger to desktop-pet consumers (contract v0.2, docs/PET-BRIEF-PRODUCER.md).
4
4
  *
5
5
  * Pure functions: no network, no model call, no ledger writes. The caller
6
6
  * supplies the ledger (loaded read-only by the CLI) and an injectable `now`.
@@ -10,13 +10,24 @@
10
10
  * - facts below 0.7 confidence are dropped before output;
11
11
  * - person/client names are masked to `某客户` by default and never echoed back;
12
12
  * - no reasoning, prompts, secrets, document bodies, or emotional fields;
13
- * - every suggested line is built from a field that is present in the brief.
13
+ * - every suggested line is built from a field that is present in the brief;
14
+ * - `displayPolicy` states who may see the brief (public/private/none); it
15
+ * defaults to `private` and is never `public` unless explicitly requested.
14
16
  */
15
17
  import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from 'node:fs'
16
18
  import { basename, dirname, join } from 'node:path'
17
19
  import { localDay } from './remind.js'
18
-
19
- export const PET_BRIEF_SCHEMA_VERSION = 1
20
+ import { classify } from './safety/index.js'
21
+
22
+ export const PET_BRIEF_SCHEMA_VERSION = 2
23
+ /** v0.1 briefs (contract before `displayPolicy`) are still accepted with warnings. */
24
+ export const PET_BRIEF_LEGACY_SCHEMA_VERSION = 1
25
+ /** Schema versions `validatePetBrief` can read (v0.1 = legacy, warnings only). */
26
+ export const PET_BRIEF_SCHEMA_VERSIONS = [PET_BRIEF_LEGACY_SCHEMA_VERSION, PET_BRIEF_SCHEMA_VERSION]
27
+ /** Contract v0.2 display policy: who may see brief-derived content. */
28
+ export const PET_BRIEF_DISPLAY_POLICIES = ['public', 'private', 'none']
29
+ /** Safe default: never `public` unless the user explicitly opts in. */
30
+ export const PET_BRIEF_DEFAULT_DISPLAY_POLICY = 'private'
20
31
  export const PET_BRIEF_SOURCE = 'advisers'
21
32
  export const PET_BRIEF_TTL_MS = 5 * 60_000
22
33
  export const PET_BRIEF_MAX_ITEMS = 10
@@ -25,6 +36,16 @@ export const PET_BRIEF_MAX_SUGGESTED_LINES = 3
25
36
  export const PET_BRIEF_MAX_LINE_LENGTH = 40
26
37
  export const PET_BRIEF_MOODS = ['calm', 'focused', 'concerned', 'pleased']
27
38
 
39
+ // Content-safety wiring (docs/CONTENT-SAFETY.md section 8): suggested lines and
40
+ // risk summaries are classified with the pet-brief surface. A block-level line
41
+ // is dropped entirely (fail-closed, no schema change: counts are derived from
42
+ // the arrays) and only a generic note is added to redactions - never the text.
43
+ const PET_BRIEF_SURFACE = 'pet-brief'
44
+
45
+ function isBlockedLine(text, hmacKey) {
46
+ return classify(text, { surface: PET_BRIEF_SURFACE, hmacKey }).action === 'block'
47
+ }
48
+
28
49
  /** Contract §2.2. Matched case-insensitively with `_`/`-`/spaces removed. */
29
50
  export const PET_BRIEF_FORBIDDEN_KEYS = [
30
51
  'reasoning', 'cot', 'chainofthought', 'rawprompt', 'systemprompt',
@@ -33,7 +54,7 @@ export const PET_BRIEF_FORBIDDEN_KEYS = [
33
54
  ]
34
55
 
35
56
  const ROOT_KEYS = [
36
- 'schemaVersion', 'generatedAt', 'expiresAt', 'source', 'counts',
57
+ 'schemaVersion', 'generatedAt', 'expiresAt', 'source', 'displayPolicy', 'counts',
37
58
  'today', 'commitments', 'risks', 'facts', 'mood', 'suggestedLines', 'redactions',
38
59
  ]
39
60
  const ITEM_KEYS = {
@@ -145,7 +166,8 @@ const RISK_RANK = { low: 1, medium: 2, high: 3 }
145
166
  * @param {number} [options.ttlMs]
146
167
  * @param {number} [options.maxItems]
147
168
  * @param {number} [options.minConfidence]
148
- * @returns {object} contract v0.1 brief (no writes, no network).
169
+ * @param {'public'|'private'|'none'} [options.displayPolicy='private'] who may see the brief
170
+ * @returns {object} contract v0.2 brief (no writes, no network).
149
171
  */
150
172
  export function buildPetBrief(ledger, options = {}) {
151
173
  if (!ledger || typeof ledger.listCommitments !== 'function') throw new TypeError('buildPetBrief requires a ledger')
@@ -153,6 +175,12 @@ export function buildPetBrief(ledger, options = {}) {
153
175
  const ttlMs = Number.isFinite(options.ttlMs) ? options.ttlMs : PET_BRIEF_TTL_MS
154
176
  const maxItems = Number.isFinite(options.maxItems) ? options.maxItems : PET_BRIEF_MAX_ITEMS
155
177
  const minConfidence = Number.isFinite(options.minConfidence) ? options.minConfidence : PET_BRIEF_MIN_CONFIDENCE
178
+ const displayPolicy = options.displayPolicy ?? PET_BRIEF_DEFAULT_DISPLAY_POLICY
179
+ const hmacKey = options.hmacKey
180
+ const dropped = { risks: 0, lines: 0 }
181
+ if (!PET_BRIEF_DISPLAY_POLICIES.includes(displayPolicy)) {
182
+ throw new TypeError(`displayPolicy must be one of ${PET_BRIEF_DISPLAY_POLICIES.join('|')}`)
183
+ }
156
184
  const limit = Math.max(1, Math.min(PET_BRIEF_MAX_ITEMS, Math.trunc(maxItems)))
157
185
  const today = localDay(new Date(nowMs).toISOString())
158
186
 
@@ -271,6 +299,11 @@ export function buildPetBrief(ledger, options = {}) {
271
299
  }
272
300
  const riskItems = risks
273
301
  .filter((risk) => risk.confidence >= minConfidence)
302
+ .filter((risk) => {
303
+ if (!isBlockedLine(risk.summary, hmacKey)) return true
304
+ dropped.risks += 1
305
+ return false
306
+ })
274
307
  .sort((a, b) => RISK_RANK[b.level] - RISK_RANK[a.level] || b.confidence - a.confidence || cmp(a.id, b.id))
275
308
  .slice(0, limit)
276
309
 
@@ -300,7 +333,12 @@ export function buildPetBrief(ledger, options = {}) {
300
333
  const lines = []
301
334
  const pushLine = (line) => {
302
335
  const text = clip(oneLine(line), PET_BRIEF_MAX_LINE_LENGTH)
303
- if (text && !lines.includes(text) && lines.length < PET_BRIEF_MAX_SUGGESTED_LINES) lines.push(text)
336
+ if (!text || lines.includes(text) || lines.length >= PET_BRIEF_MAX_SUGGESTED_LINES) return
337
+ if (isBlockedLine(text, hmacKey)) {
338
+ dropped.lines += 1
339
+ return
340
+ }
341
+ lines.push(text)
304
342
  }
305
343
  const topRisk = riskItems[0]
306
344
  if (topRisk) pushLine(`${topRisk.summary}。`)
@@ -319,6 +357,8 @@ export function buildPetBrief(ledger, options = {}) {
319
357
  redactions.push('不含模型推理、系统提示或原始提示词')
320
358
  const excludedSecrecy = allMatters.filter((matter) => matterSecrecy(matter) >= 2).length
321
359
  if (excludedSecrecy > 0) redactions.push(clip(`已排除保密等级≥2 的事项(${excludedSecrecy} 个)`, 80))
360
+ const droppedTotal = dropped.risks + dropped.lines
361
+ if (droppedTotal > 0) redactions.push(clip(`已丢弃 ${droppedTotal} 条不安全内容(不展示原文)`, 80))
322
362
  if (!redactions.some((note) => note.startsWith('联系人')) && !redactions.some((note) => note.includes('客户名'))) {
323
363
  redactions.push('联系人/客户名默认不进入 brief')
324
364
  }
@@ -330,6 +370,7 @@ export function buildPetBrief(ledger, options = {}) {
330
370
  generatedAt,
331
371
  expiresAt,
332
372
  source: PET_BRIEF_SOURCE,
373
+ displayPolicy,
333
374
  counts: {
334
375
  today: todayItems.length,
335
376
  commitments: commitmentItems.length,
@@ -376,7 +417,7 @@ function checkForbiddenKeys(value, path, errors) {
376
417
  function checkUnknownKeys(value, allowed, path, errors) {
377
418
  if (!isPlainObject(value)) return
378
419
  for (const key of Object.keys(value)) {
379
- if (!allowed.includes(key)) errors.push(issue('E_UNKNOWN_FIELD', `${path}.${key}`, `field is not in contract v0.1: ${key}`))
420
+ if (!allowed.includes(key)) errors.push(issue('E_UNKNOWN_FIELD', `${path}.${key}`, `field is not in contract v0.2: ${key}`))
380
421
  }
381
422
  }
382
423
 
@@ -402,34 +443,56 @@ function checkConfidence(value, path, errors) {
402
443
  }
403
444
 
404
445
  /**
405
- * Validate a brief against contract v0.1 (schema + freshness + forbidden data).
446
+ * Validate a brief against contract v0.2 (schema + freshness + forbidden data).
406
447
  * Used by `advisers pet-brief --check` and by tests; the consumer re-validates.
407
448
  *
449
+ * Backward compatibility: contract v0.1 briefs (`schemaVersion: 1`, no
450
+ * `displayPolicy`) are accepted by default with a `W_LEGACY_SCHEMA_VERSION`
451
+ * warning and a `W_MISSING_DISPLAY_POLICY` warning; missing `displayPolicy`
452
+ * always means the safe default `private` and never fails the check unless the
453
+ * caller opts into `requireDisplayPolicy`. Unknown versions still fail closed.
454
+ *
408
455
  * @param {unknown|string} value parsed brief, or raw JSON text
409
456
  * @param {object} [options]
410
457
  * @param {number|string|Date} [options.now]
411
458
  * @param {boolean} [options.allowExpired] skip the freshness gate (schema check only)
412
- * @returns {{ok: boolean, errors: Array<{code: string, path: string, message: string}>, brief?: object}}
459
+ * @param {boolean} [options.acceptLegacy=true] accept v0.1 briefs with warnings; false fails closed
460
+ * @param {boolean} [options.requireDisplayPolicy=false] make a missing displayPolicy an error
461
+ * @returns {{ok: boolean, errors: Array<{code: string, path: string, message: string}>, warnings: Array<{code: string, path: string, message: string}>, brief?: object}}
413
462
  */
414
463
  export function validatePetBrief(value, options = {}) {
415
464
  const errors = []
465
+ const warnings = []
416
466
  let brief = value
417
467
  if (typeof value === 'string') {
418
468
  try {
419
469
  brief = JSON.parse(value)
420
470
  } catch (error) {
421
- return { ok: false, errors: [issue('E_MALFORMED_JSON', '$', `invalid JSON: ${error.message}`)], brief: undefined }
471
+ return { ok: false, errors: [issue('E_MALFORMED_JSON', '$', `invalid JSON: ${error.message}`)], warnings: [], brief: undefined }
422
472
  }
423
473
  }
424
474
  if (!isPlainObject(brief)) {
425
- return { ok: false, errors: [issue('E_TYPE', '$', 'brief must be a JSON object')], brief: undefined }
475
+ return { ok: false, errors: [issue('E_TYPE', '$', 'brief must be a JSON object')], warnings: [], brief: undefined }
426
476
  }
427
477
 
428
478
  checkForbiddenKeys(brief, '$', errors)
429
479
  checkUnknownKeys(brief, ROOT_KEYS, '$', errors)
430
480
 
431
- if (brief.schemaVersion !== PET_BRIEF_SCHEMA_VERSION) {
432
- errors.push(issue('E_SCHEMA_VERSION', '$.schemaVersion', `unsupported schemaVersion (expected ${PET_BRIEF_SCHEMA_VERSION})`))
481
+ if (brief.schemaVersion === PET_BRIEF_LEGACY_SCHEMA_VERSION) {
482
+ if (options.acceptLegacy === false) {
483
+ errors.push(issue('E_SCHEMA_VERSION', '$.schemaVersion', 'schemaVersion 1 is legacy (contract v0.1) and acceptance is disabled'))
484
+ } else {
485
+ warnings.push(issue('W_LEGACY_SCHEMA_VERSION', '$.schemaVersion', 'brief uses legacy schemaVersion 1 (contract v0.1); accepted, missing displayPolicy means "private"'))
486
+ }
487
+ } else if (brief.schemaVersion !== PET_BRIEF_SCHEMA_VERSION) {
488
+ errors.push(issue('E_SCHEMA_VERSION', '$.schemaVersion', `unsupported schemaVersion (expected 2, legacy 1 allowed with warnings)`))
489
+ }
490
+ if (brief.displayPolicy === undefined) {
491
+ const message = 'displayPolicy is missing; consumers must treat it as "private" (legacy v0.1 brief)'
492
+ if (options.requireDisplayPolicy === true) errors.push(issue('E_DISPLAY_POLICY', '$.displayPolicy', message))
493
+ else warnings.push(issue('W_MISSING_DISPLAY_POLICY', '$.displayPolicy', message))
494
+ } else if (!PET_BRIEF_DISPLAY_POLICIES.includes(brief.displayPolicy)) {
495
+ errors.push(issue('E_ENUM', '$.displayPolicy', 'displayPolicy must be public|private|none'))
433
496
  }
434
497
  if (brief.source !== PET_BRIEF_SOURCE) errors.push(issue('E_SOURCE', '$.source', 'source must be "advisers"'))
435
498
 
@@ -531,7 +594,7 @@ export function validatePetBrief(value, options = {}) {
531
594
  })
532
595
  }
533
596
 
534
- return { ok: errors.length === 0, errors, brief }
597
+ return { ok: errors.length === 0, errors, warnings, brief }
535
598
  }
536
599
 
537
600
  function parseIsoWithZone(value, path, errors) {