dsh-hypatia-auto-memory 2.0.0 → 2.1.0

package/src/index.js

@@ -11,6 +11,8 @@
  *     ├─ recall      (inject agents)          — rules/taboos preload at session start
  *     ├─ housekeeping (inject sessionPersistence) — prune progress of vanished sessions
  *     ├─ memory-api  (inject webServer)       — the Memory tab + shelf listing routes
+ *     ├─ on-demand   (inject commands)        — /hypatia-summarize, no model turn
+ *     ├─ on-demand   (inject tools)           — the hypatia_summarize tool
  *     ├─ auto-approve (inject approval, tools) — the agent's own bash `hypatia` calls
  *     └─ skills      (inject skills)          — hypatia-memory, hypatia, hypatia-dream
  *
@@ -38,6 +40,14 @@ import { TaskDeferredError, createQueue } from './queue.js'
 import { countLoggableMessages, createCollector, formatSpan } from './collector.js'
 import { createCascade } from './cascade.js'
 import { createConsolidator, PLUGIN_NAME } from './consolidator.js'
+import {
+  SUMMARIZE_COMMAND,
+  SUMMARIZE_TOOL,
+  disabledOutcome,
+  registerSummarizeCommand,
+  registerSummarizeTool,
+  unavailableOutcome,
+} from './on-demand.js'
 import { openModelLog } from './model-log.js'
 import { createReasoningResolver } from './reasoning.js'
 import { buildStatus } from './memory-status.js'
@@ -126,17 +136,18 @@ function applyCollect(ctx, configHandle, status) {
   })
 
   /**
-   * The Memory tab's read side and the settings card's shelf listing.
+   * The Memory tab's read side and the settings card's shelf listing, plus the
+   * one write route an explicit "summarise now" rides.
    * Optional: it needs `webServer`, so a headless or TUI composition simply has
    * no Memory tab and nothing else changes. The route authenticates itself —
    * see memory-api.js.
    */
-  function mountMemoryApi({ cli, read, shared }) {
+  function mountMemoryApi({ cli, read, shared, summarize }) {
     ctx.plugin({
       name: `${name}/memory-api`,
       inject: ['webServer'],
       apply: (c) => {
-        const api = createMemoryApi({ cli, read, status })
+        const api = createMemoryApi({ cli, read, status, summarize })
         c.effect(() => {
           const unregister = c.webServer.register(api.route)
           shared.memoryApi = api
@@ -166,6 +177,9 @@ function applyCollect(ctx, configHandle, status) {
         }),
         read: (sessionId) => buildStatus({ progressEntries: [], taskEntries: [], sessionId }),
         shared: {},
+        // No state is being written while the plugin is off, so the route
+        // answers with the truth rather than an empty span.
+        summarize: disabledOutcome,
       })
       return
     }
@@ -263,6 +277,20 @@ function applyCollect(ctx, configHandle, status) {
     // needs `webServer`, and a headless composition has none.
     const shared = { consolidator: undefined, memoryApi: undefined }
 
+    /**
+     * The one function all three explicit faces call: the slash command, the
+     * tool, and the Memory tab's button. Late-bound like the rest of `shared`,
+     * because the consolidator only exists once `llm` arrives; before that (or
+     * in a composition without `llm` at all) the request is answered honestly
+     * as unavailable rather than silently dropped.
+     *
+     * @param {string} sessionId
+     * @returns {Promise<{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number}>}
+     */
+    const summarizeNow = (sessionId) => shared.consolidator === undefined
+      ? Promise.resolve(unavailableOutcome(sessionId))
+      : shared.consolidator.consolidateNow(sessionId)
+
     // Mounted before reconcile and backfill, which can take long or fail: the
     // settings card's shelf listing rides this route family, and a broken
     // shelf is exactly when the user needs it.
@@ -274,6 +302,7 @@ function applyCollect(ctx, configHandle, status) {
         sessionId,
       }),
       shared,
+      summarize: summarizeNow,
     })
 
     const writer = createWriter(cli, {
@@ -526,6 +555,30 @@ function applyCollect(ctx, configHandle, status) {
       },
     })
 
+    // The two Host-side faces of an explicit "summarise this session now".
+    //
+    // Separate fibers on purpose: `commands` is absent from a headless or TUI
+    // composition while `tools` is present, and one fiber injecting both would
+    // take the tool down with the missing command registry. Neither is mounted
+    // under `auto-approve`, which exists only when `autoApprove !== false` and
+    // has nothing to do with this — the tool is a first-class action, not a
+    // shell call to approve.
+    //
+    // Both read `summarizeNow` at invocation time, so registering them before
+    // the consolidate fiber settles is fine; a request that arrives before a
+    // route exists is answered as unavailable instead of silently dropped.
+    ctx.inject(['commands'], (commandCtx) => {
+      try {
+        registerSummarizeCommand(commandCtx, { run: summarizeNow, status })
+      } catch (error) {
+        status.warn(`/${SUMMARIZE_COMMAND} could not be registered: ${String(error)}`)
+      }
+    })
+    ctx.inject(['tools'], (toolCtx) => {
+      void registerSummarizeTool(toolCtx, { run: summarizeNow, status })
+        .catch((error) => status.warn(`the ${SUMMARIZE_TOOL} tool could not be registered: ${String(error)}`))
+    })
+
     ctx.plugin({
       name: `${name}/recall`,
       inject: ['agents'],

package/src/memory-api.js

@@ -1,5 +1,6 @@
 /**
- * The Memory tab's read-only HTTP route family.
+ * The Memory tab's HTTP route family: the read side the tab is built on, plus
+ * one write route for an explicit "summarise this session now".
  *
  * Why a route and not a settings namespace. The tab needs two different things
  * from the Host: a small per-session status that changes whenever a task
@@ -36,6 +37,20 @@
  * claim; the loopback socket is what actually bounds reachability, and the other
  * two narrow it to this page.
  *
+ * ### Why a WRITE route is allowed to live here
+ *
+ * `POST /consolidate` is the family's first route that causes work, so it is
+ * worth stating why the three checks above are still enough. It writes nothing
+ * itself: it queues the same consolidation task the automatic trigger queues,
+ * through the same function, on the same durable queue. It cannot choose what
+ * is written (the range comes from the Host's own watermarks), cannot name an
+ * entry, and cannot reach beyond the shelf the profile selected. What a hostile
+ * page could do, if it got past the checks, is cause summarisation the user did
+ * not ask for — so the checks are kept exactly as they were, and the write
+ * route is only reachable from a same-origin page on this loopback GUI. Every
+ * route in the family, read or write, calls `isTrustedRequest` first; the write
+ * route adds a method gate (`POST` only) on top.
+ *
  * ## What it will not return
  *
  * Summaries and work units are distilled knowledge, so their bodies are served —
@@ -383,13 +398,21 @@ export function fitBudget(entries, spent = 0) {
  *   cli: {query: (jse: string) => Promise<any>, listShelves: () => Promise<{name: string, path: string, connected: boolean}[]>},
  *   read: (sessionId: string) => {sessions: object[], failed: object[]},
  *   status: import('./status.js').StatusLog,
+ *   summarize?: (sessionId: string) => Promise<{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number}>,
  *   ttlMs?: number,
  *   shelvesTtlMs?: number,
  *   now?: () => number,
- * }} deps - `read` folds the state tables for one session (see memory-status.js).
+ * }} deps - `read` folds the state tables for one session (see memory-status.js);
+ *   `summarize` is the same host action the slash command and the tool call
+ *   (see on-demand.js). Absent, the write route answers 503: a composition
+ *   without a consolidator cannot consolidate, and saying so is better than
+ *   pretending to queue.
  * @returns {{route: {kind: string, path: string, handler: Function}, invalidate: (sessionId?: string) => void, fetchContent: (sessionId: string, watermark?: number) => Promise<object>, fetchShelves: () => Promise<object>}}
  */
-export function createMemoryApi({ cli, read, status, ttlMs = CONTENT_TTL_MS, shelvesTtlMs = SHELVES_TTL_MS, now = Date.now }) {
+export function createMemoryApi({
+  cli, read, status, summarize,
+  ttlMs = CONTENT_TTL_MS, shelvesTtlMs = SHELVES_TTL_MS, now = Date.now,
+}) {
   /** @type {Map<string, {at: number, watermark: number | undefined, value: object}>} */
   const cache = new Map()
   /**
@@ -570,15 +593,49 @@ export function createMemoryApi({ cli, read, status, ttlMs = CONTENT_TTL_MS, she
     writeJson(res, 200, payload)
   }
 
+  /**
+   * Queue an explicit consolidation for one session.
+   *
+   * `POST` only, because a write must never be triggerable by a link or an
+   * `<img>`: a browser sends neither for a POST, and the same-origin check
+   * refuses a cross-site one that a form could send. The body is not read —
+   * the request carries its whole meaning in the session parameter — so there
+   * is nothing here for a malformed payload to corrupt.
+   */
+  async function handleConsolidate(req, res, query) {
+    const sessionId = query.get('session') ?? ''
+    if (sessionId === '') {
+      writeJson(res, 400, { error: 'the session query parameter is required' })
+      return
+    }
+    // Same shape guard as the read route: a session id is hex, dashes and the
+    // `session-` prefix, so this refuses only values that could not be one.
+    if (/[%\\]/.test(sessionId)) {
+      writeJson(res, 400, { error: 'malformed session id' })
+      return
+    }
+    if (summarize === undefined) {
+      writeJson(res, 503, { error: 'consolidation is not available in this composition' })
+      return
+    }
+    try {
+      // Always 200 for an outcome the action itself produced — including
+      // "nothing to do" and "already queued". They are answers, not failures,
+      // and the tab renders the reason; a 4xx would turn the truthful answer
+      // into an error banner.
+      writeJson(res, 200, await summarize(sessionId))
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      status.warn(`consolidation request failed for ${sessionId}: ${message}`)
+      writeJson(res, 500, { error: message })
+    }
+  }
+
   async function handler(req, res) {
     if (!isTrustedRequest(req)) {
       writeJson(res, 403, { error: 'forbidden' })
       return
     }
-    if ((req.method ?? 'GET') !== 'GET') {
-      writeJson(res, 405, { error: 'method not allowed' })
-      return
-    }
     let url
     try {
       // The base is a placeholder: only the pathname and search are read.
@@ -587,15 +644,32 @@ export function createMemoryApi({ cli, read, status, ttlMs = CONTENT_TTL_MS, she
       writeJson(res, 400, { error: 'malformed request url' })
       return
     }
+    const method = req.method ?? 'GET'
     const path = url.pathname.slice(MEMORY_API_PREFIX.length)
     if (path === '/shelves') {
+      if (method !== 'GET') {
+        writeJson(res, 405, { error: 'method not allowed' })
+        return
+      }
       writeJson(res, 200, await fetchShelves())
       return
     }
+    if (path === '/consolidate') {
+      if (method !== 'POST') {
+        writeJson(res, 405, { error: 'method not allowed' })
+        return
+      }
+      await handleConsolidate(req, res, url.searchParams)
+      return
+    }
     if (path !== '/session') {
       writeJson(res, 404, { error: 'not found' })
       return
     }
+    if (method !== 'GET') {
+      writeJson(res, 405, { error: 'method not allowed' })
+      return
+    }
     await handleSession(req, res, url.searchParams)
   }
 

package/src/on-demand.js

@@ -0,0 +1,249 @@
+/**
+ * On-demand consolidation: the two surfaces a user drives directly.
+ *
+ * The plugin writes memory in the background, on thresholds. That is the right
+ * default and the wrong answer when a reader wants the summary NOW — measured
+ * live, a session sat 151 logged events behind while the token floor had only
+ * accumulated 645, because the floor counts user/assistant prose and the
+ * trigger was freshly restarted. Waiting for the gate is not an option a user
+ * should have to accept, so there is an explicit request.
+ *
+ * There are three faces, and this module owns the two that live in the Host:
+ *
+ * - the slash command `hypatia-summarize`, executed by the UI **without a model
+ *   turn** (`CommandDefinition.handler`'s contract), and
+ * - the tool `hypatia_summarize`, which is the skill's execution path: the
+ *   agent asks for consolidation instead of writing `sum-*` entries itself.
+ *
+ * The third face — the Memory tab's button — rides the same host action from
+ * `memory-api.js`. All three call one function and report its one result
+ * vocabulary, so they cannot drift into telling a user different things.
+ *
+ * What is deliberately NOT here: any way to run the consolidation model call
+ * inline. An explicit request only ENQUEUES. The queue executor is the single
+ * writer of `sum-*` / `wu-*` (idempotent by name), and a synchronous second
+ * writer would be exactly the duplicate this design exists to avoid.
+ *
+ * @module dsh-hypatia-auto-memory/on-demand
+ */
+
+import { SUMMARIZE_REASON } from './consolidator.js'
+
+/** Slash command a user types in the composer. */
+export const SUMMARIZE_COMMAND = 'hypatia-summarize'
+
+/** Agent-facing tool name, per DSH's snake_case tool convention. */
+export const SUMMARIZE_TOOL = 'hypatia_summarize'
+
+/** Plugin-owned identity of the command definition, independent of its name. */
+export const SUMMARIZE_DEFINITION_ID = 'dsh-hypatia-auto-memory/hypatia-summarize'
+
+/**
+ * `/`-menu description. The client keeps the Host's own text for a non-builtin
+ * command and shows it in the Commands section, after the builtins, so this
+ * line is the whole discovery story for the command — it has to say what the
+ * command does without relying on the name being recognized.
+ *
+ * Bilingual on purpose: the dictionaries this plugin ships are, and the command
+ * registry has one `description` field with no locale behind it.
+ */
+export const SUMMARIZE_COMMAND_DESCRIPTION = 'Summarise this session into Hypatia memory now · 立即整理本会话'
+
+/** Tool description; model-facing, so English only and explicit about the side effect. */
+export const SUMMARIZE_TOOL_DESCRIPTION = 'Summarise a session into long-term Hypatia memory right now, without waiting '
+  + 'for the automatic background thresholds. Queues the consolidation span that is currently unsummarised; the '
+  + 'summary is produced in the background on the plugin\'s dedicated model route, so this call returns immediately '
+  + 'and does not consume this session\'s context. Use it only when the user explicitly asks to summarise, '
+  + 'consolidate or digest the current (or a named) session now. Never call it on your own initiative.'
+
+/**
+ * The session id a command invocation or a tool call is bound to.
+ *
+ * Mirrors the collector's own derivation (`header.id` first): the header is the
+ * durable copy, and a detached session exposes the same value through `id`.
+ *
+ * @param {any} session
+ * @returns {string} the id, or '' when there is none to read.
+ */
+export function sessionIdOf(session) {
+  const value = session?.header?.id ?? session?.id
+  return value === undefined || value === null ? '' : String(value)
+}
+
+/**
+ * The one result an unavailable consolidation half reports.
+ * @param {string} sessionId
+ * @returns {{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number}}
+ */
+export function unavailableOutcome(sessionId) {
+  return { sessionId, queued: false, reason: SUMMARIZE_REASON.Unavailable, fromSeq: 0, toSeq: 0 }
+}
+
+/**
+ * The one result the whole plugin being switched off reports, for the route
+ * family that stays mounted so a user can still see why nothing happens.
+ * @param {string} sessionId
+ * @returns {{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number}}
+ */
+export function disabledOutcome(sessionId) {
+  return { sessionId, queued: false, reason: SUMMARIZE_REASON.Disabled, fromSeq: 0, toSeq: 0 }
+}
+
+/**
+ * The human-readable rendering of one outcome, shared by the command and the
+ * Memory tab's button. English, because it is also the tool's model-facing text
+ * (see {@link summarizeOutcomeValue}); the client localizes its own rendering
+ * and falls back to the reason code, not to this sentence.
+ *
+ * @param {{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number}} result
+ * @returns {string}
+ */
+export function outcomeText(result) {
+  if (result.queued) {
+    return `Consolidation queued for ${result.sessionId} over events [${result.fromSeq}, ${result.toSeq}). `
+      + 'The summary is written in the background on the plugin\'s own model route.'
+  }
+  switch (result.reason) {
+    case SUMMARIZE_REASON.Empty:
+      return `${result.sessionId} has nothing left to summarise: every logged event is already consolidated.`
+    case SUMMARIZE_REASON.Busy:
+      return `A consolidation covering [${result.fromSeq}, ${result.toSeq}) is already queued for ${result.sessionId}.`
+    case SUMMARIZE_REASON.Disabled:
+      return 'Consolidation is turned off (hypatia-auto-memory.consolidation.enabled).'
+    case SUMMARIZE_REASON.Unavailable:
+      return 'Consolidation is unavailable: no model route is mounted for it.'
+    case SUMMARIZE_REASON.Unknown:
+      return `No session "${result.sessionId}" is available to consolidate.`
+    default:
+      return `Consolidation was not queued (${result.reason}).`
+  }
+}
+
+/**
+ * The command's verdict on one outcome.
+ *
+ * "Nothing to do" and "already queued" are successes: the handler did its job
+ * and the answer is truthful. Only a genuine refusal — the feature is off, no
+ * route exists, the session is gone — is an error, which the composer renders
+ * as one.
+ *
+ * @param {{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number}} result
+ * @returns {{kind: 'success', text: string} | {kind: 'error', text: string}}
+ */
+export function commandResult(result) {
+  const text = outcomeText(result)
+  if (result.queued) return { kind: 'success', text }
+  if (result.reason === SUMMARIZE_REASON.Empty || result.reason === SUMMARIZE_REASON.Busy) {
+    return { kind: 'success', text }
+  }
+  return { kind: 'error', text }
+}
+
+/**
+ * The tool's canonical value for one outcome.
+ *
+ * Structured rather than prose-only so an agent can branch on `queued` and
+ * `reason`; `message` carries the explanatory sentence for the common case.
+ *
+ * @param {{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number}} result
+ * @returns {{sessionId: string, queued: boolean, reason: string, fromSeq: number, toSeq: number, message: string}}
+ */
+export function summarizeOutcomeValue(result) {
+  return { ...result, message: outcomeText(result) }
+}
+
+/**
+ * The tool's `execute`, split from registration so it is unit-testable without
+ * the DSH package graph.
+ *
+ * The calling session is the default and an explicit `sessionId` overrides it.
+ * A call with neither is an error: guessing "the first session" or "the most
+ * recent one" would consolidate a conversation nobody asked about.
+ *
+ * @param {{run: (sessionId: string) => Promise<any>}} deps
+ * @returns {(args: {sessionId?: string}, exec: {agent?: {session: any}}) => Promise<any>}
+ */
+export function summarizeToolHandler({ run }) {
+  return async (args, exec) => {
+    const explicit = typeof args?.sessionId === 'string' ? args.sessionId.trim() : ''
+    const sessionId = explicit !== '' ? explicit : sessionIdOf(exec?.agent?.session)
+    if (sessionId === '') {
+      throw new Error('hypatia_summarize: no calling session is bound to this call; pass sessionId explicitly')
+    }
+    return summarizeOutcomeValue(await run(sessionId))
+  }
+}
+
+/**
+ * Register `/hypatia-summarize`.
+ *
+ * The handler never sends anything to the model — that is the registry's own
+ * contract for `handler`, and the acceptance test for this face is that no
+ * model call is logged.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - a `commands`-injected context.
+ * @param {{run: (sessionId: string) => Promise<any>, status: import('./status.js').StatusLog}} deps
+ */
+export function registerSummarizeCommand(ctx, { run, status }) {
+  ctx.effect(() => ctx.commands.register({
+    definitionId: SUMMARIZE_DEFINITION_ID,
+    name: SUMMARIZE_COMMAND,
+    description: SUMMARIZE_COMMAND_DESCRIPTION,
+    handler: async (invocation) => {
+      const sessionId = sessionIdOf(invocation?.agent?.session)
+      if (sessionId === '') {
+        return { kind: 'error', text: 'hypatia-summarize: this invocation has no session to consolidate' }
+      }
+      return commandResult(await run(sessionId))
+    },
+  }), 'dsh-hypatia-auto-memory: /hypatia-summarize')
+  status.info(`command registered: /${SUMMARIZE_COMMAND}`)
+}
+
+/**
+ * Register the `hypatia_summarize` tool.
+ *
+ * `@deepseek-ai/dsh-tools` is imported lazily, like `@deepseek-ai/dsh-llm` in
+ * the consolidator: the pure helpers above stay importable (and testable)
+ * without the DSH package graph, and a composition that has no tool registry
+ * never needs the package at all.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - a `tools`-injected context.
+ * @param {{run: (sessionId: string) => Promise<any>, status: import('./status.js').StatusLog}} deps
+ * @returns {Promise<void>} resolves once the definition is registered.
+ */
+export async function registerSummarizeTool(ctx, { run, status }) {
+  const { defineTool } = await import('@deepseek-ai/dsh-tools')
+  const definition = defineTool({
+    name: SUMMARIZE_TOOL,
+    description: SUMMARIZE_TOOL_DESCRIPTION,
+    parameters: {
+      sessionId: {
+        type: 'string',
+        description: 'Session id to summarise. Defaults to the session this call runs in.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          sessionId: { type: 'string', required: true },
+          queued: { type: 'boolean', required: true },
+          reason: {
+            type: 'string',
+            required: true,
+            description: 'Empty when queued; otherwise disabled, empty, busy, unknown-session or unavailable.',
+          },
+          fromSeq: { type: 'number', required: true },
+          toSeq: { type: 'number', required: true },
+          message: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.message }],
+    },
+    execute: summarizeToolHandler({ run }),
+  })
+  ctx.effect(() => ctx.tools.register(definition), 'dsh-hypatia-auto-memory: hypatia_summarize tool')
+  status.info(`tool registered: ${SUMMARIZE_TOOL}`)
+}