dsh-retrace 0.3.0

package/lib/host-core.js

@@ -0,0 +1,379 @@
+/**
+ * dsh-retrace — Host core.
+ *
+ * Shared business logic for message recall (撤回), edit-and-resend (编辑重发)
+ * and regenerate (重新生成) over one DSH Session.
+ *
+ * The DSH conversation log is append-only, but the model-visible *surface*
+ * supports positional replacement (the same primitive compaction uses): a new
+ * surface-eligible event carrying `surfaceOp: { op: 'replace', start, end }`
+ * shadows every node in [start..end] from the derived model history. This
+ * module appends an *invisible* replacement marker (an empty assistant message
+ * derives to no model message) so the conversation rewinds to before the
+ * target while the durable transcript keeps an audit trail.
+ *
+ * Pure ESM with zero imports: safe to run inside the dynamic-package sandbox
+ * and inside a published package alike. Every op resolves to a transport-
+ * neutral result object `{ ok: true, value }` or `{ ok: false, error }` and
+ * never rejects (transport failures are the caller's concern).
+ */
+
+export const EDITOR_PLUGIN = 'retrace'
+
+/** Message-id prefix every event this plugin appends carries (client discriminator). */
+export const MARKER_ID_PREFIX = 'retrace'
+
+export function createEditorApi(ctx, sessions, agents, log = () => {}) {
+  /** One in-flight op per session; later ops wait for the earlier one. */
+  const locks = new Map()
+
+  function locked(sessionId, fn) {
+    const previous = locks.get(sessionId) ?? Promise.resolve()
+    const next = previous.catch(() => {}).then(fn)
+    locks.set(sessionId, next)
+    void next.finally(() => {
+      if (locks.get(sessionId) === next) locks.delete(sessionId)
+    }).catch(() => {})
+    return next
+  }
+
+  function editorId(op) {
+    return `${MARKER_ID_PREFIX}-${op}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+  }
+
+  function editorError(code, message) {
+    const error = new Error(message)
+    error.code = code
+    return error
+  }
+
+  function requireSession(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+      throw editorError('bad-request', 'sessionId must be a non-empty string')
+    }
+    const session = sessions.get(sessionId)
+    if (!session) throw editorError('session-not-found', `session "${sessionId}" not found`)
+    return session
+  }
+
+  function requireIdle(agent) {
+    if (agent && typeof agent.status === 'string' && agent.status === 'running') {
+      throw editorError(
+        'agent-busy',
+        'The agent is still responding. Stop the current reply before recalling or editing.',
+      )
+    }
+  }
+
+  /** Latest known provider/model: from the last request header, else last assistant message. */
+  function lastModelSource(session) {
+    const events = session.events
+    for (let i = events.length - 1; i >= 0; i--) {
+      const event = events[i]
+      if (event.type === 'request/header') {
+        const config = event.data?.header?.config
+        if (
+          config &&
+          typeof config.provider === 'string' && config.provider.length > 0 &&
+          typeof config.model === 'string' && config.model.length > 0
+        ) {
+          return { provider: config.provider, model: config.model }
+        }
+      }
+      if (event.type === 'assistant/message') {
+        const source = event.data?.message?.source
+        if (
+          source && source.kind === 'model' &&
+          typeof source.provider === 'string' && source.provider.length > 0 &&
+          typeof source.model === 'string' && source.model.length > 0
+        ) {
+          return { provider: source.provider, model: source.model }
+        }
+      }
+    }
+    return null
+  }
+
+  /** Locate the durable seq of a user/assistant message by its stable message id. */
+  function findMessageSeq(session, messageId) {
+    if (typeof messageId !== 'string' || messageId.length === 0) {
+      throw editorError('bad-request', 'messageId must be a non-empty string')
+    }
+    const events = session.events
+    for (let i = events.length - 1; i >= 0; i--) {
+      const event = events[i]
+      const id = event.type === 'user/message'
+        ? event.data?.id
+        : event.type === 'assistant/message'
+          ? event.data?.message?.id
+          : undefined
+      if (typeof id === 'string' && id === messageId) return event.seq
+    }
+    return -1
+  }
+
+  /** The current model-surface span starting at `startSeq` through the tail. */
+  function shadowSpanFrom(session, startSeq) {
+    const nodes = session.surface.nodes
+    const index = nodes.indexOf(startSeq)
+    if (index === -1) return null
+    const span = nodes.slice(index)
+    return {
+      start: span[0],
+      end: span[span.length - 1],
+      shadowedSeqs: span.slice(),
+    }
+  }
+
+  /**
+   * A round boundary is a real user-sent message. The runtime also appends
+   * `user/message` events for injected context/steering (source.kind !== 'user',
+   * e.g. the runtime-context snapshot); those must NOT split an exchange round.
+   */
+  function isRoundBoundary(event) {
+    return event?.type === 'user/message' && event.data?.source?.kind === 'user'
+  }
+
+  /**
+   * The exchange-round span containing `seq`: the user input plus everything
+   * the agent produced for it (all assistant/tool nodes up to the next user
+   * input). Recalling one message therefore removes the whole round — input
+   * AND output — from the model surface.
+   */
+  function roundSpanFrom(session, seq) {
+    const nodes = session.surface.nodes
+    const index = nodes.indexOf(seq)
+    if (index === -1) return null
+    const targetEvent = session.events[seq]
+    let startIdx = index
+    if (!isRoundBoundary(targetEvent)) {
+      for (let i = index - 1; i >= 0; i--) {
+        if (isRoundBoundary(session.events[nodes[i]])) {
+          startIdx = i
+          break
+        }
+      }
+    }
+    let endIdx = nodes.length - 1
+    for (let i = startIdx + 1; i < nodes.length; i++) {
+      if (isRoundBoundary(session.events[nodes[i]])) {
+        endIdx = i - 1
+        break
+      }
+    }
+    const span = nodes.slice(startIdx, endIdx + 1)
+    return {
+      start: span[0],
+      end: span[span.length - 1],
+      shadowedSeqs: span,
+    }
+  }
+
+  /**
+   * Append the invisible replacement marker that shadows [span.start..span.end].
+   * An empty assistant message is a valid surface node yet derives to *no*
+   * model message, so the LLM context simply rewinds. `turn: null` declares a
+   * session-level event (the client location index maps it to SESSION_LOCATION,
+   * keeping it out of every turn's node list). `editor` carries the reference
+   * facts the UI uses for the optional "original input" comparison row.
+   */
+  function appendEditorMarker(session, span, op, targetSeq, originalText) {
+    const model = lastModelSource(session)
+    if (!model) {
+      throw editorError(
+        'no-model-header',
+        'This session has no model header yet; send at least one message before recalling or editing.',
+      )
+    }
+    const marker = {
+      id: editorId(op),
+      role: 'assistant',
+      content: [],
+      source: { kind: 'model', provider: model.provider, model: model.model },
+    }
+    return session.append('assistant/message', {
+      turn: null,
+      step: null,
+      message: marker,
+      editor: {
+        targetSeq,
+        text: typeof originalText === 'string' ? originalText.slice(0, 2000) : '',
+      },
+    }, {
+      surfaceOp: { op: 'replace', start: span.start, end: span.end },
+      sourceEventSeqs: span.shadowedSeqs.slice(),
+    })
+  }
+
+  function extractUserText(content) {
+    if (!Array.isArray(content)) return ''
+    return content
+      .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text)
+      .join('')
+  }
+
+  function resendMessage(text, op) {
+    return {
+      id: editorId(op),
+      role: 'user',
+      content: [{ type: 'text', text }],
+      source: { kind: 'user', rpcId: editorId('retrace') },
+    }
+  }
+
+  async function flushSafely(session) {
+    try {
+      if (typeof sessions.flush === 'function') await sessions.flush(session)
+    } catch (error) {
+      log(`retrace: flush failed: ${String(error)}`)
+    }
+  }
+
+  /** Wrap one op body into the transport-neutral result convention. */
+  function op(fn) {
+    return (args) =>
+      locked(String(args?.sessionId ?? ''), () =>
+        Promise.resolve()
+          .then(() => fn(args))
+          .then(
+            (value) => ({ ok: true, value }),
+            (error) => ({
+              ok: false,
+              error: {
+                code: error && typeof error.code === 'string' ? error.code : 'internal',
+                message: error instanceof Error ? error.message : String(error),
+              },
+            }),
+          ),
+      )
+  }
+
+  /** Extract the durable text of a user or assistant message by seq. */
+  function messageTextOf(session, seq) {
+    const event = session.events[seq]
+    if (!event) return ''
+    const data = event.type === 'user/message' ? event.data : event.data?.message
+    return extractUserText(data?.content)
+  }
+
+  /** 撤回: remove the whole exchange round (input + output) around one message. */
+  const recall = op(async (args) => {
+    const sessionId = String(args?.sessionId ?? '')
+    const messageId = String(args?.messageId ?? '')
+    const session = requireSession(sessionId)
+    requireIdle(agents.get(sessionId))
+    const seq = findMessageSeq(session, messageId)
+    if (seq === -1) throw editorError('message-not-found', 'Message not found in this session.')
+    const span = roundSpanFrom(session, seq)
+    if (!span) throw editorError('target-shadowed', 'This message is no longer part of the active conversation.')
+    const markerEvent = appendEditorMarker(session, span, 'recall', seq, messageTextOf(session, seq))
+    await flushSafely(session)
+    return {
+      op: 'recall',
+      messageId,
+      seq,
+      markerSeq: markerEvent.seq,
+      shadowed: span.shadowedSeqs.length,
+      text: messageTextOf(session, seq),
+    }
+  })
+
+  /**
+   * 编辑重发: rewind before a user message, replace it with `text`, then re-trigger
+   * the agent. With `fromScratch` the whole surface is rewound first, so the
+   * conversation continues from a clean slate (new-conversation semantics).
+   */
+  const editAndResend = op(async (args) => {
+    const sessionId = String(args?.sessionId ?? '')
+    const messageId = String(args?.messageId ?? '')
+    const text = args?.text
+    const fromScratch = args?.fromScratch === true
+    const session = requireSession(sessionId)
+    const agent = agents.get(sessionId)
+    requireIdle(agent)
+    const seq = findMessageSeq(session, messageId)
+    if (seq === -1) throw editorError('message-not-found', 'Message not found in this session.')
+    const event = session.events[seq]
+    if (!isRoundBoundary(event)) {
+      throw editorError('not-user-message', 'Only user messages can be edited and re-sent.')
+    }
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw editorError('blank-text', 'The edited message must not be empty.')
+    }
+    if (!agent || typeof agent.followup !== 'function') {
+      throw editorError('agent-unavailable', 'No live agent for this session; cannot re-send.')
+    }
+    const originalText = messageTextOf(session, seq)
+    const startSeq = fromScratch ? session.surface.nodes[0] : seq
+    if (startSeq === undefined) throw editorError('empty-surface', 'This session has no conversation to edit.')
+    const span = shadowSpanFrom(session, startSeq)
+    if (!span) throw editorError('target-shadowed', 'This message is no longer part of the active conversation.')
+    appendEditorMarker(session, span, 'edit', seq, originalText)
+    await flushSafely(session)
+    const message = resendMessage(text.trim(), 'resend')
+    agent.followup(message)
+    return {
+      op: 'edit',
+      messageId,
+      seq,
+      resendMessageId: message.id,
+      shadowed: span.shadowedSeqs.length,
+      text: text.trim(),
+      originalText,
+      fromScratch,
+    }
+  })
+
+  /** 重新生成: rewind to the user prompt that produced one assistant reply, then re-send it. */
+  const regenerate = op(async (args) => {
+    const sessionId = String(args?.sessionId ?? '')
+    const messageId = String(args?.messageId ?? '')
+    const session = requireSession(sessionId)
+    const agent = agents.get(sessionId)
+    requireIdle(agent)
+    const seq = findMessageSeq(session, messageId)
+    if (seq === -1) throw editorError('message-not-found', 'Message not found in this session.')
+    const event = session.events[seq]
+    if (event?.type !== 'assistant/message') {
+      throw editorError('not-assistant-message', 'Regenerate targets an assistant reply.')
+    }
+    const nodes = session.surface.nodes
+    const index = nodes.indexOf(seq)
+    if (index === -1) throw editorError('target-shadowed', 'This message is no longer part of the active conversation.')
+    let userSeq = -1
+    for (let i = index - 1; i >= 0; i--) {
+      if (isRoundBoundary(session.events[nodes[i]])) {
+        userSeq = nodes[i]
+        break
+      }
+    }
+    if (userSeq === -1) throw editorError('no-prompt', 'No user message precedes this reply; cannot regenerate.')
+    const text = extractUserText(session.events[userSeq]?.data?.content)
+    if (!text.trim()) {
+      throw editorError('no-text', 'The original message carries no text to regenerate from.')
+    }
+    if (!agent || typeof agent.followup !== 'function') {
+      throw editorError('agent-unavailable', 'No live agent for this session; cannot re-send.')
+    }
+    const span = shadowSpanFrom(session, userSeq)
+    if (!span) throw editorError('target-shadowed', 'This message is no longer part of the active conversation.')
+    appendEditorMarker(session, span, 'regenerate', userSeq, text)
+    await flushSafely(session)
+    const message = resendMessage(text.trim(), 'resend')
+    agent.followup(message)
+    return {
+      op: 'regenerate',
+      messageId,
+      seq,
+      resendMessageId: message.id,
+      shadowed: span.shadowedSeqs.length,
+    }
+  })
+
+  return {
+    recall: (args) => recall(args),
+    editAndResend: (args) => editAndResend(args),
+    regenerate: (args) => regenerate(args),
+  }
+}

package/lib/http.js

@@ -0,0 +1,186 @@
+/**
+ * dsh-retrace — HTTP route aggregation for `/api/plugins/retrace/*`.
+ *
+ * Serves both the published-client transports and the versioning surface:
+ *
+ *   POST /api/plugins/retrace/{recall|editAndResend|regenerate}
+ *     — the L1 editor ops (unchanged wire shape from 0.2.x).
+ *   GET  /api/plugins/retrace/versions?sessionId=
+ *     — live projection snapshot (HTTP fallback channel; the push channel is
+ *       `session/projection` frames via dsh-host-apiproxy).
+ *   GET  /api/plugins/retrace/event?sessionId=&seq=&before=&after=
+ *     — one event + context window (sessionQuery.readEvent, lazy reads).
+ *   GET  /api/plugins/retrace/surface?sessionId=
+ *     — current model surface (sessionQuery.readSurface).
+ *
+ * Per PLAN.md §4.6 the client carries its localStorage config on every
+ * request as `x-retrace-config: {"versioning":bool,"git":bool,
+ * "retentionLimit":n}`; the host honors it per request and does not persist
+ * it. A missing/malformed header falls back to the plugin defaults.
+ */
+import { createEditorApi } from './host-core.js'
+
+export const ROUTE_PREFIX = '/api/plugins/retrace'
+const MAX_BODY_BYTES = 64 * 1024
+
+/** Default per-request config (client overrides via the header). */
+export const DEFAULT_CONFIG = { versioning: true, git: true, retentionLimit: 50 }
+
+/** Parse the `x-retrace-config` request header (tolerant of garbage). */
+export function parseRetraceConfig(raw) {
+  const config = { ...DEFAULT_CONFIG }
+  if (typeof raw !== 'string' || raw.length === 0) return config
+  try {
+    const parsed = JSON.parse(raw)
+    if (typeof parsed.versioning === 'boolean') config.versioning = parsed.versioning
+    if (typeof parsed.git === 'boolean') config.git = parsed.git
+    if (Number.isInteger(parsed.retentionLimit) && parsed.retentionLimit > 0) {
+      config.retentionLimit = parsed.retentionLimit
+    }
+  } catch {
+    // malformed header → defaults
+  }
+  return config
+}
+
+function sendJson(res, status, value) {
+  const body = JSON.stringify(value)
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(body),
+    'Cache-Control': 'no-store',
+  })
+  res.end(body)
+}
+
+function sendError(res, error) {
+  sendJson(res, 200, {
+    ok: false,
+    error: {
+      code: error && typeof error.code === 'string' ? error.code : 'internal',
+      message: error instanceof Error ? error.message : String(error),
+    },
+  })
+}
+
+/** Route one request. `seam` is the versioning seam (lib/versioning.js). */
+export function createRetraceHttpHandler(ctx, { sessions, agents, seam, log = () => {} }) {
+  const api = createEditorApi(ctx, sessions, agents, log)
+
+  function handleVersions(req, res, sessionId, config) {
+    seam.setConfig(sessionId, config)
+    try {
+      sendJson(res, 200, { ok: true, value: seam.snapshot(sessionId) })
+    } catch (error) {
+      sendError(res, error)
+    }
+  }
+
+  async function handleEvent(req, res, searchParams) {
+    const sessionId = searchParams.get('sessionId') ?? ''
+    const seq = Number(searchParams.get('seq'))
+    const before = searchParams.has('before') ? Number(searchParams.get('before')) : undefined
+    const after = searchParams.has('after') ? Number(searchParams.get('after')) : undefined
+    try {
+      const value = await seam.readEvent({ sessionId, seq, before, after })
+      sendJson(res, 200, { ok: true, value })
+    } catch (error) {
+      sendError(res, error)
+    }
+  }
+
+  async function handleSurface(req, res, sessionId) {
+    try {
+      const value = await seam.readSurface(sessionId)
+      sendJson(res, 200, { ok: true, value })
+    } catch (error) {
+      sendError(res, error)
+    }
+  }
+
+  function handlePost(req, res, op) {
+    let body = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      body += chunk
+      if (body.length > MAX_BODY_BYTES) {
+        sendJson(res, 413, {
+          ok: false,
+          error: { code: 'payload-too-large', message: 'payload exceeds 64 KiB' },
+        })
+        req.destroy()
+      }
+    })
+    req.on('error', () => { /* socket errors are terminal; nothing to send */ })
+    req.on('end', async () => {
+      let args = {}
+      if (body.length > 0) {
+        try {
+          args = JSON.parse(body)
+        } catch {
+          sendJson(res, 400, {
+            ok: false,
+            error: { code: 'bad-json', message: 'request body is not valid JSON' },
+          })
+          return
+        }
+      }
+      const sessionId = String(args?.sessionId ?? '')
+      if (sessionId) seam.setConfig(sessionId, parseRetraceConfig(req.headers['x-retrace-config']))
+      const opFn = api[op]
+      if (typeof opFn !== 'function') {
+        sendJson(res, 404, {
+          ok: false,
+          error: { code: 'unknown-op', message: `unknown operation "${op}"` },
+        })
+        return
+      }
+      try {
+        const result = await opFn(args)
+        sendJson(res, 200, result)
+      } catch (error) {
+        sendError(res, error)
+      }
+    })
+  }
+
+  return (req, res) => {
+    const url = new URL(req.url ?? '/', 'http://retrace.local')
+    const op = url.pathname.split('/').filter(Boolean).at(-1) ?? ''
+    const searchParams = url.searchParams
+    const sessionId = searchParams.get('sessionId') ?? ''
+    const config = parseRetraceConfig(req.headers['x-retrace-config'])
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, x-retrace-config',
+      })
+      res.end()
+      return
+    }
+    if (req.method === 'GET') {
+      switch (op) {
+        case 'versions':
+          return handleVersions(req, res, sessionId, config)
+        case 'event':
+          return void handleEvent(req, res, searchParams)
+        case 'surface':
+          return void handleSurface(req, res, sessionId)
+        default:
+          return sendJson(res, 404, {
+            ok: false,
+            error: { code: 'unknown-op', message: `unknown operation "${op}"` },
+          })
+      }
+    }
+    if (req.method !== 'POST') {
+      return sendJson(res, 405, {
+        ok: false,
+        error: { code: 'method-not-allowed', message: 'POST or GET only' },
+      })
+    }
+    return handlePost(req, res, op)
+  }
+}

package/lib/index.js

@@ -0,0 +1,75 @@
+/**
+ * dsh-retrace — Host plugin entry (published form).
+ *
+ * Registers the retrace operations behind two transports so the same
+ * package serves both the desktop/web GUI and headless deployments:
+ *
+ *  - `harness.handle` when present (the dynamic-package RPC bridge), and
+ *  - a same-origin HTTP route under `/api/plugins/retrace/*` for
+ *    bundled (published) client modules.
+ *
+ * The HTTP surface additionally serves the P0 versioning channels:
+ * `GET /versions` (projection snapshot fallback), `GET /event` and
+ * `GET /surface` (lazy sessionQuery reads). The versioning seam itself
+ * (`lib/versioning.js`) lives behind `ctx.inject(...)` — headless
+ * compositions without the projection/storage services simply degrade to
+ * plain L1 (recall / edit / regenerate), exactly like 0.2.x.
+ *
+ * Every op resolves to a result object `{ ok: true, value }` /
+ * `{ ok: false, error }` produced by the host core, so both transports carry
+ * the identical wire shape.
+ */
+import { createEditorApi } from './host-core.js'
+import { createRetraceHttpHandler, ROUTE_PREFIX } from './http.js'
+import { createVersioningSeam } from './versioning.js'
+
+export const name = 'dsh-retrace'
+export const inject = ['sessions', 'agents', 'webServer']
+
+export function apply(ctx) {
+  const log = (line) => ctx.logger?.info(line)
+
+  // P0 versioning seam: projection unit + artifact snapshots + config view.
+  const seam = createVersioningSeam(ctx, log)
+  seam.register()
+
+  const api = createEditorApi(ctx, ctx.sessions, ctx.agents, log)
+  const handler = createRetraceHttpHandler(ctx, {
+    sessions: ctx.sessions,
+    agents: ctx.agents,
+    seam,
+    log,
+  })
+
+  const disposeRoute = (() => {
+    const webServer = ctx.get('webServer')
+    if (webServer && typeof webServer.register === 'function') {
+      try {
+        return webServer.register({
+          kind: 'prefix',
+          path: ROUTE_PREFIX,
+          handler,
+        })
+      } catch (error) {
+        ctx.logger?.warn(`dsh-retrace: route registration failed: ${String(error)}`)
+      }
+    }
+    return () => {}
+  })()
+
+  // Dynamic-package bridge: no-op when this file runs as a plain published plugin.
+  const disposeHarness = (() => {
+    if (typeof harness === 'undefined' || !harness || typeof harness.handle !== 'function') return () => {}
+    const disposers = [
+      harness.handle('retrace.recall', (args) => api.recall(args)),
+      harness.handle('retrace.editAndResend', (args) => api.editAndResend(args)),
+      harness.handle('retrace.regenerate', (args) => api.regenerate(args)),
+    ]
+    return () => disposers.forEach((dispose) => dispose())
+  })()
+
+  ctx.effect(() => () => {
+    disposeRoute()
+    disposeHarness()
+  }, 'dsh-retrace: transports')
+}