@restregular/dsh-memory 0.23.0 → 0.24.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.
@@ -35,6 +35,20 @@ import {
35
35
 
36
36
  } from './session-visibility.js'
37
37
  import { WorkspaceBindingsStore } from './workspace-bindings.js'
38
+ import { SessionGrantsStore, } from './grants.js'
39
+ import { ApprovalAuditStore, } from './approval-audit.js'
40
+ import {
41
+ authorize as authorizeAccess,
42
+
43
+
44
+
45
+ } from './authorize.js'
46
+ import {
47
+ MAX_SCOPE_DESCRIPTION_CHARS,
48
+ ScopeMetaStore,
49
+
50
+
51
+ } from './scope-meta.js'
38
52
  import { mergeInjectSettings, normalizeInjectSettings, } from './inject-settings.js'
39
53
  import { buildStats, lexicalScore, recordScore, tokenize, cosine, normalizeInPlace, hasStrongHit } from './scoring.js'
40
54
  import { EmbedClient } from './embed.js'
@@ -520,6 +534,37 @@ export function resolveConfig(config = {}) {
520
534
 
521
535
 
522
536
 
537
+ /**
538
+ * 目录工具(memory_scopes list)的一行:作用域的“身份证 + 当前访问状态”。
539
+ *
540
+ * 0.24.0 起目录可见与正文可读是两件事:
541
+ * - `absolute` 下范围外作用域仍列出名字/用途(`accessStatus='restricted'`),
542
+ * 但 `readable/writable` 恒为 false,`canRequest*` 也恒为 false —— absolute
543
+ * 没有任何审批放行路径;
544
+ * - `normal` 下范围外可申请,`canRequest*` 才是 true;
545
+ * - 自定义作用域开关关闭时整个条目不出现(不是 `unavailable`)。
546
+ */
547
+
548
+
549
+
550
+
551
+
552
+                            
553
+
554
+
555
+
556
+
557
+
558
+
559
+
560
+
561
+
562
+                       
563
+                                     
564
+
565
+
566
+
567
+
523
568
  /** 范围外访问的动作(读取 / 写入 / 删除);审批浮层按它换文案。 */
524
569
 
525
570
 
@@ -534,6 +579,8 @@ export function resolveConfig(config = {}) {
534
579
 
535
580
                                    
536
581
 
582
+                      
583
+
537
584
 
538
585
 
539
586
 
@@ -546,6 +593,11 @@ export function resolveConfig(config = {}) {
546
593
 
547
594
                              
548
595
 
596
+
597
+                        
598
+                       
599
+
600
+
549
601
 
550
602
 
551
603
 
@@ -554,6 +606,32 @@ export function resolveConfig(config = {}) {
554
606
  /** 一次审批的结局:允许(可只允许其中几条) / 拒绝 / 超时。 */
555
607
 
556
608
 
609
+ /** 一条作用域权限申请的处理结果(0.24.0 / D3)。 */
610
+
611
+
612
+
613
+
614
+
615
+
616
+
617
+
618
+
619
+
620
+
621
+
622
+
623
+
624
+                
625
+
626
+
627
+
628
+
629
+
630
+
631
+                 
632
+
633
+
634
+
557
635
  /**
558
636
  * 审批结论(0.21.0)。`allowedIds` 省略 = 本次请求的所有条目都允许;
559
637
  * 用户在审批卡里逐条勾选时只带被勾选的条目 id。
@@ -597,12 +675,18 @@ export class LocalMemoryService {
597
675
  scopesReconciled = false
598
676
  /** 作用域别名(project:<路径> → 显示名),落盘 <storeDir>/scopes.json。 */
599
677
  names
678
+ /** 作用域用途等元数据;每作用域一个文件,旧作用域按需懒合成。 */
679
+ meta
600
680
  /** 注入设置(面板「设置」标签页可改;落盘在 <storeDir>/settings.json)。 */
601
681
  inject
602
682
  /** 会话级「记忆可见范围」覆盖;没有覆盖时沿用默认集合。 */
603
683
  visibility
604
684
  /** 工作区级「绑定作用域」:默认范围会额外并入这些作用域。 */
605
685
  bindings
686
+ /** 会话级授权(Agent 申请、用户批准);独立于 visibility 策略。 */
687
+ grants
688
+ /** 权限申请 / 授权生命周期审计(approvals.jsonl,不含正文)。 */
689
+ approvalAudit
606
690
  /** 可见域变更通知:下一次 pre-step 注入给 Agent 后删除(按会话)。 */
607
691
  visibilityNotices = new Map ()
608
692
  /** 普通限制下等待用户审批的范围外访问(按审批 id)。 */
@@ -626,8 +710,11 @@ export class LocalMemoryService {
626
710
  this.cfg = resolveConfig(config)
627
711
  this.inject = this.loadInjectSettings((config ).inject)
628
712
  this.names = new ScopeNames(join(this.cfg.storeDir, 'scopes.json'))
713
+ this.meta = new ScopeMetaStore({ root: this.cfg.storeDir })
629
714
  this.visibility = new SessionVisibilityStore({ root: this.cfg.storeDir })
630
715
  this.bindings = new WorkspaceBindingsStore({ root: this.cfg.storeDir })
716
+ this.grants = new SessionGrantsStore({ root: this.cfg.storeDir })
717
+ this.approvalAudit = new ApprovalAuditStore({ root: this.cfg.storeDir })
631
718
  this.rerankBudget = new DailyBudget(this.cfg.llm.dailyBudgetTokens)
632
719
  this.store = new MemoryStore(this.cfg.storeDir, { onWarn: (m) => console.warn(`[dsh-memory-local] ${m}`) })
633
720
  // Identity BEFORE the eager load (issue #1): ScopeStore skips its sidecar
@@ -1352,7 +1439,8 @@ export class LocalMemoryService {
1352
1439
  */
1353
1440
  assertCustomScopeBudget(scope ) {
1354
1441
  if (!isCustomScope(scope)) return
1355
- if (this.store.peek(scope) !== undefined) return // 已存在(内存或磁盘)→ 写入不受限
1442
+ // 已有记录或已有元数据都算“已存在”:删光记录但保留元数据的作用域不该再占一个新名额。
1443
+ if (this.store.peek(scope) !== undefined || this.meta.has(scope)) return
1356
1444
  const loaded = this.store.allScopes().filter((s) => isCustomScope(s.scope)).length
1357
1445
  if (loaded < this.cfg.customMaxScopes && this.store.customScopeCount() < this.cfg.customMaxScopes) return
1358
1446
  throw memoryError(
@@ -1469,8 +1557,55 @@ export class LocalMemoryService {
1469
1557
  }
1470
1558
  }
1471
1559
 
1560
+ /**
1561
+ * 沿 parentSession 链收集 grant(当前会话在前、父会话在后)。
1562
+ * 子 Agent 与父会话是同一个任务,应该继承父会话获批的权限。
1563
+ */
1564
+ resolveGrantChain(sessionId ) {
1565
+ const out = []
1566
+ const seen = new Set ()
1567
+ let id = sessionId
1568
+ while (id !== '' && !seen.has(id)) {
1569
+ seen.add(id)
1570
+ out.push(...this.grants.list(id))
1571
+ let parent
1572
+ try {
1573
+ const session = this.sessionLookup?.(id)
1574
+ parent = typeof session?.header?.parentSession === 'string' && session.header.parentSession !== ''
1575
+ ? session.header.parentSession
1576
+ : undefined
1577
+ } catch { parent = undefined }
1578
+ id = parent ?? ''
1579
+ }
1580
+ return out
1581
+ }
1582
+
1583
+ /**
1584
+ * 当前 agent 的有效 grant:作用域仍启用、作用域代次一致(同名重建不复用旧授权)。
1585
+ * `grants.list()` 已过滤撤销 / 过期;这里再按 provider 的 canonicalScope 统一键。
1586
+ */
1587
+ validGrants(agent ) {
1588
+ const sessionId = this.rawSessionIdOf(agent)
1589
+ if (sessionId === undefined) return []
1590
+ const out = []
1591
+ for (const grant of this.resolveGrantChain(sessionId)) {
1592
+ const scope = this.canonicalScope(grant.scope)
1593
+ if (!this.scopeEnabled(scope)) continue
1594
+ const meta = this.meta.get(scope)
1595
+ if (meta !== undefined && grant.scopeGeneration !== meta.generation) continue
1596
+ out.push({ ...grant, scope })
1597
+ }
1598
+ return out
1599
+ }
1600
+
1601
+ /** 面板/诊断:当前会话(含父链)的有效授权快照。 */
1602
+ activeGrants(agent ) {
1603
+ return this.validGrants(agent)
1604
+ }
1605
+
1472
1606
  /** 没有显式覆盖时的默认可见域范围(会话 + 项目 + global + 工作区绑定的作用域)。 */
1473
- defaultReadScopes(agent ) {
1607
+ /** 默认三路(会话 + 项目 + global),**不含**工作区绑定;各自开关生效。 */
1608
+ baseDefaultScopes(agent ) {
1474
1609
  const refs = this.scopeRefs(agent)
1475
1610
  const out = []
1476
1611
  const push = (scope , enabled ) => {
@@ -1480,12 +1615,32 @@ export class LocalMemoryService {
1480
1615
  push(refs.session, this.cfg.sessionEnabled)
1481
1616
  push(refs.project, this.cfg.projectEnabled)
1482
1617
  push('global', this.cfg.globalEnabled)
1618
+ return out
1619
+ }
1620
+
1621
+ /**
1622
+ * 面板:默认可见范围的**基础集合**(会话 + 项目 + global)。
1623
+ * 这些作用域天然包含在默认范围里,面板把它们显示为「已绑定」且不可取消;
1624
+ * 工作区绑定只用于**额外**并入的作用域。
1625
+ */
1626
+ defaultScopes(agent ) {
1627
+ return this.baseDefaultScopes(agent)
1628
+ }
1629
+
1630
+ /** 没有显式覆盖时的默认可见域范围(基础三路 + 工作区绑定的额外作用域)。 */
1631
+ defaultReadScopes(agent ) {
1632
+ const out = this.baseDefaultScopes(agent)
1633
+ const push = (scope ) => {
1634
+ if (out.includes(scope)) return
1635
+ out.push(scope)
1636
+ }
1483
1637
  // 0.23.0:工作区绑定的作用域默认可见。会话作用域不能绑定,这里再守一次。
1638
+ const refs = this.scopeRefs(agent)
1484
1639
  for (const raw of this.bindings.get(refs.project)) {
1485
1640
  const scope = this.canonicalScope(raw)
1486
1641
  if (scopeKind(scope) === 'session') continue
1487
1642
  if (!this.scopeEnabled(scope)) continue
1488
- push(scope, true)
1643
+ push(scope)
1489
1644
  }
1490
1645
  return out
1491
1646
  }
@@ -1545,33 +1700,62 @@ export class LocalMemoryService {
1545
1700
  return rule.kinds !== undefined && rule.kinds.length > 0 ? [...rule.kinds] : undefined
1546
1701
  }
1547
1702
 
1548
- /** 一条记录(scope + kind)是否落在当前可见域内;等级 none 时恒为 true。 */
1549
- isRecordVisible(agent , scope , kind ) {
1703
+ /**
1704
+ * 把 agent 解析成一次性授权上下文(可见域只解析一次)。
1705
+ * 纯函数 `authorize()` 是唯一规则出口;这里只负责把配置 / 策略翻译成上下文。
1706
+ */
1707
+ accessContext(agent ) {
1550
1708
  const policy = this.visibilityPolicy(agent)
1551
- if (policy.level === 'none') return true
1552
- const key = this.canonicalScope(scope)
1553
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1554
- if (rule === undefined || rule.read === false) return false
1555
- if (rule.kinds === undefined || rule.kinds.length === 0) return true
1556
- return rule.kinds.includes(kind)
1709
+ return {
1710
+ level: policy.level,
1711
+ scopes: policy.scopes,
1712
+ enabled: {
1713
+ global: this.cfg.globalEnabled,
1714
+ project: this.cfg.projectEnabled,
1715
+ session: this.cfg.sessionEnabled,
1716
+ custom: this.cfg.customEnabled,
1717
+ },
1718
+ originOf: (scope) => scopeKind(scope),
1719
+ grants: this.validGrants(agent),
1720
+ }
1721
+ }
1722
+
1723
+ /**
1724
+ * 统一授权判定:discover / read / write / delete 全部走这里。
1725
+ * 工具层、检索过滤、目录与注入都应以它为准,不再各自解释 absolute / normal / none。
1726
+ */
1727
+ authorize(agent , request ) {
1728
+ return authorizeAccess(
1729
+ { ...request, scope: this.canonicalScope(request.scope) },
1730
+ this.accessContext(agent),
1731
+ )
1732
+ }
1733
+
1734
+ /**
1735
+ * 一次解析、多次判定的版本:检索会逐条判定命中,不能每条都重新解析可见域
1736
+ * (那会重复读会话文件、重复走 parentSession 链)。
1737
+ */
1738
+ accessEvaluator(agent ) {
1739
+ const context = this.accessContext(agent)
1740
+ return (request) => authorizeAccess(
1741
+ { ...request, scope: this.canonicalScope(request.scope) },
1742
+ context,
1743
+ )
1744
+ }
1745
+
1746
+ /** 一条记录(scope + kind)是否可读。 */
1747
+ isRecordVisible(agent , scope , kind ) {
1748
+ return this.authorize(agent, { scope, action: 'read', kind }).allowed
1557
1749
  }
1558
1750
 
1559
1751
  /** 某个作用域是否可读(0.23.0:read 开关);等级 none 时恒为 true。 */
1560
1752
  isScopeReadable(agent , scope ) {
1561
- const policy = this.visibilityPolicy(agent)
1562
- if (policy.level === 'none') return true
1563
- const key = this.canonicalScope(scope)
1564
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1565
- return rule !== undefined && rule.read !== false
1753
+ return this.authorize(agent, { scope, action: 'read' }).allowed
1566
1754
  }
1567
1755
 
1568
1756
  /** 某个作用域是否可写(0.23.0:write 开关);等级 none 时恒为 true。 */
1569
1757
  isScopeWritable(agent , scope ) {
1570
- const policy = this.visibilityPolicy(agent)
1571
- if (policy.level === 'none') return true
1572
- const key = this.canonicalScope(scope)
1573
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1574
- return rule !== undefined && rule.write !== false
1758
+ return this.authorize(agent, { scope, action: 'write' }).allowed
1575
1759
  }
1576
1760
 
1577
1761
  /**
@@ -1587,21 +1771,9 @@ export class LocalMemoryService {
1587
1771
  * undefined = 不限制。
1588
1772
  */
1589
1773
  visibilityFilterFor(agent ) {
1590
- const policy = this.visibilityPolicy(agent)
1591
- if (policy.level === 'none') return undefined
1592
- const byScope = new Map ()
1593
- for (const rule of policy.scopes) {
1594
- byScope.set(this.canonicalScope(rule.scope), {
1595
- kinds: rule.kinds !== undefined && rule.kinds.length > 0 ? rule.kinds : undefined,
1596
- read: rule.read !== false,
1597
- })
1598
- }
1599
- return (scope, kind) => {
1600
- const key = this.canonicalScope(scope)
1601
- const entry = byScope.get(key)
1602
- if (entry === undefined || !entry.read) return false
1603
- return entry.kinds === undefined || entry.kinds.includes(kind)
1604
- }
1774
+ if (this.visibilityPolicy(agent).level === 'none') return undefined
1775
+ const evaluate = this.accessEvaluator(agent)
1776
+ return (scope, kind) => evaluate({ scope, action: 'read', kind }).allowed
1605
1777
  }
1606
1778
 
1607
1779
  /** 面板:读取某会话自己的覆盖(null = 没有覆盖,继续用默认集合)。 */
@@ -1755,6 +1927,8 @@ export class LocalMemoryService {
1755
1927
 
1756
1928
                        
1757
1929
 
1930
+                   
1931
+
1758
1932
 
1759
1933
 
1760
1934
  ,
@@ -1766,18 +1940,37 @@ export class LocalMemoryService {
1766
1940
  const createdAt = Date.now()
1767
1941
  const expiresAt = createdAt + VISIBILITY_APPROVAL_TTL_MS
1768
1942
  const description = typeof input.description === 'string' ? input.description.replace(/\s+/g, ' ').trim().slice(0, 500) : ''
1943
+ const auditBase = {
1944
+ at: createdAt,
1945
+ event: 'requested',
1946
+ id,
1947
+ sessionId,
1948
+ tool: input.tool,
1949
+ action: input.action ?? 'read',
1950
+ mode: input.mode ?? 'records',
1951
+ scopes: [...new Set(input.items.map((item) => item.scope))],
1952
+ count: input.items.length,
1953
+ ...(description !== '' ? { description } : {}),
1954
+ }
1955
+ this.approvalAudit.append(auditBase)
1769
1956
  return new Promise((resolve) => {
1770
1957
  let timer
1771
- const onAbort = () => finish({ outcome: 'rejected' })
1772
- const finish = (answer ) => {
1958
+ const onAbort = () => finish({ outcome: 'rejected' }, 'aborted')
1959
+ const finish = (answer , why ) => {
1773
1960
  const pending = this.pendingApprovals.get(id)
1774
1961
  if (pending === undefined) return
1775
1962
  this.pendingApprovals.delete(id)
1776
1963
  if (timer !== undefined) clearTimeout(timer)
1777
1964
  try { input.signal?.removeEventListener('abort', onAbort) } catch { /* 已卸载 */ }
1965
+ this.approvalAudit.append({
1966
+ ...auditBase,
1967
+ at: Date.now(),
1968
+ event: why === 'timeout' ? 'timeout' : 'denied',
1969
+ outcome: answer.outcome,
1970
+ })
1778
1971
  pending.resolve(answer)
1779
1972
  }
1780
- timer = setTimeout(() => finish({ outcome: 'timeout' }), VISIBILITY_APPROVAL_TTL_MS)
1973
+ timer = setTimeout(() => finish({ outcome: 'timeout' }, 'timeout'), VISIBILITY_APPROVAL_TTL_MS)
1781
1974
  timer.unref?.()
1782
1975
  this.pendingApprovals.set(id, {
1783
1976
  id,
@@ -1786,6 +1979,7 @@ export class LocalMemoryService {
1786
1979
  action: input.action ?? 'read',
1787
1980
  query: input.query,
1788
1981
  ...(description !== '' ? { description } : {}),
1982
+ ...(input.mode !== undefined ? { mode: input.mode } : {}),
1789
1983
  items: input.items.slice(0, VISIBILITY_APPROVAL_MAX_ITEMS).map((item) => ({
1790
1984
  ...item,
1791
1985
  tags: [...item.tags],
@@ -1811,6 +2005,7 @@ export class LocalMemoryService {
1811
2005
  action: pending.action,
1812
2006
  query: pending.query,
1813
2007
  ...(pending.description !== undefined ? { description: pending.description } : {}),
2008
+ ...(pending.mode !== undefined ? { mode: pending.mode } : {}),
1814
2009
  // 轮询载荷保持轻量:正文截到 1200 字,悬浮需要全文时面板再按 id 取一次。
1815
2010
  items: pending.items.map((item) => ({
1816
2011
  ...item,
@@ -1845,10 +2040,172 @@ export class LocalMemoryService {
1845
2040
  } else {
1846
2041
  answer = { outcome: 'allowed-once' }
1847
2042
  }
2043
+ this.approvalAudit.append({
2044
+ at: Date.now(),
2045
+ event: answer.outcome === 'allowed-once' ? 'approved' : 'denied',
2046
+ id,
2047
+ sessionId: pending.sessionId,
2048
+ tool: pending.tool,
2049
+ action: pending.action,
2050
+ mode: pending.mode ?? 'records',
2051
+ scopes: [...new Set(pending.items.map((item) => item.scope))],
2052
+ count: pending.items.length,
2053
+ outcome: answer.outcome,
2054
+ })
1848
2055
  pending.resolve(answer)
1849
2056
  return true
1850
2057
  }
1851
2058
 
2059
+ /**
2060
+ * Agent 主动申请范围外作用域的会话权限(0.24.0 / D3)。
2061
+ *
2062
+ * 流程:先按统一授权判定逐条筛(已允许 / 已授权 / 不可申请都不弹卡),
2063
+ * 只把**可申请**的 scope + 权限合成审批卡(`mode='grant'`),用户批准后
2064
+ * 写入 `grants/<session>.json`(仅本会话,子 Agent 沿 parentSession 继承)。
2065
+ *
2066
+ * 一次性访问**不在**这里:它继续由 memory_* 的隐式审批处理;本工具只申请会话授权。
2067
+ */
2068
+ async requestScopeGrants(
2069
+ agent ,
2070
+ input
2071
+
2072
+
2073
+
2074
+
2075
+ ,
2076
+ ) {
2077
+ const sessionId = this.rawSessionIdOf(agent)
2078
+ const results = []
2079
+ const describe = (request ) =>
2080
+ [...new Set(request.permissions.filter((item) => item === 'read' || item === 'write'))]
2081
+ if (sessionId === undefined) {
2082
+ for (const request of input.requests) {
2083
+ const scope = this.canonicalScope(request.scope)
2084
+ for (const permission of describe(request)) results.push({ scope, permission, status: 'unavailable' })
2085
+ }
2086
+ return { results, outcome: 'unavailable', grants: [] }
2087
+ }
2088
+
2089
+ const pending = []
2090
+ const seen = new Set ()
2091
+ for (const request of input.requests) {
2092
+ const scope = this.canonicalScope(request.scope)
2093
+ for (const permission of describe(request)) {
2094
+ const key = `${scope}\0${permission}`
2095
+ if (seen.has(key)) continue
2096
+ seen.add(key)
2097
+ const decision = this.authorize(agent, { scope, action: permission === 'read' ? 'read' : 'write' })
2098
+ if (decision.allowed) {
2099
+ results.push({
2100
+ scope,
2101
+ permission,
2102
+ status: decision.source === 'grant' ? 'already-granted' : 'already-allowed',
2103
+ })
2104
+ continue
2105
+ }
2106
+ if (!decision.requestable) {
2107
+ results.push({ scope, permission, status: 'not-requestable', ...(decision.reason !== undefined ? { reason: decision.reason } : {}) })
2108
+ continue
2109
+ }
2110
+ pending.push({ id: `grant:${scope}:${permission}`, scope, permission })
2111
+ }
2112
+ }
2113
+ if (pending.length === 0) return { results, grants: [] }
2114
+
2115
+ const reason = typeof input.reason === 'string' ? input.reason.replace(/\s+/g, ' ').trim().slice(0, 500) : ''
2116
+ const answer = await this.requestOutOfScope(agent, {
2117
+ tool: 'memory_scopes',
2118
+ action: 'read',
2119
+ query: reason === '' ? [...new Set(pending.map((item) => item.scope))].join(' ') : reason,
2120
+ ...(input.description !== undefined ? { description: input.description } : {}),
2121
+ mode: 'grant',
2122
+ items: pending.map((item) => ({
2123
+ id: item.id,
2124
+ scope: item.scope,
2125
+ kind: 'grant',
2126
+ content: item.permission === 'read' ? '只读访问' : '写入 / 删除',
2127
+ tags: [],
2128
+ importance: 0,
2129
+ updatedAt: Date.now(),
2130
+ reason: 'scope' ,
2131
+ grantPermission: item.permission,
2132
+ })),
2133
+ ...(input.signal !== undefined ? { signal: input.signal } : {}),
2134
+ })
2135
+
2136
+ if (answer.outcome !== 'allowed-once') {
2137
+ const status = answer.outcome === 'timeout' ? 'timeout' : answer.outcome === 'unavailable' ? 'approval-unavailable' : 'denied'
2138
+ for (const item of pending) {
2139
+ results.push({ scope: item.scope, permission: item.permission, status })
2140
+ }
2141
+ return { results, outcome: answer.outcome, grants: [] }
2142
+ }
2143
+
2144
+ const approved = answer.allowedIds === undefined
2145
+ ? new Set(pending.map((item) => item.id))
2146
+ : new Set(answer.allowedIds)
2147
+ const granted = []
2148
+ for (const item of pending) {
2149
+ if (!approved.has(item.id)) {
2150
+ results.push({ scope: item.scope, permission: item.permission, status: 'denied' })
2151
+ continue
2152
+ }
2153
+ const meta = this.meta.get(item.scope)
2154
+ const grant = this.grants.add(sessionId, {
2155
+ scope: item.scope,
2156
+ permissions: [item.permission],
2157
+ grantedBy: 'user',
2158
+ ...(meta !== undefined ? { scopeGeneration: meta.generation } : {}),
2159
+ })
2160
+ granted.push(grant)
2161
+ this.approvalAudit.append({
2162
+ at: Date.now(),
2163
+ event: 'granted',
2164
+ id: grant.id,
2165
+ sessionId,
2166
+ tool: 'memory_scopes',
2167
+ action: 'grant',
2168
+ mode: 'grant',
2169
+ scopes: [item.scope],
2170
+ permissions: [item.permission],
2171
+ outcome: 'granted',
2172
+ })
2173
+ results.push({ scope: item.scope, permission: item.permission, status: 'granted' })
2174
+ }
2175
+ return { results, outcome: 'allowed-once', grants: granted }
2176
+ }
2177
+
2178
+ /** 面板 / 诊断:当前会话的有效授权(含父会话继承)。 */
2179
+ grantList(agent ) {
2180
+ return this.validGrants(agent)
2181
+ }
2182
+
2183
+ /** 面板:撤销某会话的一条授权。 */
2184
+ revokeGrant(sessionId , id ) {
2185
+ if (typeof sessionId !== 'string' || sessionId === '') return false
2186
+ const before = this.grants.list(sessionId).find((grant) => grant.id === id)
2187
+ const ok = this.grants.revoke(sessionId, id)
2188
+ if (ok) {
2189
+ this.approvalAudit.append({
2190
+ at: Date.now(),
2191
+ event: 'revoked',
2192
+ id,
2193
+ sessionId,
2194
+ tool: 'memory_scopes',
2195
+ action: 'revoke',
2196
+ mode: 'grant',
2197
+ ...(before !== undefined ? { scopes: [before.scope], permissions: before.permissions } : {}),
2198
+ outcome: 'revoked',
2199
+ })
2200
+ }
2201
+ return ok
2202
+ }
2203
+
2204
+ /** 面板 / 诊断:最近的审批与授权事件(不含记忆正文)。 */
2205
+ approvalAuditList(limit = 200) {
2206
+ return this.approvalAudit.list(limit)
2207
+ }
2208
+
1852
2209
  /**
1853
2210
  * 无显式 scope 时的**读取**合并集合:当前会话 + 当前项目 + global(各自开关生效、按 key 去重)。
1854
2211
  * 工具 / 注入都用它。会话设置了「可见范围」时以覆盖为准(不再并入默认集合)。
@@ -1871,16 +2228,19 @@ export class LocalMemoryService {
1871
2228
  * - none:不限制。
1872
2229
  */
1873
2230
  assertOperable(agent , scope ) {
1874
- if (this.isScopeWritable(agent, scope)) return
1875
- const policy = this.visibilityPolicy(agent)
1876
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === this.canonicalScope(scope))
1877
- if (rule !== undefined) {
1878
- throw memoryError('SCOPE_READ_ONLY', `作用域 ${scope} 在本会话记忆范围里被标记为「不可写」(可读/可写按钮),本次写入/删除没有执行。如需写入,请让用户打开该作用域的「可写」状态。`)
2231
+ const decision = this.authorize(agent, { scope, action: 'write' })
2232
+ if (decision.allowed) return
2233
+ switch (decision.reason) {
2234
+ case 'WRITE_DISABLED':
2235
+ throw memoryError('SCOPE_READ_ONLY', `作用域 ${scope} 在本会话记忆范围里被标记为「不可写」(可读/可写按钮),本次写入/删除没有执行。如需写入,请让用户打开该作用域的「可写」状态。`)
2236
+ case 'SCOPE_DISABLED':
2237
+ throw memoryError('SCOPE_DISABLED', `作用域 ${scope} 已被配置关闭,本次写入/删除没有执行。`)
2238
+ case 'ABSOLUTE_ISOLATION':
2239
+ throw memoryError('SCOPE_NOT_WRITABLE', `作用域 ${scope} 不在本会话可见范围内(限制等级:绝对限制),本次写入/删除没有执行。如需写入,请让用户调整「记忆范围」后重试。`)
2240
+ default:
2241
+ // normal 且作用域不在范围内:工具层会先审批,批准后带 visibilityApproved 再来。
2242
+ throw memoryError('VISIBILITY_APPROVAL_REQUIRED', `作用域 ${scope} 不在本会话的可操作范围内,需要用户审批`)
1879
2243
  }
1880
- if (policy.level === 'absolute') {
1881
- throw memoryError('SCOPE_NOT_WRITABLE', `作用域 ${scope} 不在本会话可见范围内(限制等级:绝对限制),本次写入/删除没有执行。如需写入,请让用户调整「记忆范围」后重试。`)
1882
- }
1883
- throw memoryError('VISIBILITY_APPROVAL_REQUIRED', `作用域 ${scope} 不在本会话的可操作范围内,需要用户审批`)
1884
2244
  }
1885
2245
 
1886
2246
  async save(input ) {
@@ -1937,10 +2297,64 @@ export class LocalMemoryService {
1937
2297
  content = redactSecrets(content)
1938
2298
  }
1939
2299
  }
1940
- const { record } = this.store.save(
1941
- { ...saveInput, scope, content },
1942
- { importance: input.source?.origin === 'auto' ? 0.4 : 0.8, source: { origin: 'explicit' } },
1943
- )
2300
+ // 0.24.0:自定义作用域的“创建”与“普通写入”分开判断。
2301
+ // - Agent 新建自定义作用域必须带 scopeDescription(面板 / 导入等无 agent 路径不受限);
2302
+ // - 元数据存在但 status='pending'(上次初始化半途失败)时继续完成初始化;
2303
+ // - 已有作用域带 scopeDescription = 更新用途,不写初始记忆。
2304
+ const initInput = input
2305
+ const description = normalizeScopeDescription(initInput.scopeDescription)
2306
+ const ruleText = typeof initInput.scopeRule === 'string' ? initInput.scopeRule.trim() : ''
2307
+ const metaBefore = this.meta.get(scope)
2308
+ const newCustom = isCustomScope(scope) && this.store.peek(scope) === undefined && metaBefore === undefined
2309
+ const pendingInit = metaBefore?.status === 'pending'
2310
+ const effectiveDescription = description !== '' ? description : (metaBefore?.description ?? '')
2311
+ const agentWrite = saveAgent !== undefined
2312
+ if ((newCustom || pendingInit) && agentWrite && effectiveDescription === '') {
2313
+ throw memoryError(
2314
+ 'SCOPE_DESCRIPTION_REQUIRED',
2315
+ `新建自定义作用域 ${scope} 必须提供 scopeDescription(一句话说明这个作用域用来做什么)。`,
2316
+ )
2317
+ }
2318
+ if (effectiveDescription.length > MAX_SCOPE_DESCRIPTION_CHARS) {
2319
+ throw memoryError('SCOPE_DESCRIPTION_TOO_LONG', `作用域用途最多 ${MAX_SCOPE_DESCRIPTION_CHARS} 字`)
2320
+ }
2321
+ if (ruleText !== '' && ruleText.length > this.cfg.maxRecordChars) {
2322
+ throw memoryError('SCOPE_RULE_TOO_LONG', `scopeRule 超过 ${this.cfg.maxRecordChars} 字`)
2323
+ }
2324
+ const createdBy = agentWrite ? (this.rawSessionIdOf(saveAgent) ?? 'agent') : 'user'
2325
+ const carryInitial = (input ).initial === true
2326
+ const initialized = (newCustom || pendingInit) && effectiveDescription !== ''
2327
+ if (initialized) {
2328
+ // 先落 pending 元数据:进程在写记录途中退出时,下一次保存能识别并重试,
2329
+ // 目录工具也能看到“这个作用域正在初始化”。
2330
+ this.meta.put(scope, { description: effectiveDescription, createdBy, status: 'pending' })
2331
+ } else if (description !== '' && (metaBefore === undefined || description !== metaBefore.description)) {
2332
+ this.meta.put(scope, { description, createdBy: metaBefore?.createdBy ?? createdBy, status: 'ready' })
2333
+ }
2334
+
2335
+ let record
2336
+ try {
2337
+ const saved = this.store.save(
2338
+ { ...saveInput, scope, content, ...(initialized || carryInitial ? { initial: true } : {}) },
2339
+ { importance: input.source?.origin === 'auto' ? 0.4 : 0.8, source: { origin: 'explicit' } },
2340
+ )
2341
+ record = saved.record
2342
+ // 初始规则:只有初始化流程(新作用域 / 半途重试)才写;普通写入带 scopeRule 不生效。
2343
+ if (initialized && ruleText !== '') {
2344
+ const ruleSaved = this.store.save(
2345
+ { ...saveInput, scope, kind: 'rule', content: ruleText, tags: ['scope-init'], initial: true },
2346
+ { importance: 0.8, source: { origin: 'explicit' } },
2347
+ )
2348
+ void this.embedRecord(ruleSaved.record).catch(() => {})
2349
+ }
2350
+ if (initialized) {
2351
+ this.meta.put(scope, { description: effectiveDescription, createdBy: metaBefore?.createdBy ?? createdBy, status: 'ready' })
2352
+ }
2353
+ } catch (error) {
2354
+ // 保留 pending 元数据(而不是删掉):下一次保存可以接着完成初始化,
2355
+ // 目录工具也能明确看到这个作用域尚未就绪。
2356
+ throw error
2357
+ }
1944
2358
  void this.embedRecord(record).catch(() => {})
1945
2359
  this.store.scheduleFlush()
1946
2360
  return record
@@ -2502,6 +2916,10 @@ export class LocalMemoryService {
2502
2916
  ? input.triggers.map(String)
2503
2917
  : (old ).triggers
2504
2918
  if (Array.isArray(triggers)) (next ).triggers = [...triggers]
2919
+ // 编辑初始记录 = 修正该作用域的“自我介绍”,来源标记要跟着走。
2920
+ if ((old ).initial === true) {
2921
+ ;(next ).initial = true
2922
+ }
2505
2923
  if (input.expiresAt === null) {
2506
2924
  // 显式清除:不设置 expiredAt。
2507
2925
  } else if (typeof input.expiresAt === 'number' && Number.isFinite(input.expiresAt)) {
@@ -2536,6 +2954,8 @@ export class LocalMemoryService {
2536
2954
 
2537
2955
                 
2538
2956
 
2957
+                           
2958
+
2539
2959
 
2540
2960
  {
2541
2961
  this.discoverScopes()
@@ -2554,6 +2974,7 @@ export class LocalMemoryService {
2554
2974
  ? { triggers: ((rec ).triggers ).map(String) }
2555
2975
  : {}),
2556
2976
  ...(rec.expiredAt !== undefined ? { expiredAt: rec.expiredAt } : {}),
2977
+ ...((rec ).initial === true ? { initial: true } : {}),
2557
2978
  })
2558
2979
  }
2559
2980
  }
@@ -2582,7 +3003,7 @@ export class LocalMemoryService {
2582
3003
  try {
2583
3004
  const rec = raw
2584
3005
 
2585
-
3006
+
2586
3007
 
2587
3008
  const content = typeof rec.content === 'string' ? rec.content : ''
2588
3009
  if (content.trim().length === 0) throw new Error('content 为空')
@@ -2602,6 +3023,7 @@ export class LocalMemoryService {
2602
3023
  ...(typeof rec.importance === 'number' ? { importance: rec.importance } : {}),
2603
3024
  ...(Array.isArray(rec.triggers) ? { triggers: rec.triggers.map(String) } : {}),
2604
3025
  ...(typeof rec.expiredAt === 'number' && Number.isFinite(rec.expiredAt) ? { expiresAt: rec.expiredAt } : {}),
3026
+ ...(rec.initial === true ? { initial: true } : {}),
2605
3027
  } )
2606
3028
  imported += 1
2607
3029
  } catch (error) {
@@ -2631,6 +3053,27 @@ export class LocalMemoryService {
2631
3053
  return this.names.nameOf(scope)
2632
3054
  }
2633
3055
 
3056
+ /** 作用域用途等元数据(没有则 undefined;调用方按“未填写用途”处理)。 */
3057
+ scopeMeta(scope ) {
3058
+ return this.meta.get(this.canonicalScope(scope))
3059
+ }
3060
+
3061
+ /**
3062
+ * 写入 / 更新作用域用途。**不会**创建记录,也不触发初始化;给面板与
3063
+ * memory_save 的 scopeDescription 补写用。
3064
+ */
3065
+ describeScope(scope , description , by ) {
3066
+ const key = this.canonicalScope(scope)
3067
+ this.assertScopeAllowed(key)
3068
+ this.assertCustomScopeBudget(key)
3069
+ const text = typeof description === 'string' ? description.replace(/\s+/g, ' ').trim() : ''
3070
+ if (text === '') throw memoryError('SCOPE_DESCRIPTION_EMPTY', '作用域用途不能为空')
3071
+ if (text.length > MAX_SCOPE_DESCRIPTION_CHARS) {
3072
+ throw memoryError('SCOPE_DESCRIPTION_TOO_LONG', `作用域用途最多 ${MAX_SCOPE_DESCRIPTION_CHARS} 字`)
3073
+ }
3074
+ return this.meta.put(key, { description: text, createdBy: by, status: 'ready' })
3075
+ }
3076
+
2634
3077
  /** 名字 → 作用域键:读路径允许直接用别名找作用域。 */
2635
3078
  scopeKeyForName(name ) {
2636
3079
  return this.names.scopeOf(name)
@@ -2674,6 +3117,106 @@ export class LocalMemoryService {
2674
3117
  .sort((a, b) => b.updatedAt - a.updatedAt || b.records - a.records || a.scope.localeCompare(b.scope))
2675
3118
  }
2676
3119
 
3120
+ /**
3121
+ * 作用域目录(memory_scopes list / 未来面板的“作用域”页)。
3122
+ *
3123
+ * 与 `scopeStats()` 的区别:这里回答的是“有哪些作用域、各自干什么、我现在能不能
3124
+ * 读/写/申请”,而不是“每个作用域有多少条”。三条语义写死:
3125
+ * - 没有记录但有元数据的作用域也会出现(删光记录不等于作用域消失);
3126
+ * - 关闭的作用域类型(含 `customEnabled=false`)整条不出现;
3127
+ * - `absolute` 下范围外条目的名字/用途仍可见,但 readable/writable/canRequest*
3128
+ * 全为 false —— 目录可见不等于正文可读,且 absolute 没有审批放行路径。
3129
+ */
3130
+ /**
3131
+ * 作用域初始化记录(`initial: true`)的目录视图。只给 normal / none 用;
3132
+ * absolute 由调用方跳过。正文截断到 800 字,每个作用域最多 3 条。
3133
+ */
3134
+ initialRecordsOf(scope ) {
3135
+ const store = this.store.peek(scope)
3136
+ if (store === undefined) return undefined
3137
+ const out = []
3138
+ for (const record of store.records.values()) {
3139
+ if ((record ).initial !== true) continue
3140
+ const content = record.content.trim()
3141
+ out.push({
3142
+ id: record.id,
3143
+ kind: record.kind,
3144
+ content: content.length > 800 ? `${content.slice(0, 800)}…` : content,
3145
+ ...(content.length > 800 ? { truncated: true } : {}),
3146
+ })
3147
+ if (out.length >= 3) break
3148
+ }
3149
+ return out.length > 0 ? out : undefined
3150
+ }
3151
+
3152
+ scopeCatalog(agent ) {
3153
+ const policy = this.visibilityPolicy(agent)
3154
+ const stats = new Map(this.scopeStats().map((item) => [this.canonicalScope(item.scope), item]))
3155
+ const metas = new Map(this.meta.list().map((item) => [this.canonicalScope(item.scope), item]))
3156
+ const keys = new Set ()
3157
+ for (const scope of this.baseDefaultScopes(agent)) keys.add(this.canonicalScope(scope))
3158
+ for (const scope of this.bindings.get(this.workspaceKeyFor(agent))) keys.add(this.canonicalScope(scope))
3159
+ for (const scope of stats.keys()) keys.add(this.canonicalScope(scope))
3160
+ for (const scope of metas.keys()) keys.add(scope)
3161
+
3162
+ const out = []
3163
+ const evaluate = this.accessEvaluator(agent)
3164
+ for (const scope of keys) {
3165
+ // 目录发现本身也是一条授权判定:作用域类型被关闭时连名字/用途都不出现。
3166
+ if (!evaluate({ scope, action: 'discover' }).allowed) continue
3167
+ const meta = metas.get(scope)
3168
+ const stat = stats.get(scope)
3169
+ const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === scope)
3170
+ const inScope = policy.level === 'none' || rule !== undefined
3171
+ // 别的会话的 session scope 默认不进目录:它们没有用途、也不该被 Agent 主动申请,
3172
+ // 全列出来只会把目录变成历史会话列表。有元数据(被人描述过)则保留。
3173
+ if (!inScope && meta === undefined && scopeKind(scope) === 'session') continue
3174
+ const readDecision = evaluate({ scope, action: 'read' })
3175
+ const writeDecision = evaluate({ scope, action: 'write' })
3176
+ const readable = readDecision.allowed
3177
+ const writable = writeDecision.allowed
3178
+ // 只有“整个作用域不在范围内”(SCOPE_NOT_IN_RANGE)才可申请;absolute 与
3179
+ // 用户显式关掉的 read/write 都不会 requestable。
3180
+ const canRequestRead = !readable && readDecision.requestable
3181
+ const canRequestWrite = !writable && writeDecision.requestable
3182
+ const accessStatus = !inScope
3183
+ // 范围外但已有会话授权:如实显示“可读 / 可写”,而不是继续标 restricted。
3184
+ ? readable && writable
3185
+ ? 'read-write'
3186
+ : readable
3187
+ ? 'read-only'
3188
+ : 'restricted'
3189
+ : policy.source === 'default'
3190
+ ? 'default'
3191
+ : readable && writable
3192
+ ? 'read-write'
3193
+ : readable
3194
+ ? 'read-only'
3195
+ : 'restricted'
3196
+ const name = meta?.name ?? this.names.nameOf(scope)
3197
+ const initialRecords = policy.level === 'absolute' ? undefined : this.initialRecordsOf(scope)
3198
+ out.push({
3199
+ scope,
3200
+ ...(name !== undefined ? { name } : {}),
3201
+ ...(meta !== undefined ? { description: meta.description } : {}),
3202
+ origin: meta?.origin ?? scopeKind(scope),
3203
+ ...(inScope ? { records: stat?.records ?? 0 } : {}),
3204
+ inScope,
3205
+ readable,
3206
+ writable,
3207
+ canRequestRead,
3208
+ canRequestWrite,
3209
+ accessStatus,
3210
+ updatedAt: stat?.updatedAt ?? meta?.updatedAt ?? 0,
3211
+ ...(initialRecords !== undefined ? { initialRecords } : {}),
3212
+ })
3213
+ }
3214
+ return out.sort((a, b) => Number(b.inScope) - Number(a.inScope)
3215
+ || (b.records ?? 0) - (a.records ?? 0)
3216
+ || b.updatedAt - a.updatedAt
3217
+ || a.scope.localeCompare(b.scope))
3218
+ }
3219
+
2677
3220
  /**
2678
3221
  * 发现磁盘上的 scope(带时间缓存)。面板每次 /status、每次 memory_list 都要一份完整
2679
3222
  * 清单,而 discovery 要读每个文件的第一条记录 —— 限流到最短 3 秒一次,既保证清单够新,
@@ -2863,6 +3406,11 @@ function memoryError(code , message ) {
2863
3406
  return err
2864
3407
  }
2865
3408
 
3409
+ /** 作用域用途统一成一行(与工具的 description 同款收敛口径)。 */
3410
+ function normalizeScopeDescription(raw ) {
3411
+ return typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim() : ''
3412
+ }
3413
+
2866
3414
  /** discoverScopes() 的最短间隔:清单要够新,但 projects/ 目录不该被读成热路径。 */
2867
3415
  const DISCOVER_TTL_MS = 3000
2868
3416