dsh-tacit 0.2.0

package/lib/fold.js

@@ -0,0 +1,300 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 hackernotfound — https://github.com/hackernotfound/dsh-tacit
+/**
+ * dsh-tacit — trajectory fold (session projection unit).
+ *
+ * A pure, synchronous fold over the committed session event log that keeps a
+ * bounded ring of per-turn digests: the human prompt, step count, tool calls
+ * (name + clipped argument preview), tool errors, retries, compactions,
+ * feedback counts, provider-reported usage, and the final assistant text.
+ *
+ * Registered on the harness's `ctx.sessionProjections` registry, which drives
+ * `apply(state, event)` over every committed event, persists the state through
+ * the projection cache, and pushes the finished value to the browser as a
+ * `session/projection` frame where the client reads it with
+ * `useProjection('tacitTimeline')`.
+ *
+ * The contract on dsh >= 0.1.1-rc.1 requires BOTH `stateSchema` (validates the
+ * persisted state on restore) and `wire` (declares the browser-delivered
+ * payload); `schema`/`view` are kept for older hosts. `stateVersion` must be
+ * bumped whenever the persisted state shape or fold semantics change.
+ *
+ * Fork-seed guard: a forked session's log starts with parent-copied events
+ * whose original timestamps predate the child's createdAt (carried by the
+ * `session` header-line event during cold restore). Those are skipped — the
+ * parent session already folded them. A resumed session's seed is its own
+ * history and folds normally.
+ */
+
+import { timelineStateSchema, timelineViewSchema } from './schema.js'
+
+export const DEFAULT_BOUNDS = {
+  maxKeptTurns: 60,
+  maxPromptChars: 4000,
+  maxToolCallChars: 500,
+  maxAssistantChars: 4000,
+  maxToolCallsPerTurn: 50,
+}
+
+/** Clip text to `max` chars (string-safe). */
+export function clip(text, max) {
+  const value = typeof text === 'string' ? text : ''
+  return value.length <= max ? value : value.slice(0, max)
+}
+
+/** Concatenate the text blocks of a message content list (blocks may be any shape). */
+export function textOfBlocks(content) {
+  if (!Array.isArray(content)) return ''
+  let out = ''
+  for (const block of content) {
+    if (
+      block !== null && typeof block === 'object'
+      && block.type === 'text' && typeof block.text === 'string'
+    ) {
+      out = out.length > 0 ? `${out}\n${block.text}` : block.text
+    }
+  }
+  return out
+}
+
+function zeroUsage() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    reasoningTokens: 0,
+  }
+}
+
+export function emptyTurn(turn, time) {
+  return {
+    turn,
+    startedAt: time,
+    prompt: '',
+    provisionalPrompt: '',
+    steps: 0,
+    toolCalls: [],
+    toolErrors: 0,
+    retries: 0,
+    compactions: 0,
+    feedback: 0,
+    usage: zeroUsage(),
+    finalText: '',
+    model: '',
+    provider: '',
+    finished: false,
+    endedAt: 0,
+    endReason: '',
+    enrichment: '',
+  }
+}
+
+/** Is this user/message the coach's own pre-send context note? */
+function isCoachEnrichment(source) {
+  return source !== null && typeof source === 'object' && source.kind === 'plugin' && source.plugin === 'dsh-tacit'
+}
+
+/** Add the usage of one assistant message into the turn's running totals (mutates `usage`). */
+function accumulateUsage(usage, usageReport) {
+  if (usageReport === null || typeof usageReport !== 'object') return usage
+  const read = (key) => {
+    const value = usageReport[key]
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0
+  }
+  usage.inputTokens += read('inputTokens')
+  usage.outputTokens += read('outputTokens')
+  usage.cacheReadTokens += read('cacheReadTokens')
+  usage.cacheWriteTokens += read('cacheWriteTokens')
+  usage.reasoningTokens += read('reasoningTokens')
+  return usage
+}
+
+/** Close the open turn: strip fold-internal fields, mark finished, append to the ring, trim. */
+function closeTurn(state, turn, finished, endedAt, endReason = '') {
+  const { provisionalPrompt, ...record } = turn
+  const closed = {
+    ...record,
+    prompt: record.prompt.length > 0 ? record.prompt : provisionalPrompt,
+    finished,
+    endedAt,
+    endReason: clip(endReason, 40),
+  }
+  const turns = state.turns.concat([closed])
+  const excess = turns.length - state.maxKeptTurns
+  if (excess > 0) turns.splice(0, excess)
+  return { ...state, turns, current: null }
+}
+
+/** Fold one committed event into the timeline state (same reference when irrelevant). */
+export function applyTimeline(state, event, bounds) {
+  // The persistence header line arrives as a `type: 'session'` event during
+  // cold restore; it carries the session's createdAt at the envelope level.
+  if (event.type === 'session') {
+    const created = Number(event.createdAt)
+    if (Number.isFinite(created) && created > 0 && created !== state.createdAt) {
+      return { ...state, createdAt: created }
+    }
+    return state
+  }
+  // Fork-seed guard: a forked session's log starts with the parent's copied
+  // events, whose original timestamps predate the child's createdAt. The
+  // parent already folded them, so skip. A resumed session's seed is its own
+  // history (timestamps >= its own createdAt) and folds normally.
+  const eventTime = Number(event.time)
+  if (state.createdAt > 0 && Number.isFinite(eventTime) && eventTime > 0 && eventTime < state.createdAt) {
+    return state
+  }
+
+  switch (event.type) {
+    case 'turn/start': {
+      const turn = event.data !== null && typeof event.data === 'object' && typeof event.data.turn === 'number'
+        ? event.data.turn
+        : (state.current?.turn ?? 0) + 1
+      const next = state.current === null
+        ? state
+        : closeTurn(state, state.current, false, event.time)
+      return { ...next, current: emptyTurn(turn, event.time) }
+    }
+
+    case 'turn/end': {
+      if (state.current === null) return state
+      const reason = event.data !== null && typeof event.data === 'object' && typeof event.data.reason === 'string'
+        ? event.data.reason
+        : ''
+      return closeTurn(state, state.current, true, event.time, reason)
+    }
+
+    case 'user/message': {
+      if (state.current === null) return state
+      const data = event.data
+      const source = data !== null && typeof data === 'object' ? data.source : null
+      const text = data !== null && typeof data === 'object' ? textOfBlocks(data.content) : ''
+      if (text.length === 0) return state
+      const current = state.current
+      if (isCoachEnrichment(source)) {
+        if (current.enrichment === '') current.enrichment = clip(text, bounds.maxPromptChars)
+        return { ...state }
+      }
+      const isHuman = source !== null && typeof source === 'object' && source.kind === 'user'
+      if (current.provisionalPrompt === '') current.provisionalPrompt = clip(text, 100000)
+      if (isHuman && current.prompt === '') current.prompt = clip(text, bounds.maxPromptChars)
+      return { ...state }
+    }
+
+    case 'step/start':
+    case 'step/end': {
+      if (state.current === null) return state
+      const step = event.data !== null && typeof event.data === 'object' && typeof event.data.step === 'number'
+        ? event.data.step
+        : 0
+      if (step > state.current.steps) state.current.steps = step
+      return { ...state }
+    }
+
+    case 'tool/call': {
+      if (state.current === null) return state
+      if (state.current.toolCalls.length >= bounds.maxToolCallsPerTurn) return state
+      const data = event.data !== null && typeof event.data === 'object' ? event.data : {}
+      state.current.toolCalls.push({
+        name: typeof data.name === 'string' ? data.name : '?',
+        args: clip(typeof data.arguments === 'string' ? data.arguments : '', bounds.maxToolCallChars),
+      })
+      return { ...state }
+    }
+
+    case 'tool/result': {
+      if (state.current === null) return state
+      const data = event.data !== null && typeof event.data === 'object' ? event.data : null
+      if (data !== null && data.error !== undefined && data.error !== null) state.current.toolErrors += 1
+      return { ...state }
+    }
+
+    case 'assistant/message': {
+      if (state.current === null) return state
+      const data = event.data !== null && typeof event.data === 'object' ? event.data : {}
+      accumulateUsage(state.current.usage, data.usage)
+      const text = data.message !== null && typeof data.message === 'object'
+        ? textOfBlocks(data.message.content)
+        : ''
+      if (text.length > 0) state.current.finalText = clip(text, bounds.maxAssistantChars)
+      return { ...state }
+    }
+
+    case 'request/header': {
+      if (state.current === null) return state
+      const header = event.data !== null && typeof event.data === 'object' ? event.data.header : null
+      const config = header !== null && typeof header === 'object' ? header.config : null
+      if (config !== null && typeof config === 'object') {
+        if (typeof config.model === 'string') state.current.model = config.model
+        if (typeof config.provider === 'string') state.current.provider = config.provider
+      }
+      return { ...state }
+    }
+
+    case 'llm/retry': {
+      if (state.current === null) return state
+      state.current.retries += 1
+      return { ...state }
+    }
+
+    case 'compaction/summary': {
+      if (state.current === null) return state
+      state.current.compactions += 1
+      return { ...state }
+    }
+
+    case 'feedback/record': {
+      if (state.current === null) return state
+      state.current.feedback += 1
+      return { ...state }
+    }
+
+    default:
+      return state
+  }
+}
+
+/**
+ * The `tacitTimeline` projection definition. `boundsOf` is re-read on
+ * every fold so retention settings changed from the UI apply live.
+ */
+export function createTimelineDefinition(boundsOf) {
+  const view = (state) => ({
+    turns: state.current === null ? state.turns : state.turns.concat([stripProvisional(state.current)]),
+  })
+  const definition = {
+    key: 'tacitTimeline',
+    // Contract (dsh >= 0.1.1-rc.1): without `wire` and `stateSchema`
+    // the registry treats the unit as host-only and never pushes to the browser.
+    stateSchema: timelineStateSchema,
+    wire: {
+      viewSchema: timelineViewSchema,
+      view,
+    },
+    init: () => ({ createdAt: 0, turns: [], current: null, maxKeptTurns: 60 }),
+    apply: (state, event) => {
+      const bounds = {
+        ...DEFAULT_BOUNDS,
+        ...(boundsOf === undefined ? {} : boundsOf()),
+      }
+      // Keep the retention cap inside the persisted state so old checkpoints
+      // restore with the bound that produced them; refresh it live here.
+      if (state.maxKeptTurns !== bounds.maxKeptTurns) {
+        state = { ...state, maxKeptTurns: bounds.maxKeptTurns }
+      }
+      return applyTimeline(state, event, bounds)
+    },
+    // 1 → 2: turn digests gained `endReason` (from turn/end data.reason).
+    // 2 → 3: turn digests gained `enrichment` (the coach's pre-send context note).
+    stateVersion: 3,
+  }
+  return definition
+}
+
+/** Strip the fold-internal provisional field before anything leaves the fold. */
+function stripProvisional(turn) {
+  if (turn === null || turn === undefined) return turn
+  const { provisionalPrompt, ...rest } = turn
+  return rest
+}

package/lib/index.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 hackernotfound — https://github.com/hackernotfound/dsh-tacit
+/**
+ * dsh-tacit — host half entry.
+ *
+ * Loaded by the profile's bundle patch row (`cordis.patch.yml`):
+ *   - registers the `tacitTimeline` session projection (the trajectory
+ *     fold the browser reads via useProjection);
+ *   - provides the `tacit` service and its /api/tacit/* routes;
+ *   - injects the learned directives as a system-prompt section;
+ *   - stores everything under $DSH_HOME/storages/tacit/.
+ *
+ * The plugin shares the harness process, so it only talks to services through
+ * the duck-typed `ctx` — no cordis runtime imports, no second instance of
+ * anything stateful. API keys are handled entirely by the harness's own LLM
+ * service.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+import { Config } from './schema.js'
+import { createTimelineDefinition } from './fold.js'
+import { CoachStore } from './store.js'
+import { createCoachService, mergeConfig } from './service.js'
+import { registerWebRoutes } from './routes.js'
+
+export const name = 'tacit'
+export { Config }
+
+/**
+ * One-time adoption of the plugin's previous name: an existing
+ * storages/prompt-coach directory becomes storages/tacit (rename only —
+ * nothing is deleted; when both exist the newer one wins untouched).
+ * Safe to drop after 0.3.0 — every dsh-prompt-coach user has migrated by then.
+ */
+export function migrateLegacyStorage(dshHome) {
+  const legacy = path.join(dshHome, 'storages', 'prompt-coach')
+  const current = path.join(dshHome, 'storages', 'tacit')
+  try {
+    if (fs.existsSync(legacy) && !fs.existsSync(current)) fs.renameSync(legacy, current)
+  } catch {
+    // Best effort: a failed rename just means a fresh profile.
+  }
+  return current
+}
+
+export function apply(ctx, config) {
+  const store = new CoachStore(migrateLegacyStorage(resolveDshHome()))
+  const effectiveConfig = () => mergeConfig(config, store.configPatch())
+
+  // Trajectory fold. Guarded inject so assemblies without the projection
+  // registry (headless) simply skip this half instead of failing.
+  ctx.inject(['sessionProjections'], (scope) => {
+    scope.sessionProjections.register(createTimelineDefinition(() => effectiveConfig()))
+  })
+
+  // Browser-facing service + routes.
+  const service = createCoachService(ctx, store, effectiveConfig)
+  ctx.provide('tacit', service)
+  registerWebRoutes(ctx, service)
+
+  // Ambient steering: the learned directives ride every session's system
+  // prompt (order 60: after the persona, before tool guidance). Guarded
+  // inject — assemblies without a system-prompt service simply skip it.
+  ctx.inject(['systemPrompt'], (scope) => {
+    if (scope.systemPrompt === undefined || scope.systemPrompt === null || typeof scope.systemPrompt.section !== 'function') return
+    scope.systemPrompt.section({
+      name: 'tacit:steering',
+      order: 60,
+      text: (assemble) => service.steeringText(assemble),
+    })
+  })
+
+  // Opt-in pre-send enrichment (config.enrichPrompts, default off): append a
+  // learned context note to the first step of a turn; never rewrites the
+  // user's message. The listener itself is a no-op while the option is off.
+  if (typeof ctx.on === 'function') {
+    const off = ctx.on('agent/pre-step', (payload, next) => service.preStep(payload, next))
+    if (typeof off === 'function') ctx.effect(() => off, 'tacit: pre-step enrichment')
+  }
+
+  ctx.effect(() => () => {
+    // Nothing to flush: all writes are atomic and complete at call time.
+  }, 'tacit: dispose')
+}

package/lib/routes.js

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 hackernotfound — https://github.com/hackernotfound/dsh-tacit
+/**
+ * dsh-tacit — browser-facing HTTP routes on the harness's own web
+ * server (the same transport dsh-memento's panel uses). No third-party
+ * server, no extra port: the GUI already talks to these /api/* routes on the
+ * harness origin.
+ *
+ * Registered through the guarded `webServer` service; disposers are collected
+ * into one ctx.effect so a fiber unload removes every route.
+ */
+
+function withService(ctx, serviceName, fn) {
+  const existing = ctx.get !== undefined && typeof ctx.get === 'function' ? ctx.get(serviceName) : undefined
+  if (existing !== undefined && existing !== null) {
+    fn(existing)
+    return
+  }
+  if (ctx.on !== undefined && typeof ctx.on === 'function') {
+    const off = ctx.on('internal/service', (name) => {
+      if (name !== serviceName) return
+      const service = ctx.get !== undefined && typeof ctx.get === 'function' ? ctx.get(serviceName) : undefined
+      if (service !== undefined && service !== null) {
+        off()
+        fn(service)
+      }
+    })
+  }
+}
+
+function sendJson(res, status, value) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(value))
+}
+
+/** Read a JSON request body (bounded); never rejects — returns {} on any problem. */
+async function readJsonBody(req) {
+  const chunks = []
+  let bytes = 0
+  try {
+    for await (const chunk of req) {
+      if (chunk === null || chunk === undefined) continue
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      bytes += buffer.length
+      if (bytes > 256 * 1024) return null
+      chunks.push(buffer)
+    }
+  } catch {
+    return null
+  }
+  const raw = Buffer.concat(chunks).toString('utf8')
+  if (raw.trim() === '') return {}
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Cross-site request guard. The harness web server has no origin policy, and
+ * Tacit's routes write into the agent's system prompt (directives) and spend
+ * money (analyze/improve/bootstrap) — so a web page must not be able to drive
+ * them from another origin. Browsers block cross-origin `application/json`
+ * fetches at the CORS preflight; this closes the remaining "simple request"
+ * shapes (forms, text/plain) and honours the fetch-metadata headers.
+ * Non-browser callers (curl, the smoke script) carry none of these headers and
+ * pass; the browser client always sends application/json from the same origin.
+ */
+function crossSiteReason(req) {
+  const headers = req !== null && typeof req === 'object' && req.headers !== null && typeof req.headers === 'object' ? req.headers : {}
+  const site = typeof headers['sec-fetch-site'] === 'string' ? headers['sec-fetch-site'].toLowerCase() : ''
+  if (site !== '' && site !== 'same-origin' && site !== 'none') return 'sec-fetch-site'
+  const origin = typeof headers.origin === 'string' ? headers.origin : ''
+  const host = typeof headers.host === 'string' ? headers.host : ''
+  if (origin !== '' && origin !== 'null' && host !== '') {
+    let originHost = ''
+    try { originHost = new URL(origin).host } catch { originHost = '' }
+    if (originHost !== host) return 'origin'
+  }
+  const type = typeof headers['content-type'] === 'string' ? headers['content-type'].toLowerCase() : ''
+  if (type !== '' && !type.startsWith('application/json')) return 'content-type'
+  return ''
+}
+
+/**
+ * Register the /api/tacit/* routes against the harness web server.
+ * `service` is the object returned by createCoachService.
+ */
+export function registerWebRoutes(ctx, service) {
+  withService(ctx, 'webServer', (webServer) => {
+    if (webServer === null || typeof webServer.register !== 'function') return
+    const disposers = []
+    const route = (method, pathName, handler) => {
+      disposers.push(webServer.register({
+        kind: 'exact',
+        path: pathName,
+        handler: async (req, res) => {
+          try {
+            if (typeof req.method === 'string' && req.method.toUpperCase() !== method) {
+              sendJson(res, 405, { ok: false, code: 'bad-request', detail: 'method' })
+              return
+            }
+            const reason = crossSiteReason(req)
+            if (reason !== '') {
+              sendJson(res, 403, { ok: false, code: 'forbidden', detail: reason })
+              return
+            }
+            const body = await readJsonBody(req)
+            if (body === null) {
+              sendJson(res, 400, { ok: false, code: 'bad-json', detail: '' })
+              return
+            }
+            const result = await handler(body)
+            // Malformed or orphaned feedback/applied requests are rejected
+            // with an HTTP 400 (soft envelopes keep the other codes at 200).
+            const rejected = result !== null && typeof result === 'object' && result.ok === false
+              && (result.code === 'bad-request' || result.code === 'unknown-rewrite')
+            sendJson(res, rejected ? 400 : 200, result)
+          } catch (error) {
+            const detail = error instanceof Error ? error.message.slice(0, 300) : String(error).slice(0, 300)
+            sendJson(res, 500, { ok: false, code: 'internal', detail })
+          }
+        },
+      }))
+    }
+
+    route('POST', '/api/tacit/state', () => service.getState())
+    route('POST', '/api/tacit/reports', (body) => service.getReports(body))
+    route('POST', '/api/tacit/history', (body) => service.listHistory(body))
+    route('POST', '/api/tacit/analyze', (body) => service.analyzeTurn(body))
+    route('POST', '/api/tacit/improve', (body) => service.improveDraft(body))
+    route('POST', '/api/tacit/feedback', (body) => service.feedback(body))
+    route('POST', '/api/tacit/applied', (body) => service.applied(body))
+    route('POST', '/api/tacit/directives', (body) => service.directives(body))
+    route('POST', '/api/tacit/stats', (body) => service.stats(body))
+    route('POST', '/api/tacit/bootstrap', (body) => service.bootstrap(body))
+    route('POST', '/api/tacit/config', (body) => service.updateConfig(body))
+    route('POST', '/api/tacit/clear', () => service.clearReports())
+
+    ctx.effect(() => () => {
+      for (const dispose of disposers.splice(0).reverse()) {
+        try {
+          dispose?.()
+        } catch {
+          // Best-effort teardown.
+        }
+      }
+    }, 'tacit: web routes')
+  })
+}