advisers 0.3.2 → 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 (44) hide show
  1. package/README-zh.md +13 -14
  2. package/README.md +32 -23
  3. package/THIRD-PARTY-NOTICES.md +1 -1
  4. package/bin/advisers.js +2180 -92
  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/error-codes.js +516 -7
  11. package/lib/evidence.js +697 -113
  12. package/lib/kb-extract.js +626 -0
  13. package/lib/kb-facts.js +429 -0
  14. package/lib/kb-pages.js +1084 -0
  15. package/lib/kb.js +1036 -0
  16. package/lib/mail-errors.js +46 -0
  17. package/lib/mail-extract.js +351 -0
  18. package/lib/mail-imap.js +446 -0
  19. package/lib/mail-import.js +176 -0
  20. package/lib/mail-parse.js +223 -0
  21. package/lib/mail-store.js +731 -0
  22. package/lib/mail.js +506 -0
  23. package/lib/mcp-server.js +196 -10
  24. package/lib/notify.js +265 -7
  25. package/lib/policy/decision.js +315 -0
  26. package/lib/policy/egress.js +268 -0
  27. package/lib/policy/errors.js +71 -0
  28. package/lib/policy/index.js +99 -0
  29. package/lib/policy/rules.js +468 -0
  30. package/lib/policy/surfaces.js +141 -0
  31. package/lib/receipt-verify.js +199 -19
  32. package/lib/receivables.js +1653 -0
  33. package/lib/scheduler.js +453 -9
  34. package/lib/shell.js +1406 -0
  35. package/lib/source.js +98 -3
  36. package/lib/sqlite.js +366 -49
  37. package/lib/tos/index.js +2 -2
  38. package/lib/tos/manifest.json +6 -6
  39. package/lib/tos/privacy.zh-CN.md +33 -20
  40. package/lib/tos/safety.zh-CN.md +7 -6
  41. package/lib/tos/summary.zh-CN.md +3 -2
  42. package/lib/tos/terms.zh-CN.md +31 -16
  43. package/lib/urgency.js +467 -0
  44. package/package.json +4 -4
package/lib/source.js CHANGED
@@ -16,6 +16,11 @@
16
16
  * { sourceVersion: 2, type, quote, ref, messageId, subject, file, mime,
17
17
  * speaker, tStart, tEnd, capturedAt }
18
18
  *
19
+ * 0.4 extends the canonical type list (kb_chunk, kb_page, web, tool) without
20
+ * changing the shape: typed pointer fields (docId/pageId/url/tool) and the
21
+ * additive flags (chunkIndex, retained, derivedFrom) are preserved as
22
+ * extensions so older readers keep ignoring them.
23
+ *
19
24
  * normalizeSource() maps legacy rows into this shape (and preserves unknown
20
25
  * fields as extensions so old consumers keep working); validateSource() reports
21
26
  * schema problems; toLegacySource() produces the lossy v1 view for consumers
@@ -28,12 +33,46 @@
28
33
  /** Current source schema version. */
29
34
  export const SOURCE_VERSION = 2
30
35
 
31
- /** Canonical source types; any other stored type is preserved with a warning. */
32
- export const SOURCE_TYPES = Object.freeze(['conversation', 'mail', 'calendar', 'transcript'])
36
+ /**
37
+ * Canonical source types; any other stored type is preserved with a warning.
38
+ *
39
+ * 0.4 adds the data-bearing types introduced by the mail/KB evidence lines:
40
+ * kb_chunk / kb_page local KB chunk/page ids (stable, never reused)
41
+ * web a URL reference; the page itself is never cached
42
+ * tool a tool result reference; tool bodies are not turns
43
+ * The four 0.2.0 types stay byte-compatible: normalizeSource() never rewrites
44
+ * stored rows, and old readers keep ignoring the new type values.
45
+ */
46
+ export const SOURCE_TYPES = Object.freeze([
47
+ 'conversation',
48
+ 'mail',
49
+ 'calendar',
50
+ 'transcript',
51
+ 'kb_chunk',
52
+ 'kb_page',
53
+ 'web',
54
+ 'tool',
55
+ ])
33
56
 
34
57
  /** Legacy type spellings that map onto a canonical type. */
35
58
  export const SOURCE_TYPE_ALIASES = Object.freeze({ email: 'mail' })
36
59
 
60
+ /**
61
+ * Pointer fields that identify the source for each type (in addition to the
62
+ * generic `ref`). Used by validateSource() and lib/evidence.js to decide
63
+ * whether a typed source can be resolved without inventing a conversation turn.
64
+ */
65
+ export const SOURCE_POINTER_FIELDS = Object.freeze({
66
+ conversation: Object.freeze(['ref']),
67
+ mail: Object.freeze(['ref', 'messageId', 'file']),
68
+ calendar: Object.freeze(['ref']),
69
+ transcript: Object.freeze(['ref', 'file']),
70
+ kb_chunk: Object.freeze(['ref', 'docId']),
71
+ kb_page: Object.freeze(['ref', 'pageId']),
72
+ web: Object.freeze(['ref', 'url']),
73
+ tool: Object.freeze(['ref', 'turnId', 'tool']),
74
+ })
75
+
37
76
  const VERSION_KEYS = ['sourceVersion', 'source_v', 'source_version']
38
77
  const FIELDS = Object.freeze([
39
78
  'type',
@@ -230,6 +269,22 @@ export function validateSource(raw) {
230
269
  if (raw.file !== undefined && typeof raw.file === 'string' && hasPathSeparator(raw.file)) {
231
270
  errors.push('file must be a basename, not a path')
232
271
  }
272
+ for (const field of ['docId', 'pageId', 'url', 'tool']) {
273
+ if (raw[field] === undefined || raw[field] === null) continue
274
+ if (typeof raw[field] !== 'string' || !raw[field].trim()) errors.push(field + ' must be a non-empty string')
275
+ }
276
+ if (raw.chunkIndex !== undefined && raw.chunkIndex !== null) {
277
+ if (!Number.isInteger(raw.chunkIndex) || raw.chunkIndex < 0) errors.push('chunkIndex must be a non-negative integer')
278
+ }
279
+ if (raw.retained !== undefined && raw.retained !== null && typeof raw.retained !== 'boolean') {
280
+ errors.push('retained must be a boolean')
281
+ }
282
+ if (raw.derivedFrom !== undefined && raw.derivedFrom !== null) {
283
+ if (!Array.isArray(raw.derivedFrom)) errors.push('derivedFrom must be an array of strings')
284
+ else if (raw.derivedFrom.some((item) => typeof item !== 'string' || !item.trim())) {
285
+ errors.push('derivedFrom entries must be non-empty strings')
286
+ }
287
+ }
233
288
  if (raw.mime !== undefined && typeof raw.mime === 'string' && raw.mime.trim() && !MIME_TYPE.test(raw.mime.trim())) {
234
289
  errors.push('mime must look like type/subtype')
235
290
  }
@@ -249,7 +304,15 @@ export function validateSource(raw) {
249
304
  if (Date.parse(raw.tStart) > Date.parse(raw.tEnd)) errors.push('tStart must not be after tEnd')
250
305
  }
251
306
 
252
- const hasPointer = Boolean(normalized.ref || normalized.messageId || normalized.file)
307
+ const hasPointer = Boolean(
308
+ normalized.ref ||
309
+ normalized.messageId ||
310
+ normalized.file ||
311
+ normalized.docId ||
312
+ normalized.pageId ||
313
+ normalized.url ||
314
+ (normalized.turnId && normalized.tool),
315
+ )
253
316
  const hasQuote = typeof normalized.quote === 'string' && normalized.quote.length > 0
254
317
  if (!hasPointer && !hasQuote) {
255
318
  errors.push('source has neither a pointer (ref/messageId/file) nor a quote')
@@ -258,6 +321,38 @@ export function validateSource(raw) {
258
321
  return { ok: errors.length === 0, errors, warnings, source: normalized }
259
322
  }
260
323
 
324
+ /** Canonical (lower-cased, alias-mapped) source type value, or '' when absent. */
325
+ export function canonicalSourceType(value) {
326
+ return canonicalType(value)
327
+ }
328
+
329
+ /** Canonical (lower-cased, alias-mapped) source type, or '' when absent. */
330
+ export function sourceTypeOf(raw) {
331
+ if (!isPlainObject(raw)) return ''
332
+ const direct = canonicalType(raw.type)
333
+ if (direct) return direct
334
+ return ''
335
+ }
336
+
337
+ /**
338
+ * JSON-ready pointer description used by the evidence resolver.
339
+ *
340
+ * Normalises a v1/v2/typed source (or a legacy commitment evidence item that
341
+ * carries sessionId/turnId) and returns only the fields needed to resolve it:
342
+ * {type, quote, ref, messageId, subject, docId, pageId, chunkIndex, url, tool,
343
+ * retained, derivedFrom}. Missing fields are omitted; unknown input -> null.
344
+ * It never invents a ref and never reads a database.
345
+ */
346
+ export function describeSourcePointer(raw) {
347
+ const normalized = normalizeSource(raw)
348
+ if (!normalized) return null
349
+ const pointer = { type: normalized.type }
350
+ for (const field of ['quote', 'ref', 'messageId', 'subject', 'docId', 'pageId', 'chunkIndex', 'url', 'tool', 'retained', 'derivedFrom']) {
351
+ if (normalized[field] !== undefined && normalized[field] !== null && normalized[field] !== '') pointer[field] = normalized[field]
352
+ }
353
+ return pointer
354
+ }
355
+
261
356
  /** True when a row already carries the v2 version marker. */
262
357
  export function isSourceV2(raw) {
263
358
  if (!isPlainObject(raw)) return false