dsh-hitl 0.1.0

package/lib/fields.js

@@ -0,0 +1,244 @@
+/**
+ * Proposal construction: turning one pending tool execution plus its mount into
+ * the wire request the browser renders, and turning a human decision back into
+ * the text the model reads.
+ *
+ * Defaults follow the plugin's core promise: with no configuration at all, the
+ * proposal is the call's own parameters — one field per parameter, titled by the
+ * parameter's key, rendered as an editable markdown box.
+ */
+
+import { LIMITS, truncate } from './protocol.js'
+import { defaultEditable } from './resolve.js'
+
+/** Model-facing prefix every reason this plugin produces starts with. */
+export const REASON_PREFIX = 'HITL'
+
+/** Render a parameter value as proposal text. */
+export function renderValue(value) {
+  if (typeof value === 'string') return value
+  if (value === undefined) return '(undefined)'
+  try {
+    const json = JSON.stringify(value, null, 2)
+    return json === undefined ? String(value) : json
+  } catch {
+    return String(value)
+  }
+}
+
+/**
+ * The default renderer of one parameter value: an editable markdown box, for
+ * every value. A non-string value reaches it as pretty-printed JSON text, and a
+ * mount that prefers the read-only JSON inspector says `render: 'json'`.
+ * @returns the render mode, always `'markdown'`.
+ */
+export function inferRender() {
+  return 'markdown'
+}
+
+function schemaOf(execution) {
+  const parameters = execution.schema?.parameters
+  return typeof parameters === 'object' && parameters !== null ? parameters : undefined
+}
+
+function schemaEntry(execution, param) {
+  const schema = schemaOf(execution)
+  const entry = schema === undefined ? undefined : schema[param]
+  return typeof entry === 'object' && entry !== null ? entry : undefined
+}
+
+function argumentsOf(execution) {
+  const args = execution.arguments
+  return typeof args === 'object' && args !== null && !Array.isArray(args) ? args : undefined
+}
+
+/**
+ * Derive the default field list of one call: every parameter, in argument order.
+ * @param execution - the pending tool execution.
+ * @returns field specs (`{ param, title? }`) before values are attached.
+ */
+export function defaultFieldSpecs(execution) {
+  const args = argumentsOf(execution)
+  if (args === undefined) return [{ param: '(arguments)', render: 'json' }]
+  const keys = Object.keys(args)
+  if (keys.length === 0) return [{ param: '(arguments)', render: 'json' }]
+  return keys.map(param => ({ param }))
+}
+
+function diffSpec(spec, mount, execution) {
+  const requested = spec.diff ?? mount.options.diff
+  if (requested === undefined || requested === null || typeof requested !== 'object') return undefined
+  const before = requested.before
+  const after = requested.after
+  if (typeof before !== 'string' || typeof after !== 'string') return undefined
+  const args = argumentsOf(execution)
+  if (args === undefined) return undefined
+  return {
+    path: typeof requested.path === 'string' ? renderValue(args[requested.path]) : undefined,
+    oldText: renderValue(args[before]),
+    newText: renderValue(args[after]),
+  }
+}
+
+/**
+ * Build the wire fields of one request.
+ * @param execution - the pending tool execution.
+ * @param mount - the matched mount.
+ * @returns an ordered field array, values already rendered and truncated.
+ */
+export function buildFields(execution, mount) {
+  const options = mount.options
+  const args = argumentsOf(execution)
+  const mountDiff = options.diff === undefined || options.diff === null ? undefined : options.diff
+  // A mount-level diff pairs two parameters, so those parameters must not also
+  // appear as their own fields in the defaulted list.
+  const paired = options.fields === undefined && mountDiff !== undefined
+    ? new Set([mountDiff.before, mountDiff.after].filter(entry => typeof entry === 'string'))
+    : new Set()
+  const specs = options.fields
+    ?? defaultFieldSpecs(execution).filter(spec => !paired.has(spec.param))
+  const fields = []
+  for (const spec of specs) {
+    const param = spec.param
+    const schema = schemaEntry(execution, param)
+    // The scalar fallback field reads the whole argument value; every other
+    // field reads its own parameter out of the argument record.
+    const raw = param === '(arguments)' && args === undefined
+      ? execution.arguments
+      : (args === undefined ? undefined : args[param])
+    const render = spec.render ?? (diffSpec(spec, mount, execution) === undefined ? inferRender(raw) : 'diff')
+    const diff = render === 'diff' ? diffSpec(spec, mount, execution) : undefined
+    const title = spec.title
+      ?? (typeof schema?.title === 'string' ? schema.title : undefined)
+      ?? param
+    const description = spec.description
+      ?? (typeof schema?.description === 'string' ? schema.description : undefined)
+    const editable = spec.editable ?? defaultEditable(render)
+    // A hidden field carries no value: it exists only to stay out of the panel.
+    const value = diff === undefined && render !== 'hidden'
+      ? truncate(renderValue(raw), options.maxFieldChars)
+      : { text: '', truncated: false }
+    fields.push({
+      param,
+      title,
+      ...(description === undefined ? {} : { description }),
+      render,
+      editable: render === 'diff' || render === 'hidden' ? false : editable,
+      labels: spec.labels ?? [],
+      ...(diff === undefined ? { value: value.text, truncated: value.truncated } : { diff }),
+    })
+  }
+  if (options.fields === undefined && mountDiff !== undefined) {
+    const diff = diffSpec({ diff: mountDiff }, mount, execution)
+    if (diff !== undefined) {
+      fields.push({
+        param: `${options.diff.before}→${options.diff.after}`,
+        title: typeof options.diff.title === 'string' ? options.diff.title : 'diff',
+        render: 'diff',
+        editable: false,
+        labels: [],
+        diff,
+      })
+    }
+  }
+  if (fields.length === 0) {
+    return [{ param: '(arguments)', title: '(arguments)', render: 'json', editable: false, labels: [], value: '{}', truncated: false }]
+  }
+  return fields
+}
+
+/**
+ * Build one complete wire request.
+ * @param input - `{ execution, mount, sessionId, id, now }`.
+ * @returns the request object broadcast to browsers.
+ */
+export function buildRequest({ execution, mount, sessionId, id, now = Date.now() }) {
+  const options = mount.options
+  const fields = buildFields(execution, mount)
+  const countdown = options.countdown === null ? null : {
+    remainingMs: options.countdown.seconds * 1000,
+    action: options.countdown.action,
+    freezeOnInteract: options.countdown.freezeOnInteract,
+  }
+  return {
+    id,
+    sessionId,
+    toolName: execution.name,
+    ...(execution.callId === undefined ? {} : { callId: String(execution.callId) }),
+    ...(options.title === undefined ? {} : { title: options.title }),
+    layout: options.layout,
+    labels: options.labels,
+    fields,
+    buttons: {
+      ...options.buttons,
+      feedback: {
+        enabled: options.reject.feedback,
+        ...(options.reject.feedbackPrompt === undefined ? {} : { prompt: options.reject.feedbackPrompt }),
+        required: options.reject.requireFeedback,
+      },
+    },
+    countdown,
+    createdAt: now,
+  }
+}
+
+/** Whether a decision carries a human edit of the proposal. */
+export function isRevision(decision) {
+  return decision.kind === 'modify' && decision.fields.length > 0
+}
+
+/**
+ * Render the human's edited fields as text the model can act on.
+ * @param decision - a modify decision.
+ * @returns one block per changed field.
+ */
+export function revisionText(decision) {
+  return decision.fields
+    .map(entry => `- ${entry.param}:\n${entry.text}`)
+    .join('\n')
+}
+
+/**
+ * Fold one settled decision into the single message the model reads.
+ * @param request - the request the human decided on.
+ * @param decision - the normalized decision.
+ * @param source - `user`, `timeout`, `abort`, or `host`.
+ * @returns the model-facing reason text.
+ */
+export function describeDecision(request, decision, source) {
+  const tool = JSON.stringify(request.toolName)
+  if (source === 'timeout') {
+    const seconds = Math.round((request.countdown?.remainingMs ?? 0) / 1000)
+    if (decision.kind === 'approve') return `${REASON_PREFIX}: no human decision arrived within ${seconds}s, so tool ${tool} ran under the mount's timeout policy.`
+    if (request.countdown?.action === 'notify') {
+      return `${REASON_PREFIX}: no human decision arrived within ${seconds}s, so tool ${tool} did not run. Tell the user this call timed out and wait for an explicit instruction before running it.`
+    }
+    return `${REASON_PREFIX}: no human decision arrived within ${seconds}s, so tool ${tool} did not run (timeout policy: reject).`
+  }
+  if (source === 'abort' || source === 'host') {
+    return `${REASON_PREFIX}: the decision for tool ${tool} was withdrawn before the user answered, so it did not run.`
+  }
+  if (decision.kind === 'modify') {
+    return `${REASON_PREFIX}: the user revised the proposal, so tool ${tool} did not run. Re-issue the call with these changes:\n${revisionText(decision)}`
+  }
+  const feedback = decision.kind === 'reject' && typeof decision.feedback === 'string' && decision.feedback !== ''
+    ? ` User feedback: ${decision.feedback}`
+    : ''
+  return `${REASON_PREFIX}: the user rejected tool ${tool} and it did not run.${feedback}`
+}
+
+/**
+ * Fold one approved-with-edits decision into context the model reads alongside
+ * the tool result (`modify.mode: allow-and-inform`).
+ * @param request - the request the human approved.
+ * @param decision - a modify decision.
+ * @returns the follow-up text.
+ */
+export function revisionContext(request, decision) {
+  return `${REASON_PREFIX}: the user approved tool ${JSON.stringify(request.toolName)} after editing the proposal. Their revised content:\n${revisionText(decision)}`
+}
+
+/** Cap one model-facing text at the protocol limit. */
+export function capReason(text) {
+  return truncate(text, LIMITS.maxDecisionChars).text
+}

package/lib/pending.js

@@ -0,0 +1,217 @@
+/**
+ * The pending-decision registry: one state machine per open HITL request,
+ * owning its countdown, its interaction hold, and the exactly-once settlement
+ * that releases the blocked tool call.
+ *
+ * The clock is injected so tests drive seconds without waiting for them, and so
+ * every timer this plugin arms passes through one place that can be cleared on
+ * unload.
+ */
+
+import { ERROR_CODES, OUTCOMES } from './protocol.js'
+
+/** Default cap on how long one browser may freeze a countdown by interacting. */
+export const DEFAULT_HOLD_GRACE_MS = 300000
+
+/** Decision a countdown action applies when it reaches zero. */
+export function timeoutDecision(action) {
+  if (action === 'approve') return { kind: 'approve' }
+  return { kind: 'reject' }
+}
+
+/**
+ * Create one process-wide pending registry.
+ * @param options - injected clock/timers, settlement sink, and hold grace.
+ * @returns the registry API used by the host half.
+ */
+export function createPendingRegistry({
+  now = Date.now,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  onSettle = () => {},
+  holdGraceMs = DEFAULT_HOLD_GRACE_MS,
+} = {}) {
+  const entries = new Map()
+  const settledOrder = []
+  // Settled identities outlive their entry so a late or duplicated decision is
+  // reported as already-settled rather than as an unknown request. The set is
+  // only a diagnostic, so it is dropped wholesale rather than aged.
+  const settledIds = new Set()
+  const SETTLED_MEMORY = 4096
+
+  /** Verdict for an identity that has no open entry. */
+  function missing(id) {
+    return settledIds.has(id) ? ERROR_CODES.alreadySettled : ERROR_CODES.unknownRequest
+  }
+
+  function clearEntryTimers(entry) {
+    if (entry.timer !== undefined) {
+      clearTimer(entry.timer)
+      entry.timer = undefined
+    }
+    if (entry.graceTimer !== undefined) {
+      clearTimer(entry.graceTimer)
+      entry.graceTimer = undefined
+    }
+  }
+
+  function armCountdown(entry) {
+    if (entry.countdownMs === null || entry.settled) return
+    const delay = Math.max(0, entry.remainingMs)
+    entry.timer = setTimer(() => {
+      entry.timer = undefined
+      close(entry.id, OUTCOMES.timeout, timeoutDecision(entry.countdownAction))
+    }, delay)
+  }
+
+  function releaseHold(entry) {
+    if (!entry.held) return
+    entry.held = false
+    entry.holdExpiresAt = undefined
+    if (entry.graceTimer !== undefined) {
+      clearTimer(entry.graceTimer)
+      entry.graceTimer = undefined
+    }
+    // Re-base the countdown so the frozen remainder is what still runs, and so a
+    // later hold computes the remainder from the resumed clock rather than from
+    // the original deadline that already passed.
+    entry.startedAt = now() + entry.remainingMs - entry.countdownMs
+    armCountdown(entry)
+  }
+
+  function close(id, source, decision) {
+    const entry = entries.get(id)
+    if (entry === undefined) return { accepted: false, code: missing(id) }
+    if (entry.settled) return { accepted: false, code: ERROR_CODES.alreadySettled }
+    clearEntryTimers(entry)
+    entry.settled = true
+    entry.settledAt = now()
+    entry.source = source
+    entry.decision = decision
+    entries.delete(id)
+    settledOrder.push(id)
+    settledIds.add(id)
+    if (settledIds.size > SETTLED_MEMORY) settledIds.clear()
+    onSettle(entry, { decision, source })
+    return { accepted: true }
+  }
+
+  return {
+    /**
+     * Register one open decision.
+     * @param input - identity, wire request, countdown policy, and callbacks.
+     * @returns `{ ok: true }` or `{ ok: false, code }` for a duplicate id.
+     */
+    open({ id, request, countdown, onTimeout }) {
+      if (entries.has(id)) return { ok: false, code: ERROR_CODES.alreadySettled }
+      const countdownMs = countdown === null || countdown === undefined ? null : countdown.remainingMs
+      const entry = {
+        id,
+        request,
+        countdownMs,
+        countdownAction: countdown?.action ?? 'reject',
+        freezeOnInteract: countdown?.freezeOnInteract !== false,
+        onTimeout,
+        remainingMs: countdownMs ?? 0,
+        startedAt: now(),
+        held: false,
+        holdExpiresAt: undefined,
+        timer: undefined,
+        graceTimer: undefined,
+        settled: false,
+        settledAt: undefined,
+        source: undefined,
+        decision: undefined,
+      }
+      entries.set(id, entry)
+      armCountdown(entry)
+      return { ok: true, expiresAt: countdownMs === null ? undefined : entry.startedAt + countdownMs }
+    },
+
+    /** Apply the human's decision. First call wins; later calls are reported. */
+    settle(id, decision) {
+      return close(id, OUTCOMES.user, decision)
+    },
+
+    /**
+     * Freeze or resume one countdown while its browser holds the decision.
+     * @param id - request identity.
+     * @param held - whether the browser is still interacting.
+     * @returns the acceptance, and when a hold stops applying on its own.
+     */
+    hold(id, held) {
+      const entry = entries.get(id)
+      if (entry === undefined) return { ok: false, code: missing(id) }
+      if (entry.settled) return { ok: false, code: ERROR_CODES.alreadySettled }
+      if (entry.countdownMs === null) return { ok: true, held: false }
+      if (!entry.freezeOnInteract) return { ok: true, held: false }
+      if (held) {
+        if (entry.held) return { ok: true, held: true, expiresAt: entry.holdExpiresAt }
+        entry.remainingMs = Math.max(0, entry.startedAt + entry.countdownMs - now())
+        entry.held = true
+        if (entry.timer !== undefined) {
+          clearTimer(entry.timer)
+          entry.timer = undefined
+        }
+        entry.holdExpiresAt = now() + holdGraceMs
+        entry.graceTimer = setTimer(() => {
+          entry.graceTimer = undefined
+          releaseHold(entry)
+        }, holdGraceMs)
+        return { ok: true, held: true, expiresAt: entry.holdExpiresAt }
+      }
+      releaseHold(entry)
+      return { ok: true, held: false }
+    },
+
+    /** Withdraw one request (turn interruption, unload, or host-side cancel). */
+    abort(id, source = OUTCOMES.abort) {
+      return close(id, source, { kind: 'cancel' })
+    },
+
+    /** Withdraw every open request; used on plugin teardown. */
+    drain(source = OUTCOMES.host) {
+      const ids = [...entries.keys()]
+      for (const id of ids) close(id, source, { kind: 'cancel' })
+      return ids
+    },
+
+    /** Whether one request identity is still open. */
+    has(id) {
+      return entries.has(id)
+    },
+
+    /** The wire request behind one identity, or undefined once settled. */
+    get(id) {
+      return entries.get(id)?.request
+    },
+
+    /** Every open request, in registration order. */
+    list() {
+      return [...entries.values()].map(entry => entry.request)
+    },
+
+    /** Count of open requests. */
+    size() {
+      return entries.size
+    },
+
+    /** Identities settled so far, in settlement order (diagnostics and tests). */
+    settled() {
+      return [...settledOrder]
+    },
+
+    /** Whether one request's countdown is currently frozen by a client. */
+    held(id) {
+      return entries.get(id)?.held === true
+    },
+
+    /** Remaining milliseconds of one countdown, or null when it has none. */
+    remaining(id) {
+      const entry = entries.get(id)
+      if (entry === undefined || entry.countdownMs === null) return null
+      if (entry.held) return entry.remainingMs
+      return Math.max(0, entry.startedAt + entry.countdownMs - now())
+    },
+  }
+}

package/lib/protocol.js

@@ -0,0 +1,182 @@
+/**
+ * The dsh-hitl wire protocol: the normative definition of every frame the host
+ * half broadcasts, every payload the browser half sends back, and the limits
+ * both sides agree on.
+ *
+ * Both halves are plain JavaScript loaded without a build step, so `client.js`
+ * cannot import this module. It re-implements the few shapes it must produce;
+ * the tests in `tests/protocol.test.js` pin the contract the two halves share.
+ * Anything the wire carries is untrusted on arrival and passes a validator here
+ * before it reaches the gate.
+ */
+
+/** Bumped when a frame shape changes incompatibly. */
+export const PROTOCOL_VERSION = 1
+
+/** The `globalThis` property the served index carries this plugin's boot facts in. */
+export const GLOBAL_KEY = '__DSH_HITL__'
+
+/** Default route prefix the host half owns on the browser HTTP carrier. */
+export const DEFAULT_ENDPOINT = '/dsh-hitl'
+
+/** Discriminator of the pending-interaction values the browser half publishes. */
+export const PENDING_KIND = 'hitl'
+
+/** Bounds applied to untrusted input and to what reaches the browser. */
+export const LIMITS = {
+  /** Largest uplink body the decide route accepts. */
+  maxBodyBytes: 256 * 1024,
+  /** Longest rendered value of one field before truncation. */
+  maxFieldChars: 20000,
+  /** Longest decision text folded into one model-facing message. */
+  maxDecisionChars: 8000,
+}
+
+/** Failure vocabulary shared by the HTTP replies and the panel's error state. */
+export const ERROR_CODES = {
+  unauthorized: 'unauthorized',
+  badPayload: 'bad-payload',
+  unknownRequest: 'unknown-request',
+  alreadySettled: 'already-settled',
+  hostGone: 'host-gone',
+}
+
+/** How a pending request left the pending set. */
+export const OUTCOMES = {
+  user: 'user',
+  timeout: 'timeout',
+  abort: 'abort',
+  host: 'host',
+}
+
+/** Structural guard for plain records (not arrays, not null). */
+export function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Structural guard for the decision vocabulary the uplink may carry. */
+export function isDecision(value) {
+  if (!isRecord(value)) return false
+  if (value.kind === 'approve') return true
+  if (value.kind === 'reject') {
+    return value.feedback === undefined || typeof value.feedback === 'string'
+  }
+  if (value.kind === 'modify') {
+    return Array.isArray(value.fields)
+      && value.fields.every(entry => isRecord(entry)
+        && typeof entry.param === 'string'
+        && typeof entry.text === 'string')
+  }
+  return false
+}
+
+/**
+ * Normalize one untrusted uplink payload.
+ * @param value - parsed JSON body of a decide/hold request.
+ * @returns `{ ok: true, value }` with a trimmed decision, or `{ ok: false, code, message }`.
+ */
+export function parseUplink(value) {
+  if (!isRecord(value)) return invalid('the uplink body must be a JSON object')
+  if (typeof value.id !== 'string' || value.id === '') return invalid('id must be a non-empty string')
+  if (value.type === 'hold') {
+    if (typeof value.held !== 'boolean') return invalid('hold.held must be a boolean')
+    return { ok: true, value: { type: 'hold', id: value.id, held: value.held } }
+  }
+  if (value.type !== 'decide') return invalid(`unknown uplink type ${JSON.stringify(value.type)}`)
+  if (!isDecision(value.decision)) return invalid('decision must be approve, modify, or reject')
+  const decision = value.decision
+  if (decision.kind === 'reject') {
+    const feedback = typeof decision.feedback === 'string' ? decision.feedback.trim() : ''
+    return {
+      ok: true,
+      value: {
+        type: 'decide',
+        id: value.id,
+        decision: feedback === '' ? { kind: 'reject' } : { kind: 'reject', feedback },
+      },
+    }
+  }
+  if (decision.kind === 'modify') {
+    const fields = decision.fields
+      .map(entry => ({ param: entry.param, text: entry.text }))
+      .filter(entry => entry.param !== '')
+    if (fields.length === 0) return invalid('a modify decision must carry at least one field change')
+    return { ok: true, value: { type: 'decide', id: value.id, decision: { kind: 'modify', fields } } }
+  }
+  return { ok: true, value: { type: 'decide', id: value.id, decision: { kind: 'approve' } } }
+}
+
+function invalid(message) {
+  return { ok: false, code: ERROR_CODES.badPayload, message }
+}
+
+/** Frame announcing the complete pending set; sent on connect and on demand. */
+export function frameSnapshot(requests) {
+  return { type: 'snapshot', version: PROTOCOL_VERSION, requests }
+}
+
+/** Frame announcing one newly pending request. */
+export function frameRequest(request) {
+  return { type: 'request', version: PROTOCOL_VERSION, request }
+}
+
+/** Frame announcing one request left the pending set. */
+export function frameSettled(id, outcome, decidedBy) {
+  return {
+    type: 'settled',
+    version: PROTOCOL_VERSION,
+    id,
+    outcome,
+    ...(decidedBy === undefined ? {} : { decidedBy }),
+  }
+}
+
+/** Liveness frame: it carries nothing, and proves the stream is still attached. */
+export function framePing() {
+  return { type: 'ping', version: PROTOCOL_VERSION }
+}
+
+/**
+ * Frame answering a hold request: whether the host froze the countdown, when a
+ * hold stops applying on its own, and the remainder the host now holds.
+ *
+ * The remainder travels with the ack because a freeze and a release both move
+ * the deadline; a client that kept counting on its own clock would show a
+ * number the host disagrees with on the very frame the pause ends.
+ */
+export function frameHoldAck(id, held, expiresAt, remainingMs) {
+  return {
+    type: 'holdAck',
+    version: PROTOCOL_VERSION,
+    id,
+    held,
+    ...(expiresAt === undefined ? {} : { expiresAt }),
+    ...(remainingMs === null || remainingMs === undefined ? {} : { remainingMs }),
+  }
+}
+
+/** One Server-Sent-Event data chunk carrying a JSON frame. */
+export function sseChunk(frame) {
+  return `data: ${JSON.stringify(frame)}\n\n`
+}
+
+/** JSON body of a failed route call. */
+export function errorBody(code, message) {
+  return { ok: false, code, message }
+}
+
+/** JSON body of a successful route call. */
+export function okBody(accepted) {
+  return { ok: true, accepted }
+}
+
+/**
+ * Cap one string at a limit, marking that it was cut.
+ * @param text - value to bound.
+ * @param limit - maximum character count.
+ * @returns the value, cut with a trailing notice when it exceeded the limit.
+ */
+export function truncate(text, limit) {
+  if (text.length <= limit) return { text, truncated: false }
+  return { text: `${text.slice(0, limit)}\n… [已截断，共 ${text.length} 字]`, truncated: true }
+}