advisers 0.3.1 → 0.4.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.
Files changed (48) hide show
  1. package/README-zh.md +13 -15
  2. package/README.md +32 -22
  3. package/THIRD-PARTY-NOTICES.md +1 -1
  4. package/bin/advisers.js +2769 -183
  5. package/index.js +1 -1
  6. package/lib/brief-archive.js +267 -0
  7. package/lib/client-pack.js +1016 -0
  8. package/lib/consent.js +390 -0
  9. package/lib/credentials.js +195 -0
  10. package/lib/customer-read.js +524 -0
  11. package/lib/error-codes.js +516 -7
  12. package/lib/evidence.js +928 -120
  13. package/lib/kb-extract.js +626 -0
  14. package/lib/kb-facts.js +429 -0
  15. package/lib/kb-pages.js +1084 -0
  16. package/lib/kb.js +1036 -0
  17. package/lib/ledger-read.js +109 -1
  18. package/lib/mail-errors.js +46 -0
  19. package/lib/mail-extract.js +351 -0
  20. package/lib/mail-imap.js +446 -0
  21. package/lib/mail-import.js +176 -0
  22. package/lib/mail-parse.js +223 -0
  23. package/lib/mail-store.js +731 -0
  24. package/lib/mail.js +506 -0
  25. package/lib/mcp-server.js +397 -11
  26. package/lib/notify.js +265 -7
  27. package/lib/policy/decision.js +315 -0
  28. package/lib/policy/egress.js +268 -0
  29. package/lib/policy/errors.js +71 -0
  30. package/lib/policy/index.js +99 -0
  31. package/lib/policy/rules.js +468 -0
  32. package/lib/policy/surfaces.js +141 -0
  33. package/lib/receipt-verify.js +283 -26
  34. package/lib/receivables.js +1653 -0
  35. package/lib/scheduler.js +453 -9
  36. package/lib/shell.js +1406 -0
  37. package/lib/source.js +98 -3
  38. package/lib/sqlite.js +501 -49
  39. package/lib/tos/index.js +2 -2
  40. package/lib/tos/manifest.json +6 -6
  41. package/lib/tos/privacy.zh-CN.md +33 -20
  42. package/lib/tos/safety.zh-CN.md +7 -6
  43. package/lib/tos/summary.zh-CN.md +3 -2
  44. package/lib/tos/terms.zh-CN.md +31 -16
  45. package/lib/tui/labels.js +1 -1
  46. package/lib/tui/render.js +1 -1
  47. package/lib/urgency.js +467 -0
  48. package/package.json +4 -4
@@ -23,7 +23,11 @@
23
23
  // unseal / sync pull inode replacement and a concurrent writer are safe;
24
24
  // - per-item clearance (default 0, fail closed): rows whose matter.secrecy
25
25
  // is above the clearance are excluded and only counted, never partially
26
- // returned.
26
+ // returned;
27
+ // - customer reads (0.3.2 M3): the client list/status projection is derived by
28
+ // lib/customer-read.js inside one read snapshot; customer entities are
29
+ // SQLite-only, so a JSON backend reports customerEntities:false and an
30
+ // empty list instead of inventing rows.
27
31
  //
28
32
  // The API is a versioned contract (docs/LEDGER-READ-API.md): 0.x versions only
29
33
  // add fields/signatures; existing names, shapes and error codes stay stable.
@@ -32,6 +36,7 @@ import { existsSync, readFileSync } from 'node:fs'
32
36
  import { homedir } from 'node:os'
33
37
  import { isAbsolute, join } from 'node:path'
34
38
 
39
+ import { listClientRows, readClientStatus } from './customer-read.js'
35
40
  import { secrecyLevel } from './egress.js'
36
41
  import { evidenceRecordSecrecy } from './evidence.js'
37
42
 
@@ -285,6 +290,20 @@ function normalizeLimit(value) {
285
290
  return limit
286
291
  }
287
292
 
293
+ /**
294
+ * Validate one customer-page limit (clients or timeline rows). The read-only
295
+ * facade caps a customer page at 200 rows even when a caller asks for more, so
296
+ * a single read can never load an unbounded customer projection.
297
+ */
298
+ function normalizeCustomerLimit(value, fallback, label) {
299
+ if (value === undefined || value === null) return fallback
300
+ const limit = Number(value)
301
+ if (!Number.isInteger(limit) || limit < 1) {
302
+ throw new LedgerReadError('E_USAGE', label + ' must be a positive integer when supplied', 'Omit ' + label + ' to use the default; the read-only facade caps customer pages at 200 rows.')
303
+ }
304
+ return Math.min(limit, 200)
305
+ }
306
+
288
307
  function normalizeParts(parts) {
289
308
  if (parts === undefined || parts === null) return null
290
309
  if (!Array.isArray(parts)) throw new LedgerReadError('E_USAGE', 'parts must be an array of wire table names', `Accepted names: ${WIRE_TABLES.join(', ')}.`)
@@ -324,10 +343,15 @@ async function openLedgerHandle(home) {
324
343
  backend: 'json',
325
344
  schemaVersion: null,
326
345
  warnings: [],
346
+ // Customer entities are SQLite-only (schema v21): the legacy JSON ledger has
347
+ // no client/project/note tables. Report that honestly; never invent rows.
348
+ customerEntities: false,
327
349
  close() {},
328
350
  getEntity: (kind, id, clearance) => jsonEntity(ledger, kind, id, clearance),
329
351
  index: (options) => jsonCommitmentIndex(ledger, options),
330
352
  snapshot: (parts) => jsonSnapshot(ledger, parts),
353
+ clientList: () => ({ rows: [], total: 0, limit: null, clearance: 0, protectedExcluded: 0 }),
354
+ clientStatus: () => null,
331
355
  }
332
356
  }
333
357
  if (!existsSync(backend.dbPath)) throw notFoundInHome(backend)
@@ -345,6 +369,9 @@ async function openLedgerHandle(home) {
345
369
  backend: 'sqlite',
346
370
  schemaVersion: store.schemaVersion(),
347
371
  warnings,
372
+ // A read-only open asserts the current schema (v21), so the customer tables
373
+ // exist whenever this handle is returned.
374
+ customerEntities: true,
348
375
  close() { try { store.close() } catch {} },
349
376
  getEntity(kind, id, clearance) {
350
377
  const spec = ENTITY_KINDS[kind]
@@ -356,6 +383,12 @@ async function openLedgerHandle(home) {
356
383
  snapshot(parts) {
357
384
  return store.read(() => store.loadSnapshot(parts))
358
385
  },
386
+ clientList(options) {
387
+ return listClientRows(store, options)
388
+ },
389
+ clientStatus(id, options) {
390
+ return readClientStatus(store, id, options)
391
+ },
359
392
  }
360
393
  }
361
394
 
@@ -598,6 +631,79 @@ export async function readLedgerSnapshot({ home, parts = null } = {}) {
598
631
  }))
599
632
  }
600
633
 
634
+ /**
635
+ * Read-only customer list (0.3.2 M3). Customer entities are SQLite-only: on the
636
+ * legacy JSON backend the result is an empty list with `customerEntities:false`
637
+ * (never invented rows). The list is clearance-filtered per client (matters and
638
+ * client-level note counts above the clearance are counted in
639
+ * `protectedExcluded`, not shown). Note bodies are never returned.
640
+ *
641
+ * @param {{ home?: string, clearance?: number, limit?: number, all?: boolean }} [options]
642
+ * @returns {Promise<{clients:Array<object>, total:number, truncated:boolean,
643
+ * limit:number, clearance:number, protectedExcluded:number,
644
+ * customerEntities:boolean, schemaVersion:number|null, backend:'sqlite'|'json',
645
+ * readAt:string, warnings:string[]}>}
646
+ */
647
+ export async function readClientList({ home, clearance = 0, limit = 20, all = false } = {}) {
648
+ const root = resolveAdvisersHome({ home })
649
+ const level = normalizeClearance(clearance)
650
+ const pageLimit = normalizeCustomerLimit(limit, 20, 'limit')
651
+ return withLedger(root, (handle) => {
652
+ const result = handle.customerEntities === true
653
+ ? handle.clientList({ clearance: level, limit: pageLimit, includeArchived: all === true })
654
+ : { rows: [], total: 0, protectedExcluded: 0 }
655
+ return {
656
+ clients: result.rows,
657
+ total: result.total,
658
+ truncated: result.total > result.rows.length,
659
+ limit: pageLimit,
660
+ clearance: level,
661
+ protectedExcluded: result.protectedExcluded,
662
+ customerEntities: handle.customerEntities === true,
663
+ schemaVersion: handle.schemaVersion,
664
+ backend: handle.backend,
665
+ readAt: new Date().toISOString(),
666
+ warnings: handle.warnings.slice(),
667
+ }
668
+ })
669
+ }
670
+
671
+ /**
672
+ * Read-only customer status by id (0.3.2 M3): client identity, project
673
+ * summaries, exact counts, open mine/waiting items and a derived
674
+ * delivery/commitment timeline. `found:false` (with `view:null`) distinguishes
675
+ * an unknown/archived-by-id client from a gate failure, without throwing.
676
+ *
677
+ * @param {{ home?: string, id: string, clearance?: number, timelineLimit?: number }} [options]
678
+ * @returns {Promise<{found:boolean, view:object|null, clearance:number,
679
+ * customerEntities:boolean, schemaVersion:number|null, backend:'sqlite'|'json',
680
+ * readAt:string, warnings:string[]}>}
681
+ */
682
+ export async function readClientById({ home, id, clearance = 0, timelineLimit = 20 } = {}) {
683
+ const root = resolveAdvisersHome({ home })
684
+ if (typeof id !== 'string' || id.trim() === '') {
685
+ throw new LedgerReadError('E_USAGE', 'id must be a non-empty string', 'Pass the client id (cl_…); list ids with readClientList.')
686
+ }
687
+ const key = id.trim()
688
+ const level = normalizeClearance(clearance)
689
+ const timelinePage = normalizeCustomerLimit(timelineLimit, 20, 'timelineLimit')
690
+ return withLedger(root, (handle) => {
691
+ const view = handle.customerEntities === true
692
+ ? handle.clientStatus(key, { clearance: level, timelineLimit: timelinePage, openLimit: 20 })
693
+ : null
694
+ return {
695
+ found: view !== null && view !== undefined,
696
+ view: view ?? null,
697
+ clearance: level,
698
+ customerEntities: handle.customerEntities === true,
699
+ schemaVersion: handle.schemaVersion,
700
+ backend: handle.backend,
701
+ readAt: new Date().toISOString(),
702
+ warnings: handle.warnings.slice(),
703
+ }
704
+ })
705
+ }
706
+
601
707
  export default Object.freeze({
602
708
  LedgerReadError,
603
709
  resolveAdvisersHome,
@@ -605,4 +711,6 @@ export default Object.freeze({
605
711
  readOpenCommitmentIndex,
606
712
  readEntityById,
607
713
  readLedgerSnapshot,
714
+ readClientList,
715
+ readClientById,
608
716
  })
@@ -0,0 +1,46 @@
1
+ /**
2
+ * 0.4.0 mail-entry error helpers.
3
+ *
4
+ * Every failure in lib/mail*.js and lib/credentials.js is an Error with a stable
5
+ * `code` (the mail/IMAP/credential codes below), an optional `hint`,
6
+ * and a message that never contains a password or email body text. The new
7
+ * codes are registered in lib/error-codes.js at integration time (see the 0.4
8
+ * implementation report).
9
+ *
10
+ * This module is pure (no I/O, no network, no console).
11
+ */
12
+
13
+ /** All mail/IMAP/credential codes this feature can raise. */
14
+ export const MAIL_ERROR_CODES = Object.freeze({
15
+ CONFIG: 'E_MAIL_CONFIG',
16
+ ACCOUNT_NOT_FOUND: 'E_MAIL_ACCOUNT_NOT_FOUND',
17
+ MESSAGE_NOT_FOUND: 'E_MAIL_MESSAGE_NOT_FOUND',
18
+ CREDENTIALS_MISSING: 'E_MAIL_CREDENTIALS_MISSING',
19
+ CREDENTIALS_INSECURE: 'E_CREDENTIALS_INSECURE',
20
+ IMAP_AUTH: 'E_IMAP_AUTH',
21
+ IMAP_TLS: 'E_IMAP_TLS',
22
+ IMAP_UIDVALIDITY: 'E_IMAP_UIDVALIDITY',
23
+ IMAP_PROTOCOL: 'E_IMAP_PROTOCOL',
24
+ IMAP_TIMEOUT: 'E_IMAP_TIMEOUT',
25
+ MAIL_TOO_LARGE: 'E_MAIL_TOO_LARGE',
26
+ NOT_RETAINED: 'E_MAIL_NOT_RETAINED',
27
+ MODEL_DISABLED: 'E_MAIL_MODEL_DISABLED',
28
+ // Reuses the existing ledger schema code: mail needs the v22 tables.
29
+ SCHEMA_STALE: 'E_SCHEMA_STALE',
30
+ })
31
+
32
+ const KNOWN = new Set(Object.values(MAIL_ERROR_CODES))
33
+
34
+ /** A business error with a stable code (message keeps the code for stderr). */
35
+ export function mailError(code, message, hint) {
36
+ if (!KNOWN.has(code)) throw new TypeError('unknown mail error code: ' + String(code))
37
+ const error = new Error(code + ': ' + message + (hint ? ' (hint: ' + hint + ')' : ''))
38
+ error.code = code
39
+ if (hint) error.hint = hint
40
+ return error
41
+ }
42
+
43
+ /** True when `error` is one of this feature's coded errors. */
44
+ export function isMailError(error) {
45
+ return Boolean(error && typeof error === 'object' && KNOWN.has(error.code))
46
+ }
@@ -0,0 +1,351 @@
1
+ /**
2
+ * Local-first commitment extraction for the 0.4.0 mail entry.
3
+ *
4
+ * DEFAULT PATH (`extractLocalCandidates`) is fully offline/deterministic:
5
+ * sentence split -> commitment trigger patterns (zh/en) -> verbatim quote
6
+ * -> due date via lib/relative-date.js (Asia/Shanghai) -> amount/currency
7
+ * -> client/project HINTS (never automatic binding) -> memory_candidates
8
+ * compatible payload (kind 'commitment').
9
+ *
10
+ * The model path (`extractCandidatesWithModel`) is OPT-IN and never called by
11
+ * mailSync or by the default `mailExtract` flow. It requires an explicit
12
+ * ADVISERS_API_KEY, wraps the body with lib/untrusted.js, clips it to 8 KiB,
13
+ * sends no attachment/header bytes and reuses the audited capture pipeline
14
+ * (safety classify + verbatim quote validation). Candidates stay pending;
15
+ * nothing is auto-accepted.
16
+ *
17
+ * Known limits (documented, not bugs): request/polite sentences are not
18
+ * promises; meeting reschedules are a known false-positive class; the rules
19
+ * are calibrated for typical Chinese/English business mail and every
20
+ * candidate is reviewed by a human before it reaches the ledger.
21
+ */
22
+ import { normalizeDue } from './relative-date.js'
23
+ import { mailError, MAIL_ERROR_CODES } from './mail-errors.js'
24
+
25
+ export const LOCAL_MAX_CANDIDATES = 5
26
+ export const MODEL_MAX_INPUT_CHARS = 8000
27
+ export const MAX_QUOTE_CHARS = 500
28
+ export const MAX_ACTION_CHARS = 40
29
+
30
+ const ACTION_VERBS = [
31
+ '发送', '发', '提交', '交付', '回复', '确认', '提供', '安排', '完成', '给出',
32
+ '上线', '付款', '打款', '支付', '签署', '签', '寄', '送', '对接', '处理',
33
+ '反馈', '准备', '整理', '跟进', '汇报', '报价', '回访', '续约',
34
+ ]
35
+ const EN_ACTION_VERBS = ['send', 'submit', 'deliver', 'reply', 'confirm', 'provide', 'finish', 'complete', 'pay', 'share', 'prepare', 'upload', 'review', 'fix', 'quote']
36
+ // A request is only a request when the sentence STARTS with one: a promise
37
+ // sentence may legitimately mention "please" later ("I will send it, please review").
38
+ const REQUEST_RE = /^(?:请|麻烦|烦请|劳驾|能否|可否|能不能|可以(?:帮我|帮忙)?|帮忙|劳烦)|^\s*(?:could|can|would|please)\b/i
39
+ const RESCHEDULE_RE = /(?:改期|改到|改在|推迟|延后|另行通知|时间改|推到|挪到|顺延)/
40
+ const TENTATIVE_RE = /(?:尽量|争取|应该|大概|可能|回头|到时候|看看|有空)/
41
+ const STRONG_RE = /(?:一定|保证|承诺|答应|务必|准时|肯定)/
42
+ const FIRST_PERSON_RE = /(?:我|我们|本人|咱们)/
43
+ const THIRD_PERSON_RE = /(?:他|她|他们|她们|对方|客户|乙方|供应商|厂家|甲方)/
44
+
45
+ function splitSentences(text) {
46
+ return String(text == null ? '' : text)
47
+ .replace(/\r\n/g, '\n').replace(/\r/g, '\n')
48
+ // Chinese/ASCII sentence punctuation plus an ASCII full stop followed by
49
+ // a capitalised new sentence (keeps 3.5 / U.S. intact).
50
+ .split(/[\n。!?!?;;]+|\.\s+(?=[A-Z])/u)
51
+ .map((sentence) => sentence.trim())
52
+ .filter(Boolean)
53
+ }
54
+
55
+ function compact(text) {
56
+ return String(text == null ? '' : text).replace(/\s+/g, '')
57
+ }
58
+
59
+ function capAction(value) {
60
+ const text = String(value == null ? '' : value).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim()
61
+ return text ? text.slice(0, MAX_ACTION_CHARS) : undefined
62
+ }
63
+
64
+ function actionOf(sentence) {
65
+ const carry = /(?:把|将)([^。!?!?\n,,::]{1,16}?)(发送|发|提交|交付|回复|确认|提供|安排|完成|给出|上线|付款|打款|支付|签署|寄|送|对接|处理|反馈|报价)/.exec(sentence)
66
+ if (carry) return capAction(carry[2] + carry[1])
67
+ let first = null
68
+ for (const verb of ACTION_VERBS) {
69
+ const index = sentence.indexOf(verb)
70
+ if (index === -1) continue
71
+ if (!first || index < first.index) first = { index, verb }
72
+ }
73
+ if (first) {
74
+ const after = sentence.slice(first.index + first.verb.length).replace(/^[\s,,::]*(?:给|到|至|你|您|他|她|他们|客户|对方)?/, '').slice(0, 12)
75
+ return capAction(first.verb + after)
76
+ }
77
+ const english = /\b(?:will|'ll|promise to|going to|shall)\s+([a-z]+(?:\s+[a-z]+){0,4})/i.exec(sentence)
78
+ if (english) {
79
+ const words = english[1].split(/\s+/).slice(0, 5).join(' ')
80
+ return capAction(words.replace(/\b(the|a|an)\b\s*/gi, ''))
81
+ }
82
+ for (const verb of EN_ACTION_VERBS) {
83
+ const match = new RegExp('\\b' + verb + '\\b([^.!?\\n]{0,30})', 'i').exec(sentence)
84
+ if (match) return capAction((verb + match[1]).replace(/\s+/g, ' ').trim().slice(0, MAX_ACTION_CHARS))
85
+ }
86
+ return undefined
87
+ }
88
+
89
+ function toMinor(numberText, unit) {
90
+ const clean = String(numberText).replace(/,/g, '')
91
+ const [integerPart, fractionRaw = ''] = clean.split('.')
92
+ if (!/^\d+$/.test(integerPart)) return null
93
+ const fraction = (fractionRaw + '00').slice(0, 2)
94
+ let minor = BigInt(integerPart) * 100n + BigInt(fraction)
95
+ if (unit === '万') minor *= 10000n
96
+ else if (unit === '千') minor *= 1000n
97
+ if (minor <= 0n || minor > 100_000_000_000_000n) return null
98
+ return Number(minor)
99
+ }
100
+
101
+ /** Extract one explicit money amount from text: { amountMinor, currency } or null. */
102
+ export function extractMailAmount(text) {
103
+ const source = String(text == null ? '' : text)
104
+ let match = /(?:¥|¥|RMB|CNY|人民币)\s*([0-9][0-9,]*(?:\.[0-9]{1,2})?)\s*(万|千)?/i.exec(source)
105
+ if (match) {
106
+ const minor = toMinor(match[1], match[2] === '万' ? '万' : match[2] === '千' ? '千' : null)
107
+ if (minor) return { amountMinor: minor, currency: 'CNY' }
108
+ }
109
+ match = /([0-9][0-9,]*(?:\.[0-9]{1,2})?)\s*(万元|万|千元|元|块(?:钱)?)/.exec(source)
110
+ if (match) {
111
+ const unit = match[2].startsWith('万') ? '万' : match[2].startsWith('千') ? '千' : null
112
+ const minor = toMinor(match[1], unit)
113
+ if (minor) return { amountMinor: minor, currency: 'CNY' }
114
+ }
115
+ match = /(?:USD|US\$|\$)\s*([0-9][0-9,]*(?:\.[0-9]{1,2})?)/i.exec(source)
116
+ if (match) {
117
+ const minor = toMinor(match[1], null)
118
+ if (minor) return { amountMinor: minor, currency: 'USD' }
119
+ }
120
+ match = /([0-9][0-9,]*(?:\.[0-9]{1,2})?)\s*(?:美元|美金)/.exec(source)
121
+ if (match) {
122
+ const minor = toMinor(match[1], null)
123
+ if (minor) return { amountMinor: minor, currency: 'USD' }
124
+ }
125
+ return null
126
+ }
127
+
128
+ function normalizeKey(value) {
129
+ return String(value == null ? '' : value)
130
+ .normalize('NFKC')
131
+ .replace(/[\u200B-\u200D\u2060\uFEFF]/g, '')
132
+ .toLowerCase()
133
+ .replace(/\s+/g, ' ')
134
+ .trim()
135
+ }
136
+
137
+ /** Parse a From header into display name / address / domain. */
138
+ export function parseFromAddress(from) {
139
+ const text = String(from == null ? '' : from).trim()
140
+ const bracketed = /<([^<>\s]+@[^<>\s]+)>/.exec(text)
141
+ const emailMatch = bracketed || /([^\s<>]+@[^\s<>]+)/.exec(text)
142
+ const email = emailMatch ? emailMatch[1].trim() : ''
143
+ let display = ''
144
+ if (bracketed) display = text.slice(0, bracketed.index).replace(/["']/g, '').trim()
145
+ else if (!email) display = text
146
+ const domain = email.includes('@') ? email.split('@').pop().toLowerCase().replace(/[>),;]+$/, '') : ''
147
+ const local = email.includes('@') ? email.split('@')[0].toLowerCase() : ''
148
+ return { display, email, domain, local }
149
+ }
150
+
151
+ /**
152
+ * Client/project HINTS from the From header, subject and body.
153
+ * NEVER writes a binding: docs/CLIENTS.md forbids automatic customer
154
+ * identification, so the candidate only carries a suggestion.
155
+ */
156
+ export function matchMailHints({ from = '', subject = '', text = '' } = {}, { clients = [], projects = [] } = {}) {
157
+ const parsed = parseFromAddress(from)
158
+ const haystack = compact(normalizeKey([parsed.display, subject, text].filter(Boolean).join(' ')))
159
+ const domain = parsed.domain.replace(/\s+/g, '')
160
+ let clientHint
161
+ // Pass 1: address domain / exact From display name (stronger than a substring
162
+ // in the body). Pass 2: name or alias mentioned in From/subject/body.
163
+ for (const client of Array.isArray(clients) ? clients : []) {
164
+ if (!client || typeof client !== 'object' || !client.id) continue
165
+ const names = [client.name, ...(Array.isArray(client.aliases) ? client.aliases : [])].filter(Boolean)
166
+ for (const name of names) {
167
+ const key = normalizeKey(name)
168
+ const keyCompact = key.replace(/[^a-z0-9\u4e00-\u9fff]/g, '')
169
+ if (keyCompact.length >= 3 && domain.includes(keyCompact)) {
170
+ clientHint = { id: client.id, name: client.name, basis: 'address-domain', confidence: 0.75 }
171
+ break
172
+ }
173
+ if (parsed.display && compact(normalizeKey(parsed.display)) === compact(normalizeKey(client.name))) {
174
+ clientHint = { id: client.id, name: client.name, basis: 'from-name', confidence: 0.8 }
175
+ break
176
+ }
177
+ }
178
+ if (clientHint) break
179
+ }
180
+ if (!clientHint) {
181
+ for (const client of Array.isArray(clients) ? clients : []) {
182
+ if (!client || typeof client !== 'object' || !client.id) continue
183
+ const names = [client.name, ...(Array.isArray(client.aliases) ? client.aliases : [])].filter(Boolean)
184
+ for (const name of names) {
185
+ const keyCompact = normalizeKey(name).replace(/[^a-z0-9\u4e00-\u9fff]/g, '')
186
+ if (!keyCompact) continue
187
+ const latin = /^[a-z0-9]+$/.test(keyCompact)
188
+ if (haystack.includes(keyCompact) && (!latin || keyCompact.length >= 3)) {
189
+ clientHint = { id: client.id, name: client.name, basis: 'message', confidence: 0.6 }
190
+ break
191
+ }
192
+ }
193
+ if (clientHint) break
194
+ }
195
+ }
196
+ let projectHint
197
+ const projectHaystack = compact(normalizeKey([subject, text].filter(Boolean).join(' ')))
198
+ for (const project of Array.isArray(projects) ? projects : []) {
199
+ if (!project || typeof project !== 'object' || !project.id) continue
200
+ const key = normalizeKey(project.name).replace(/[^a-z0-9\u4e00-\u9fff]/g, '')
201
+ if (key.length < 2 || !projectHaystack.includes(key)) continue
202
+ projectHint = { id: project.id, name: project.name, ...(project.clientId ? { clientId: project.clientId } : {}), basis: 'message', confidence: 0.6 }
203
+ break
204
+ }
205
+ return { clientHint, projectHint }
206
+ }
207
+
208
+ function exceedsQuote(quote) {
209
+ return String(quote).length > MAX_QUOTE_CHARS
210
+ }
211
+
212
+ function analyzeSentence(sentence, { messageDate, hints, parsedFrom, receivedAt }) {
213
+ const source = String(sentence)
214
+ if (REQUEST_RE.test(source) && !FIRST_PERSON_RE.test(source)) return null
215
+ const strong = STRONG_RE.test(source)
216
+ if (RESCHEDULE_RE.test(source) && !strong) return null
217
+ let debtor = null
218
+ if (/(?:我|我们|本人)(?:会|将|一定|保证|承诺|答应|争取|尽量)/.test(source)) debtor = 'user'
219
+ if (debtor == null && /(?:我|我们|本人)[^。!?!?\n]{0,60}(?:前|之前|以前|内|截止)/.test(source) && ACTION_VERBS.some((verb) => source.includes(verb))) debtor = 'user'
220
+ if (debtor == null && /(?:我|我们|本人)(?:明天|后天|今天|本周|这周|下周|下个月|月底|下周一|周[一二三四五六日天]|[0-9]{1,2}月[0-9]{1,2}[日号]|[0-9]{1,2}号)/.test(source) && ACTION_VERBS.some((verb) => source.includes(verb))) debtor = 'user'
221
+ if (debtor == null && /\b(?:i|we)\b[^.!?\n]{0,40}\b(?:will|'ll|shall|promise to|am going to|are going to)\b/i.test(source)) debtor = 'user'
222
+ if (debtor == null && /\b(?:i|we)\b[^.!?\n]{0,60}\b(?:by|before|no later than)\b/i.test(source) && /\b(?:send|submit|deliver|reply|confirm|provide|finish|complete|pay|share|prepare|upload|review|fix)\b/i.test(source)) debtor = 'user'
223
+ if (debtor == null && THIRD_PERSON_RE.test(source) && /(?:会|将|答应|承诺|同意|保证)/.test(source)) debtor = 'third'
224
+ if (debtor == null && /\b(?:he|she|they|the client|the vendor|the supplier)\b[^.!?\n]{0,30}\b(?:will|promised to|agreed to)\b/i.test(source)) debtor = 'third'
225
+ if (debtor == null) return null
226
+ const quote = source.trim()
227
+ if (!quote || exceedsQuote(quote)) return null
228
+ const action = actionOf(source)
229
+ if (!action) return null
230
+ const due = normalizeDue({ quote, text: source, messageDate })
231
+ const money = extractMailAmount(source)
232
+ const uncertain = TENTATIVE_RE.test(source)
233
+ const confidence = strong ? 0.85 : uncertain ? 0.55 : 0.7
234
+ const uncertaintyParts = []
235
+ if (due.ambiguous) uncertaintyParts.push('相对日期有歧义,已按消息时间解析')
236
+ if (uncertain) uncertaintyParts.push('语气为“尽量/争取”,不保证完成')
237
+ if (!due.dueAt) uncertaintyParts.push('未识别到明确日期')
238
+ return {
239
+ action,
240
+ debtor,
241
+ creditor: debtor === 'third' ? (hints.thirdPartyName ?? parsedFrom.display ?? undefined) : (parsedFrom.display || undefined),
242
+ ...(due.dueAt ? { dueAt: due.dueAt, dueBasis: due.basis } : {}),
243
+ ...(due.ambiguous ? { dueAmbiguous: true } : {}),
244
+ ...(money ? { amountMinor: money.amountMinor, currency: money.currency } : {}),
245
+ quote,
246
+ modal: strong ? 'firm' : uncertain ? 'tentative' : 'firm',
247
+ confidence,
248
+ uncertainty: uncertaintyParts.join(';').slice(0, 160),
249
+ extractor: 'local',
250
+ receivedAt: receivedAt ?? undefined,
251
+ }
252
+ }
253
+
254
+ /**
255
+ * Deterministic offline extraction for one message.
256
+ * @returns {{ candidates: object[], hints: {clientHint?, projectHint?} }}
257
+ */
258
+ export function extractLocalCandidates({
259
+ text = '', subject = '', from = '', receivedAt, clients = [], projects = [], now,
260
+ } = {}) {
261
+ const parsedFrom = parseFromAddress(from)
262
+ const hints = matchMailHints({ from, subject, text }, { clients, projects })
263
+ const messageDate = receivedAt ? new Date(receivedAt) : now instanceof Date ? now : new Date(now ?? Date.now())
264
+ const anchor = Number.isFinite(messageDate.getTime()) ? messageDate : new Date()
265
+ const normalizedQuote = compact(text)
266
+ const candidates = []
267
+ for (const sentence of splitSentences(text)) {
268
+ if (candidates.length >= LOCAL_MAX_CANDIDATES) break
269
+ const candidate = analyzeSentence(sentence, { messageDate: anchor, hints, parsedFrom, receivedAt: anchor.toISOString() })
270
+ if (!candidate) continue
271
+ if (!normalizedQuote.includes(compact(candidate.quote))) continue
272
+ const duplicate = candidates.some((row) => row.quote === candidate.quote)
273
+ if (duplicate) continue
274
+ candidates.push({ ...candidate, ...(hints.clientHint ? { clientHint: hints.clientHint } : {}), ...(hints.projectHint ? { projectHint: hints.projectHint } : {}) })
275
+ }
276
+ return { candidates, hints }
277
+ }
278
+
279
+ /**
280
+ * Build the source-ref object stored on a mail candidate's evidence.
281
+ * IMAP rows use `imap:<account>:<uidvalidity>:<uid>`; .eml rows use
282
+ * `eml:<account>:<messageRowId>`. Quote-only evidence; never the body.
283
+ */
284
+ export function mailEvidenceSource(message, { now } = {}) {
285
+ const accountId = message?.accountId ?? 'unknown'
286
+ const localRow = message?.uidvalidity === 'local' || message?.mailbox === 'local'
287
+ const ref = message?.uid != null && !localRow
288
+ ? 'imap:' + accountId + ':' + (message.uidvalidity ?? 'unknown') + ':' + message.uid
289
+ : 'eml:' + accountId + ':' + (message.id ?? 'unknown')
290
+ const capturedAt = message?.receivedAt ?? (now instanceof Date ? now.toISOString() : new Date().toISOString())
291
+ return {
292
+ type: 'mail',
293
+ ref,
294
+ ...(message?.messageId ? { messageId: message.messageId } : {}),
295
+ ...(message?.subject ? { subject: String(message.subject).slice(0, 200) } : {}),
296
+ capturedAt,
297
+ }
298
+ }
299
+
300
+ /**
301
+ * Map one extractor candidate to the memory_candidates shape reused by
302
+ * `advisers memory accept` (kind 'commitment', payload + evidence).
303
+ */
304
+ export function toMemoryCandidate(candidate, { message, matterId, now } = {}) {
305
+ const payload = {
306
+ ...(matterId ? { matterId } : {}),
307
+ debtor: candidate.debtor === 'third' ? 'third' : 'user',
308
+ creditor: candidate.creditor || 'someone',
309
+ action: candidate.action,
310
+ ...(candidate.dueAt ? { dueAt: candidate.dueAt } : {}),
311
+ capability: 'none',
312
+ extractor: candidate.extractor ?? 'local',
313
+ ...(candidate.amountMinor ? { amountMinor: candidate.amountMinor, currency: candidate.currency ?? 'CNY' } : {}),
314
+ ...(candidate.clientHint ? { clientHint: candidate.clientHint } : {}),
315
+ ...(candidate.projectHint ? { projectHint: candidate.projectHint } : {}),
316
+ }
317
+ return { kind: 'commitment', payload, evidence: [{ quote: candidate.quote, source: mailEvidenceSource(message, { now }) }] }
318
+ }
319
+
320
+ /**
321
+ * OPT-IN model extraction. Never called by mailSync or by the local default.
322
+ * Requires an API key and reuses lib/capture.js (safety classify + verbatim
323
+ * quote validation) with the body inside the untrusted-data boundary.
324
+ */
325
+ export async function extractCandidatesWithModel({
326
+ text = '', subject = '', from = '', receivedAt, apiKey, baseUrl, model, fetchImpl, safetyKey,
327
+ maxChars = MODEL_MAX_INPUT_CHARS, now,
328
+ } = {}) {
329
+ if (!apiKey) {
330
+ throw mailError(MAIL_ERROR_CODES.MODEL_DISABLED, 'mail extract --model requires ADVISERS_API_KEY', 'model extraction is opt-in; the default --local path never calls a model')
331
+ }
332
+ const body = String(text == null ? '' : text).slice(0, Math.max(1, Number(maxChars) || MODEL_MAX_INPUT_CHARS))
333
+ if (!body.trim()) return { candidates: [], safetyWarnings: [] }
334
+ const [{ wrapUntrusted }, { captureCandidates }] = await Promise.all([import('./untrusted.js'), import('./capture.js')])
335
+ const wrapped = wrapUntrusted('mail:message', body)
336
+ let messageDate = receivedAt ? new Date(receivedAt) : now ? new Date(now) : new Date()
337
+ if (!Number.isFinite(messageDate.getTime())) messageDate = new Date()
338
+ const result = await captureCandidates({
339
+ text: wrapped, apiKey, baseUrl, model, fetchImpl,
340
+ date: messageDate, source: 'email', now: messageDate, safetyKey,
341
+ })
342
+ const candidates = (Array.isArray(result.candidates) ? result.candidates : []).map((candidate) => ({
343
+ ...candidate,
344
+ extractor: 'model',
345
+ receivedAt: messageDate.toISOString(),
346
+ }))
347
+ return {
348
+ candidates,
349
+ ...(Array.isArray(result.safetyWarnings) && result.safetyWarnings.length ? { safetyWarnings: result.safetyWarnings } : {}),
350
+ }
351
+ }