@try-works/dsh-memory 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@try-works/dsh-memory",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Git-backed, workspace-scoped memory for the DeepSeek Harness (global layer + per-workspace layers)",
   "type": "module",
   "main": "src/index.js",

package/src/client/index.js

@@ -342,59 +342,213 @@ window.__ModuleLoader__.load({
     /**
      * The Memory tab: this session's memory activity, in one place.
      *
-     * Its data is the most recent memory_map result in this session. That is not a
+     * Its data is the most recent memory_map result of this conversation. That is not a
      * convenience: a browser half cannot ask the host for anything, so the session record is
-     * the only channel, and a tool result carries its structured value on `meta` (ui-chat's
-     * conversation-nodes/tool.ts does `meta: match.event.data.meta`).
+     * the only channel, and a tool result carries its structured value on `meta` - the very
+     * object ui-chat's conversation-nodes/tool.ts forwards as `meta: match.event.data.meta`.
      *
-     * READING IT: a conversation view gets data through a registered standard hook, so the
-     * plugin provides `memoryMap` via ctx.uiSession.provide and this component receives
-     * `useMemoryMap` as a prop, the way ui-tool's rows receive their history hook. The hook
-     * resolves by scanning the Trajectory target's event nodes for a settled memory_map tool
-     * call; the Trajectory target is the shipped assembly of this session's nodes, and its
-     * snapshot contract is eventNodes: ConversationNode[] with { kind: 'tool', root }.
+     * READING IT: the session's contiguous event window is published as the documented
+     * public member SessionBinding.eventSource (ObservableSnapshot<SessionEventWindow>, see
+     * api/session-controller/src/client/contract/events.ts), reached through
+     * ctx.sessions.binding(sessionId). That is the same source the Chat and Trajectory tabs
+     * are assembled from, so the tab adds no new channel and cannot disagree with them.
+     * Sessions is reached with ctx.get() because it is a reachable service, not a required
+     * one: making it an inject dependency would hold the whole plugin - Settings included -
+     * pending behind a service the settings page does not need.
      */
-    function findMemorySnapshot(snapshot) {
-      if (!snapshot || !Array.isArray(snapshot.eventNodes)) return null
+    const MEMORY_STATE_NONE = { kind: 'none', meta: null, seq: null, time: null }
+    const MEMORY_STATE_UNAVAILABLE = { kind: 'unavailable', meta: null, seq: null, time: null }
+    // Distinct from NONE on purpose. PTC mode dispatches a tool from inside a run_code program and
+    // records tool/ptc-dispatch, which carries the rendered text but NO structured value, so there
+    // is genuinely nothing to draw - and telling the reader 'memory_map has not run here' would be
+    // false.
+    const MEMORY_STATE_NESTED = { kind: 'nested', meta: null, seq: null, time: null }
+
+    /**
+     * Find the newest memory_map result in the window and say what it carried.
+     *
+     * A tool/result event names its call only by id, so the call events are indexed first.
+     * A result whose tool/call pair has been paged out or pruned is still recognised by the
+     * shape of its own value: nothing but memory_map produces { scope, generatedAt }.
+     */
+    function readMemoryState(window) {
+      const entries = window && Array.isArray(window.entries) ? window.entries : null
+      if (!entries) return MEMORY_STATE_NONE
+      const calls = Object.create(null)
+      let nested = false
+      for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i]
+        const event = entry && entry.type === 'event' ? entry.event : null
+        if (event && event.type === 'tool/call' && event.data && event.data.name === 'memory_map') calls[event.data.callId] = true
+        // A nested dispatch is a real call the agent made; it simply has no structured result.
+        if (event && event.type === 'tool/ptc-dispatch' && event.data && event.data.name === 'memory_map') nested = true
+      }
       // Newest first: the tab describes the session as it stands now, not as it first was.
-      for (let i = snapshot.eventNodes.length - 1; i >= 0; i -= 1) {
-        const node = snapshot.eventNodes[i]
-        const root = node && node.kind === 'tool' ? node.root : null
-        if (!root || root.isError) continue
-        const name = root.call && root.call.name
-        if (name !== 'memory_map') continue
-        if (root.meta && typeof root.meta === 'object') return root.meta
+      for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i]
+        const event = entry && entry.type === 'event' ? entry.event : null
+        if (!event || event.type !== 'tool/result') continue
+        const data = event.data || {}
+        const message = data.message || null
+        const callId = message && message.source ? message.source.callId : undefined
+        const meta = data.meta
+        const shaped = meta !== null && typeof meta === 'object'
+          && typeof meta.generatedAt === 'string' && typeof meta.scope === 'string'
+        if (calls[callId] !== true && !shaped) continue
+        // A failed call is not a snapshot: it is the absence of one, and it is said so.
+        if (message && message.isError === true) continue
+        if (meta === null || typeof meta !== 'object') return { kind: 'empty', meta: null, seq: event.seq, time: event.time }
+        return { kind: 'ready', meta: meta, seq: event.seq, time: event.time }
       }
-      return null
+      return nested ? MEMORY_STATE_NESTED : MEMORY_STATE_NONE
     }
 
-    function MemoryTabView(props) {
-      const useMemoryMap = props ? props.useMemoryMap : null
-      const meta = typeof useMemoryMap === 'function' ? useMemoryMap() : null
-      const page = { padding: '32px 28px 0 28px', display: 'flex', flexDirection: 'column', gap: '0' }
-      if (!meta) {
-        // Nothing to draw yet, and saying so beats drawing an empty chart that reads as zero.
-        const empty = { display: 'flex', flexDirection: 'column', gap: '10px', maxWidth: '520px' }
-        return box(page, [box(empty, [
-          react.createElement('div', { key: 'h', style: { fontFamily: GEIST, fontSize: '15px', fontWeight: 500, color: INK } }, 'No memory snapshot in this session yet'),
-          react.createElement('div', { key: 'p', style: { fontFamily: GEIST, fontSize: '13px', lineHeight: 1.6, color: MUTED } }, 'This tab shows what memory put in front of this conversation, what the conversation wrote back, and the state of the store. It fills in once memory_map runs in this session.'),
-        ])]);
+    /**
+     * The tab's observable source over one session's event window.
+     *
+     * It re-resolves the binding on every read, so a session whose binding materializes
+     * after the tab has already rendered still fills in; while no window exists it listens
+     * to the session list, which publishes when a generation is retained or opened, so the
+     * tab wakes up instead of staying dark until an unrelated re-render. Values are cached by
+     * window identity, which keeps getSnapshot referentially stable between publications.
+     */
+    function createMemorySource(ctx, sessionId) {
+      const listeners = []
+      let subscribedTo = null
+      let unsubscribe = null
+      let cachedWindow = null
+      let cachedState = MEMORY_STATE_NONE
+      const wake = () => {
+        cachedWindow = null
+        for (let i = 0; i < listeners.length; i += 1) listeners[i]()
+      }
+      const eventSourceOf = () => {
+        const sessions = ctx.get('sessions')
+        if (!sessions || typeof sessions.binding !== 'function') return null
+        const binding = sessions.binding(sessionId)
+        return binding && binding.eventSource ? binding.eventSource : null
+      }
+      const attach = (source) => {
+        if (unsubscribe) { unsubscribe(); unsubscribe = null }
+        subscribedTo = source
+        if (source) { unsubscribe = source.subscribe(wake); return }
+        const sessions = ctx.get('sessions')
+        const list = sessions && sessions.list
+        if (list && typeof list.subscribe === 'function' && listeners.length) unsubscribe = list.subscribe(wake)
+      }
+      const sync = () => {
+        const source = eventSourceOf()
+        if (listeners.length) { if (source !== subscribedTo) attach(source) }
+        else if (subscribedTo) attach(null)
+        return source
+      }
+      return {
+        getSnapshot: () => {
+          const source = sync()
+          if (!source) return MEMORY_STATE_UNAVAILABLE
+          const window = source.getSnapshot()
+          if (window !== cachedWindow) { cachedWindow = window; cachedState = readMemoryState(window) }
+          return cachedState
+        },
+        subscribe: (listener) => {
+          listeners.push(listener)
+          sync()
+          return () => {
+            const index = listeners.indexOf(listener)
+            if (index >= 0) listeners.splice(index, 1)
+            if (!listeners.length) attach(null)
+          }
+        },
+      }
+    }
+
+    /** Selector for the injected memory hook: the source caches by window, so identity holds. */
+    function memoryStateOf(value) { return value === undefined ? MEMORY_STATE_NONE : value }
+
+    /** The sheet the panels sit on: their ink colours are fixed, so the surface must be too. */
+    function sheet(key, children) {
+      return box({ key: key, border: '1px solid #E7E7E4', borderRadius: '12px', background: '#FFFFFF', padding: '16px', display: 'flex', flexDirection: 'column', gap: '14px' }, children)
+    }
+
+    /** The snapshot's OWN stamp, never the clock: a snapshot taken an hour ago must read so. */
+    function whenText(iso) {
+      const at = new Date(iso)
+      return Number.isNaN(at.getTime()) ? String(iso) : at.toLocaleString()
+    }
+
+    /**
+     * What the tab says when there is nothing to draw.
+     *
+     * The distinctions matter: 'this session never ran memory_map' and 'the call ran but its
+     * result carries no snapshot' are different facts, and neither of them is zero entries.
+     */
+    function emptyMemoryCopy(state) {
+      if (state.kind === 'unavailable') {
+        return {
+          title: 'The session record is not attached yet',
+          lines: [
+            'This tab reads memory from the conversation it belongs to - the event window of the open session - and that window is not available here.',
+            'Settings, Memory still reads the live store through the host, so the store itself stays visible either way.',
+          ],
+        }
       }
+      if (state.kind === 'empty') {
+        return {
+          title: 'The last memory_map result carried no snapshot',
+          lines: [
+            'The call is part of this session, but no structured value is attached to its result: a call that failed, or one whose result was replaced while the context was compacted.',
+            'Running memory_map again puts a fresh snapshot here.',
+          ],
+        }
+      }
+      if (state.kind === 'nested') {
+        return {
+          title: 'memory_map ran here, but not as a readable result',
+          lines: [
+            'This session called memory_map from inside a run_code program. Those calls are recorded as nested dispatches, which keep the rendered text and not the structured value this tab draws.',
+            'Calling memory_map directly - scope "session" or "all" - records a result the panels can read.',
+          ],
+        }
+      }
+      return {
+        title: 'No memory_map result in this session yet',
+        lines: [
+          'This tab draws the most recent memory_map result of this conversation: the same snapshot the agent was shown, read back from the session record rather than fetched again.',
+          'Run memory_map once - scope "session" or "all" - and the panels appear here.',
+        ],
+      }
+    }
+
+    /** The honest empty state: prose that says what is missing, never a shape that reads as data. */
+    function MemoryEmpty(props) {
+      const copy = emptyMemoryCopy(props.state)
+      const lines = copy.lines.map(function (line, index) {
+        return react.createElement('div', { key: String(index), style: { fontFamily: GEIST, fontSize: '12px', lineHeight: 1.6, color: MUTED } }, line)
+      })
+      return sheet('empty', [
+        react.createElement('div', { key: 't', style: { fontFamily: GEIST, fontSize: '13px', fontWeight: 500, color: INK } }, copy.title),
+        box({ key: 'b', display: 'flex', flexDirection: 'column', gap: '8px' }, lines),
+      ])
+    }
+
+    /** The panels, drawn from the snapshot memory_map actually returned and nothing else. */
+    function MemoryPanels(props) {
+      const meta = props.meta
       const store = meta.store || null
       const session = meta.session || null
       const parts = []
-      if (session) {
-        const who = session.workspace ? 'workspace ' + session.workspace : 'global layer'
-        parts.push(react.createElement('div', { key: 'id', style: { fontFamily: GEIST, fontSize: '13px', color: '#3A3A38', paddingBottom: '26px' } }, 'This session · ' + who));
-        if (session.received) parts.push(box({ key: 'r', display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '460px' }, [react.createElement(ReceivedPanel, { key: 'p', received: session.received })]));
-        if (session.written) parts.push(box({ key: 'w', marginTop: '34px', paddingTop: '26px', borderTop: '1px solid ' + LINE, display: 'flex', flexDirection: 'column' }, [react.createElement(WrittenPanel, { key: 'p', written: session.written })]));
-      }
+      const chips = [react.createElement(Chip, { key: 'scope', text: 'scope ' + String(meta.scope) })]
+      if (meta.generatedAt) chips.push(react.createElement(Chip, { key: 'at', text: whenText(meta.generatedAt) }))
+      if (session) chips.push(react.createElement(Chip, { key: 'where', text: session.workspace ? 'workspace ' + session.workspace : 'global layer' }))
+      parts.push(box({ key: 'chips', display: 'flex', gap: '5px', flexWrap: 'wrap' }, chips))
       if (store) {
         const attention = (store.queue && store.queue.attention) || []
-        const chips = attention.slice(0, 3).map(function (row) { return react.createElement(Chip, { key: row.state + row.reason, text: fmt(row.count) + ' ' + row.state, hot: true }) });
-        if (store.queue && store.queue.waiting) chips.push(react.createElement(Chip, { key: 'waiting', text: fmt(store.queue.waiting) + ' waiting' }));
-        parts.push(box({ key: 's', marginTop: '34px', paddingTop: '26px', borderTop: '1px solid ' + LINE, display: 'flex', flexDirection: 'column', gap: '15px' }, [
-          sectionLabel('SNAPSHOT', fmt(store.total) + ' entries · ' + fmt(store.scopeTotal) + ' scopes'),
+        const queue = attention.slice(0, 3).map(function (row) {
+          return react.createElement(Chip, { key: row.state + row.reason, text: fmt(row.count) + ' ' + row.state, hot: true })
+        })
+        if (store.queue && store.queue.waiting) queue.push(react.createElement(Chip, { key: 'waiting', text: fmt(store.queue.waiting) + ' waiting' }))
+        parts.push(sheet('store', [
+          sectionLabel('STORE', fmt(store.total) + ' entries · ' + fmt(store.scopeTotal) + ' scopes'),
           react.createElement(LayerBar, { key: 'bar', layers: store.layers, height: '30px' }),
           react.createElement(Legend, { key: 'leg', layers: store.layers }),
           box({ key: 'f', display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '16px' }, [
@@ -403,12 +557,62 @@ window.__ModuleLoader__.load({
               store.freshness.stale ? react.createElement(Stat, { key: 'b', value: fmt(store.freshness.stale), label: 'stale', color: RUST }) : null,
               store.freshness.skip ? react.createElement(Stat, { key: 'c', value: fmt(store.freshness.skip), label: 'superseded' }) : null,
             ]),
-            box({ key: 'q', display: 'flex', gap: '5px', flexWrap: 'wrap' }, chips),
+            box({ key: 'q', display: 'flex', gap: '5px', flexWrap: 'wrap' }, queue),
           ]),
-        ]));
+        ]))
+      }
+      // A panel with nothing in it is omitted, or said in one line of prose: an empty card is
+      // a shape that reads as data, which is exactly what this tab must never draw.
+      const received = session ? session.received : null
+      if (received && received.sections && received.sections.length) {
+        parts.push(sheet('received', [react.createElement(ReceivedPanel, { key: 'r', received: received })]))
+      }
+      const written = session ? session.written : null
+      if (written && written.total) {
+        parts.push(sheet('written', [react.createElement(WrittenPanel, { key: 'w', written: written })]))
+      } else if (written) {
+        parts.push(react.createElement('div', {
+          key: 'none',
+          style: { fontFamily: GEIST, fontSize: '12px', color: 'var(--dsw-alias-label-tertiary)' },
+        }, 'This session has not recorded an entry yet.'))
       }
-      return box(page, parts);
+      parts.push(react.createElement('div', {
+        key: 'src',
+        style: { fontFamily: GEIST, fontSize: '11px', color: 'var(--dsw-alias-label-tertiary)', lineHeight: 1.6 },
+      }, 'Read from this session\u2019s most recent memory_map result (event #' + fmt(props.seq) + '), not re-read from the store. Run memory_map again to refresh it.'))
+      return box({ display: 'flex', flexDirection: 'column', gap: '18px' }, parts)
+    }
+
+    /**
+     * The Memory tab.
+     *
+     * The hook arrives as part of this entry's injected standard kit: the inject face
+     * publishes hooks.memory, which the renderer binds to a useMemory prop, exactly as
+     * ui-trajectory's view receives useDuration. It is present for the whole life of a mount
+     * or absent for the whole of it, so this branch never changes hook order. The selector is
+     * required: the bound hook is a selector hook and calls it without a guard.
+     */
+    function MemoryTabView(props) {
+      const useMemory = props && typeof props.useMemory === 'function' ? props.useMemory : null
+      const state = useMemory ? useMemory(memoryStateOf) : MEMORY_STATE_NONE
+      const page = { flex: '1 1 auto', minHeight: 0, overflowY: 'auto' }
+      const inner = { maxWidth: '760px', margin: '0 auto', padding: '26px 28px 44px', display: 'flex', flexDirection: 'column', gap: '18px' }
+      const head = box({ display: 'flex', alignItems: 'center', gap: '10px' }, [
+        react.createElement(Glyph, { key: 'g' }),
+        // Theme token, not the fixed ink palette: this line sits on the shell background,
+        // which the palette knows nothing about.
+        react.createElement('div', { key: 't', style: { fontFamily: GEIST, fontSize: '15px', fontWeight: 500, color: 'var(--dsw-alias-label-primary)' } }, 'Memory'),
+      ])
+      const intro = react.createElement('div', {
+        key: 'i',
+        style: { fontFamily: GEIST, fontSize: '12px', lineHeight: 1.6, color: 'var(--dsw-alias-label-tertiary)' },
+      }, 'What memory put in front of this conversation, what the conversation wrote back, and the state of the store.')
+      const body = state.kind === 'ready'
+        ? react.createElement(MemoryPanels, { key: 'p', meta: state.meta, seq: state.seq })
+        : react.createElement(MemoryEmpty, { key: 'e', state: state })
+      return box(page, [box(inner, [head, intro, body])])
     }
+
     /** Fields rendered on this page, in order. */
     const FIELDS = [
       { key: 'memoryRoot', label: 'Memory root', hint: 'Local folder or drive that holds the store.', placeholder: 'D:\\Memory' },
@@ -628,25 +832,11 @@ window.__ModuleLoader__.load({
           order: 80,
           label: 'Memory',
         }, () => react.createElement(MemorySettings))))
-        // The Memory tab. Data arrives through a registered standard hook, because a
-        // conversation view is a slot and slots are fed by hooks, not by direct reads.
-        // The Trajectory target is the shipped assembly of this session's nodes, so the
-        // source re-derives the memory snapshot from it on every projection.
+        // The Memory tab. Its data is injected by THIS entry rather than registered globally
+        // through uiSession.provide: the source is per-session and read from the session's own
+        // event window, and an entry-owned inject face is cached per (entry x session), so the
+        // hook the renderer binds (useMemory) is created once per conversation.
         try {
-          ctx.effect(() => ctx.uiSession.provide({
-            hooks: ['memoryMap'],
-            resolve: (binding) => {
-              const target = ctx.uiConversation.binding(binding).target('trajectory')
-              return {
-                hooks: {
-                  memoryMap: {
-                    getSnapshot: () => findMemorySnapshot(target.getSnapshot()),
-                    subscribe: (listener) => target.subscribe(listener),
-                  },
-                },
-              }
-            },
-          }), 'dsh-memory: memory map hook')
           disposers.push(ctx.slots.inject('conversation.view', () => ctx.slots.register({
             name: 'conversation.view',
             id: 'memory',
@@ -654,6 +844,7 @@ window.__ModuleLoader__.load({
             // reordering anyone else's tab.
             order: 20,
             label: 'Memory',
+            inject: (sessionId) => ({ hooks: { memory: createMemorySource(ctx, sessionId) } }),
           }, MemoryTabView)))
         } catch (error) {
           // Loud, not silent. A tab that fails to register is invisible by definition, so this
@@ -665,7 +856,9 @@ window.__ModuleLoader__.load({
     }
 
     exports.name = 'dsh-memory'
-    exports.inject = ['slots', 'configForms', 'remote.session', 'uiSession', 'uiConversation']
+    // 'sessions' is deliberately NOT here: the tab reaches it with ctx.get() so that a
+    // missing service can only blank the tab, never hold back the settings page too.
+    exports.inject = ['slots', 'configForms', 'remote.session']
     exports.apply = apply
     return module.exports
   },