@huaqiu/dsh-log 0.0.0-stage → 1.1.2

package/index.ts

@@ -0,0 +1,848 @@
+/**
+ * DSH plugin: `call_external_api` + `run_external_script` with structured audit
+ * logging (v1.0).
+ *
+ * Written against the REAL DeepSeek Harness SDK surface (this checkout):
+ * - Cordis function-plugin exports (`name` / `inject` / `Config` / `apply`) —
+ *   the shape the profile `cordis.patch.yml` loader expects, NOT a standalone
+ *   `@dsh/sdk` module. See README.md for the spec→SDK adaptation table.
+ * - Tools are registered through `ctx.tools.register(defineTool(...))` from
+ *   `@deepseek-ai/dsh-tools`; `defineTool` takes `{ name, description,
+ *   parameters, output: { schema, render }, execute(args, exec) }`.
+ * - The spec's `ctx.log.info/error` → DUAL audit sink:
+ *     1. HOST LOG channel: one structured JSON line per record via
+ *        `ctx.logger('dsh-log')` (process log; never lost even
+ *        for non-agent callers — the v1.2 remote-push hook point).
+ *     2. SESSION-STREAM channel: the audit record is embedded in the tool's
+ *        canonical result, which DSH persists through the well-known
+ *        `tool/result` session event and renders on the WebUI Trajectory page.
+ *        (A plugin-owned custom event type is deliberately NOT used: this
+ *        build's persistence restore refuses unknown non-ignorable event
+ *        types, so a bespoke `audit/log` event would break session reload.)
+ * - The spec's `ctx.sessionId` → `exec.agent.session.id`; `ctx.config` → the
+ *   Cordis plugin `Config` (schemastery) resolved from the patch entry.
+ *
+ * Business logic, the log data model, masking/truncation rules and every
+ * security rule follow the spec document unchanged — see `audit-core.ts`.
+ *
+ * @module dsh-log
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { appendFileSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import {
+  ERROR_TYPES,
+  HOST_RISK_SEVERITY,
+  SCHEMA_VERSION,
+  callExternalApi,
+  classifyHost,
+  generateCallId,
+  hostOfUrl,
+  inspectAllowHosts,
+  maskSensitive,
+  maskTextForLog,
+  maskUrlQuery,
+  resolveTimeoutMs,
+  runExternalScript,
+  truncateJson,
+  type ApiCallParams,
+  type AuditJsonValue,
+  type AuditPhase,
+  type AuditRecord,
+  type ErrorType,
+  type HttpMethod,
+} from './audit-core.ts'
+
+/** Cordis plugin name (loader diagnostics + logger channel name). */
+export const name = 'dsh-log'
+
+/** Plugin version, reported in the boot record so a log file names the build that wrote it. */
+export const PLUGIN_VERSION = '1.1.2'
+
+/** Services this plugin requires before it can register tools. */
+export const inject = ['tools']
+
+const TOOL_API = 'call_external_api'
+const TOOL_SCRIPT = 'run_external_script'
+
+/** Plugin configuration (spec §8), resolved by schemastery with defaults. */
+export interface Config {
+  /** API host whitelist (`api_allow_hosts`). Empty = every call refused at runtime (fail closed). */
+  apiAllowHosts?: string[]
+  /** Script whitelist directory (`script_allow_dir`); REQUIRED — boot fails loud when empty. */
+  scriptAllowDir?: string
+  /** Global timeout budget in ms for both tools (`default_timeout`). Defaults to 30000. */
+  defaultTimeoutMs?: number
+  /** Upper bound for a per-call `timeoutMs` override on either tool (`max_timeout`). Defaults to 120000. */
+  maxTimeoutMs?: number
+  /** Max bytes of one request log segment (`maxReqLogSize`). Defaults to 2048. */
+  maxReqLogBytes?: number
+  /** Max bytes of one API response log segment (`maxRespLogSize`). Defaults to 2048. */
+  maxRespLogBytes?: number
+  /** Max bytes of captured script stdout/stderr (`maxOutputLogSize`). Defaults to 512. */
+  maxOutputLogBytes?: number
+  /** Max response BODY bytes buffered for one API call (memory protection; the live request is aborted beyond it). Defaults to 10 MiB. */
+  maxResponseBytes?: number
+  /** Max request BODY bytes serialized and sent for one API call (memory + egress protection; an oversized request is refused before any I/O). Defaults to 1 MiB. */
+  maxRequestBytes?: number
+  /** Working directory for executed scripts (`script_working_dir`); falls back to scriptAllowDir when empty. Defaults to ''. */
+  scriptWorkingDir?: string
+  /** Days to keep rotated audit log files before automatic cleanup. Defaults to 14. */
+  logRetentionDays?: number
+  /** Max bytes of one rotated audit log file before a `-partN` sibling is started. Defaults to 20 MiB. */
+  maxLogFileSizeBytes?: number
+}
+
+/** Schemastery schema: validates + defaults every config field at plugin load. */
+export const Config: z<Config> = z.object({
+  apiAllowHosts: z.array(z.string()).default([]),
+  scriptAllowDir: z.string().default(''),
+  defaultTimeoutMs: z.number().default(30_000),
+  maxTimeoutMs: z.number().default(120_000),
+  maxReqLogBytes: z.number().default(2048),
+  maxRespLogBytes: z.number().default(2048),
+  maxOutputLogBytes: z.number().default(512),
+  maxResponseBytes: z.number().default(10 * 1024 * 1024),
+  maxRequestBytes: z.number().default(1024 * 1024),
+  scriptWorkingDir: z.string().default(''),
+  logRetentionDays: z.number().default(14),
+  maxLogFileSizeBytes: z.number().default(20 * 1024 * 1024),
+})
+
+/** Config after schemastery applied every default. */
+type ResolvedConfig = Required<Config>
+
+/** One-line JSON audit sink over the host logger (channel 1 — never lost). */
+type HostAuditSink = (record: AuditRecord) => void
+
+function createHostAuditSink(ctx: Context): HostAuditSink {
+  const log = ctx.logger(name)
+  return record => {
+    try {
+      // One structured JSON line per record; level routes info/error.
+      if (record.level === 'ERROR') log.error(JSON.stringify(record))
+      else log.info(JSON.stringify(record))
+    } catch {
+      // An audit-sink failure must never mask the business outcome (spec §5.6
+      // protects records, but a broken sink cannot take the tool down with it).
+    }
+  }
+}
+
+function assertPositiveInteger(field: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) throw new Error(`dsh-log: ${field} must be a positive integer (got ${String(value)})`)
+}
+
+/** Session id of the calling agent, or 'standalone' for non-agent callers. */
+function sessionIdOf(exec: { agent?: { session?: { id?: unknown } } | undefined }): string {
+  const raw = exec.agent?.session?.id
+  return raw === undefined ? 'standalone' : String(raw)
+}
+
+/**
+ * Outcome of the persistent-sink registration, surfaced in the boot record so an
+ * operator can answer "did my audit lines actually land on disk?" from the log
+ * itself instead of guessing.
+ */
+type PersistentSinkStatus = { persistent: true; logDir: string } | { persistent: false; reason: string }
+
+/**
+ * Register a PERSISTENT exporter on the host logger service (channel-1 durability).
+ * Cordis's built-in logger only buffers messages in memory (capped at 1000), and some
+ * DSH builds register no exporters at all — without a persistent sink, audit lines
+ * would vanish with the process. This appends one JSON line per record to
+ * `$DSH_HOME/logs/dsh-log-YYYY-MM-DD.jsonl` (~/.dsh when DSH_HOME is unset),
+ * rotating daily and by size (`-partN` siblings past maxLogFileSizeBytes) and cleaning
+ * up files older than logRetentionDays. Best effort: registration and write failures are
+ * contained so a broken sink can never mask the business outcome (spec §5.6 spirit).
+ *
+ * Returns whether the sink is actually live, so the caller can warn loudly instead of
+ * letting the plugin claim durability it does not have.
+ * @param ctx - registrant context carrying the logger service.
+ * @param cfg - resolved plugin config (rotation + retention budgets).
+ * @returns live-sink status for the boot record.
+ */
+function registerPersistentAuditExporter(ctx: Context, cfg: ResolvedConfig): PersistentSinkStatus {
+  const service = ctx.logger as unknown as {
+    exporter?: (exporter: { levels?: Record<string, number>; export(message: { ts: number; type: string; name: string; args: unknown[] }): void }) => unknown
+  } | undefined
+  if (!service || typeof service.exporter !== 'function') {
+    return { persistent: false, reason: 'logger exporter API unavailable in this build (memory buffer only)' }
+  }
+
+  let logDir = ''
+  try {
+    const home = process.env.DSH_HOME?.trim() || path.join(os.homedir(), '.dsh')
+    logDir = path.join(home, 'logs')
+  } catch {
+    return { persistent: false, reason: 'could not resolve DSH_HOME / home directory' }
+  }
+
+  // Rotation (P1): daily files `<name>-YYYY-MM-DD.jsonl`; when one grows past
+  // maxLogFileSizeBytes a `-part2`/`-part3` sibling is started. Retention cleanup
+  // (delete same-prefix files older than logRetentionDays) runs at most once per minute.
+  const state = { file: '', bytes: 0, lastCleanup: 0 }
+  // Run-time sink health. `dropped` counts records the sink failed to persist since
+  // the last successful write; `lastWarn` throttles the stderr notice to once a minute.
+  const health = { dropped: 0, lastWarn: 0, degradedSince: 0 }
+
+  const dayStamp = (): string => {
+    const d = new Date()
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+  }
+
+  const resolveFile = (stamp: string): string => {
+    let n = 1
+    for (;;) {
+      const candidate = path.join(logDir, n === 1 ? `${name}-${stamp}.jsonl` : `${name}-${stamp}-part${n}.jsonl`)
+      let size = 0
+      try { size = statSync(candidate).size } catch { /* missing file → size 0 */ }
+      if (size < cfg.maxLogFileSizeBytes) return candidate
+      n += 1
+      if (n > 99) return path.join(logDir, `${name}-${stamp}-part${n}.jsonl`) // give up scanning
+    }
+  }
+
+  const cleanupExpired = (): void => {
+    try {
+      const cutoff = Date.now() - cfg.logRetentionDays * 86_400_000
+      for (const entry of readdirSync(logDir)) {
+        if (!entry.startsWith(`${name}-`) || !entry.endsWith('.jsonl')) continue
+        const m = entry.match(new RegExp(`^${name}-(\\d{4})-(\\d{2})-(\\d{2})(?:-part\\d+)?\\.jsonl$`))
+        if (!m) continue
+        const fileDate = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))
+        if (fileDate < cutoff) unlinkSync(path.join(logDir, entry))
+      }
+    } catch { /* cleanup is best effort */ }
+  }
+
+  const writeLine = (message: { ts: number; type: string; name: string; args: unknown[] }): void => {
+    if (message.name !== name || !Array.isArray(message.args) || message.args.length === 0) return
+    const first = message.args[0]
+    let payload: Record<string, unknown>
+    if (typeof first === 'string') {
+      try {
+        const parsed: unknown = JSON.parse(first)
+        // Persist our own structured lines: audit records (carry tool + sessionId/callId)
+        // and the plugin-started config line (carries event). Anything else is skipped.
+        if (typeof parsed !== 'object' || parsed === null || (!('tool' in parsed) && !('event' in parsed))) return
+        payload = parsed as Record<string, unknown>
+      } catch {
+        return
+      }
+    } else {
+      return
+    }
+    try {
+      const stamp = dayStamp()
+      if (state.lastCleanup === 0 || Date.now() - state.lastCleanup >= 60_000) {
+        state.lastCleanup = Date.now()
+        cleanupExpired()
+      }
+      // Rotate: new day → new file; current file over budget → next part sibling.
+      if (!state.file.startsWith(`${name}-${stamp}`) || state.bytes >= cfg.maxLogFileSizeBytes) {
+        state.file = resolveFile(stamp)
+        try { state.bytes = statSync(state.file).size } catch { state.bytes = 0 /* fresh file */ }
+      }
+      mkdirSync(logDir, { recursive: true })
+      const line = JSON.stringify({ ts: message.ts, level: message.type, ...payload }) + '\n'
+      appendFileSync(state.file, line, 'utf8')
+      state.bytes += Buffer.byteLength(line, 'utf8')
+      if (health.dropped > 0) {
+        // Recovered from a broken stretch: say how much was lost while the sink was
+        // down. Written from the SUCCESS path (not the failure path) so the notice is
+        // guaranteed to land — the sink is provably working again right here.
+        const notice = JSON.stringify({
+          ts: Date.now(),
+          level: 'WARN',
+          event: 'audit-sink-recovered',
+          tool: name,
+          pluginVersion: PLUGIN_VERSION,
+          schemaVersion: SCHEMA_VERSION,
+          droppedRecords: health.dropped,
+          degradedMs: Date.now() - health.degradedSince,
+        }) + '\n'
+        try {
+          appendFileSync(state.file, notice, 'utf8')
+          state.bytes += Buffer.byteLength(notice, 'utf8')
+          health.dropped = 0
+          health.degradedSince = 0
+        } catch { /* stay degraded; the notice is retried on the next successful write */ }
+      }
+    } catch (err) {
+      // Sink failure must never mask the business outcome (spec §5.6) — but it must
+      // not be invisible either. A sink that dies mid-run used to leave NO trace, so
+      // an operator reading a truncated file would conclude "no calls happened".
+      health.dropped += 1
+      if (health.degradedSince === 0) health.degradedSince = Date.now()
+      if (Date.now() - health.lastWarn >= 60_000) {
+        health.lastWarn = Date.now()
+        try {
+          // stderr, deliberately NOT the logger: this sink IS the logger's only
+          // persistent output, so reporting the failure through it would recurse.
+          process.stderr.write(`[${name}] audit sink write failed (${health.dropped} record(s) dropped so far): ${err instanceof Error ? err.message : String(err)}\n`)
+        } catch { /* stderr is best effort */ }
+      }
+    }
+  }
+
+  try {
+    service.exporter({
+      levels: { [name]: 1 }, // INFO (1) and above, our channel only
+      export: writeLine,
+    })
+  } catch (err) {
+    // Registration is best effort — the in-memory buffer sink still applies, but the
+    // caller must hear about it (a silent downgrade is how audit trails disappear).
+    return { persistent: false, reason: `exporter registration failed: ${err instanceof Error ? err.message : String(err)}` }
+  }
+  return { persistent: true, logDir }
+}
+
+/**
+ * Coerce model-supplied header values (the schema allows any JSON value) into
+ * the string map `fetch` requires: null/undefined entries are dropped, every
+ * other value is stringified. Keys are untouched, so masking still catches
+ * sensitive header names on this map; stringification never alters a real
+ * credential's value.
+ */
+function normalizeHeaders(headers?: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    if (value === null || value === undefined) continue
+    out[key] = String(value)
+  }
+  return out
+}
+
+/**
+ * Coerce model-supplied query values (the schema allows any JSON value) into the
+ * string map the URL encoder needs: null/undefined entries are dropped, every
+ * other value is stringified. Keys are untouched, so masking still catches
+ * sensitive parameter names on this map.
+ */
+function normalizeQuery(query?: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value === null || value === undefined) continue
+    out[key] = String(value)
+  }
+  return out
+}
+
+/**
+ * Narrow a core-produced log segment to the record field type. The core module
+ * is SDK-free and types its JSON-safe output as `unknown`; this adapter knows
+ * by construction that masking/truncation only ever yields JSON values.
+ */
+function asJsonSegment(value: unknown): AuditJsonValue {
+  return value as AuditJsonValue
+}
+
+/**
+ * Strip a URL down to origin + path, dropping the query string and any userinfo.
+ * Used by the masking-failure fallback: credentials are commonly smuggled in
+ * `?token=…`, so a fallback must never echo the full URL into the log (spec §5.3).
+ * @param url - the raw request URL.
+ * @returns origin+path, or a marker when the URL does not parse.
+ */
+function bareUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    return `${parsed.origin}${parsed.pathname}`
+  } catch {
+    return '(unparseable url)'
+  }
+}
+
+/**
+ * Build the masked + truncated REQUEST log segment for one start/finished record.
+ * Never throws: the start record is the only place this channel holds something
+ * the trajectory structurally cannot (a call that has begun but not returned), so
+ * a failure inside the masking pipeline must not cost us that record — we fall
+ * back to a caller-supplied minimal, credential-free mirror instead.
+ * @param raw - the raw request params to mask.
+ * @param fallback - minimal credential-free segment used when masking throws.
+ * @param maxBytes - byte budget from plugin config.
+ * @returns a JSON-safe request segment.
+ */
+function maskRequestForLog(raw: unknown, fallback: AuditJsonValue, maxBytes: number): AuditJsonValue {
+  try {
+    return asJsonSegment(truncateJson(maskSensitive(raw), maxBytes))
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * Build the script-output log segment from only the DEFINED fields. DSH rejects
+ * tool results that are not lossless JSON (undefined-valued keys fail the
+ * stringify round-trip), so refusal/timeout paths — which carry no exitCode or
+ * captured output at all — must omit those keys rather than set them undefined.
+ */
+function scriptOutputSegment(result: { exitCode?: number; stdout?: string; stderr?: string; interpreter?: string }): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  if (result.interpreter !== undefined) out.interpreter = result.interpreter
+  if (result.exitCode !== undefined) out.exitCode = result.exitCode
+  if (result.stdout !== undefined) out.stdout = result.stdout
+  if (result.stderr !== undefined) out.stderr = result.stderr
+  return out
+}
+
+/**
+ * Spec §3 mandates a UUID v4 per invocation, so callId is ALWAYS freshly
+ * generated; the platform's own exec.callId (when present) rides along as
+ * `dshCallId` for joining with the surrounding tool/call|tool/result events.
+ */
+function dshCallIdOf(exec: { callId?: unknown }): string | undefined {
+  return exec.callId !== undefined && String(exec.callId) !== '' ? String(exec.callId) : undefined
+}
+
+/**
+ * Register both tools on `ctx.tools` with their audit wiring.
+ * @param ctx - registrant context carrying the tool registry and logger service.
+ * @param config - deployment config from the profile patch entry (defaults applied).
+ */
+export function apply(ctx: Context, config: Config): void {
+  const cfg = config as ResolvedConfig
+  assertPositiveInteger('defaultTimeoutMs', cfg.defaultTimeoutMs)
+  assertPositiveInteger('maxTimeoutMs', cfg.maxTimeoutMs)
+  assertPositiveInteger('maxReqLogBytes', cfg.maxReqLogBytes)
+  assertPositiveInteger('maxRespLogBytes', cfg.maxRespLogBytes)
+  assertPositiveInteger('maxOutputLogBytes', cfg.maxOutputLogBytes)
+  assertPositiveInteger('maxResponseBytes', cfg.maxResponseBytes)
+  assertPositiveInteger('maxRequestBytes', cfg.maxRequestBytes)
+  assertPositiveInteger('logRetentionDays', cfg.logRetentionDays)
+  assertPositiveInteger('maxLogFileSizeBytes', cfg.maxLogFileSizeBytes)
+  if (cfg.maxTimeoutMs < cfg.defaultTimeoutMs) {
+    // The ceiling must not silently make the configured default unreachable.
+    throw new Error(`dsh-log: maxTimeoutMs (${cfg.maxTimeoutMs}) must be >= defaultTimeoutMs (${cfg.defaultTimeoutMs})`)
+  }
+  if (cfg.scriptAllowDir.trim() === '') {
+    // Fail loud at boot: a script tool with no allow dir is a misconfiguration,
+    // not a runtime surprise.
+    throw new Error('dsh-log: scriptAllowDir is required (script whitelist directory)')
+  }
+
+  // Channel-1 durability: persist host audit lines to $DSH_HOME/logs/<name>-YYYY-MM-DD.jsonl
+  // (the built-in logger buffer alone would lose them at process exit).
+  const sink = registerPersistentAuditExporter(ctx, cfg)
+
+  // Whitelist hygiene (spec §5.1): the gate compares host strings, so it can never
+  // notice that a whitelisted host IS the cloud metadata service or an intranet box.
+  // Classifying the entries once at boot is free and makes the risk explicit in the
+  // log the operator already reads — "why was a static-looking whitelist dangerous?"
+  // is answered by the same line that states the config.
+  const allowlistRisks = inspectAllowHosts(cfg.apiAllowHosts)
+  const dangerousHosts = allowlistRisks.filter(risk => HOST_RISK_SEVERITY[risk.tier] === 'WARN')
+
+  // P1 ops: one startup record so operators can see the effective config at a glance
+  // (persisted to the same JSONL via the exporter registered above; non-sensitive values only).
+  // It also carries whether the persistent sink is live — the log itself answers
+  // "are these lines actually on disk?" instead of leaving it to guesswork.
+  try {
+    const log = ctx.logger(name)
+    log.info(JSON.stringify({
+      event: 'plugin-started',
+      tool: name,
+      pluginVersion: PLUGIN_VERSION,
+      level: 'INFO',
+      schemaVersion: SCHEMA_VERSION,
+      persistentLog: sink.persistent,
+      ...(sink.persistent ? { logDir: sink.logDir } : { downgradeReason: sink.reason }),
+      allowlist: {
+        entries: cfg.apiAllowHosts.length,
+        risks: allowlistRisks.map(risk => ({ host: risk.host, tier: risk.tier })),
+        scope: 'static literal/name-suffix check; a public name that RESOLVES to a private address is not detectable without DNS',
+      },
+      config: {
+        apiAllowHosts: cfg.apiAllowHosts,
+        scriptAllowDir: cfg.scriptAllowDir,
+        scriptWorkingDir: cfg.scriptWorkingDir === '' ? cfg.scriptAllowDir : cfg.scriptWorkingDir,
+        defaultTimeoutMs: cfg.defaultTimeoutMs,
+        maxTimeoutMs: cfg.maxTimeoutMs,
+        maxReqLogBytes: cfg.maxReqLogBytes,
+        maxRespLogBytes: cfg.maxRespLogBytes,
+        maxOutputLogBytes: cfg.maxOutputLogBytes,
+        maxResponseBytes: cfg.maxResponseBytes,
+        maxRequestBytes: cfg.maxRequestBytes,
+        logRetentionDays: cfg.logRetentionDays,
+        maxLogFileSizeBytes: cfg.maxLogFileSizeBytes,
+      },
+    }))
+    if (dangerousHosts.length > 0) {
+      // A warning, not a refusal: whitelisting 127.0.0.1 is ordinary local verification,
+      // and an operator may have a legitimate reason to reach an intranet API. But a
+      // metadata/link-local/private target is one SSRF away from handing over instance
+      // credentials, so it must never be a quiet line in a config dump.
+      log.warn(JSON.stringify({
+        event: 'allowlist-risk',
+        tool: name,
+        pluginVersion: PLUGIN_VERSION,
+        level: 'WARN',
+        schemaVersion: SCHEMA_VERSION,
+        risks: dangerousHosts,
+        impact: 'a whitelisted private/link-local/metadata host lets this tool reach intranet services or cloud instance credentials',
+      }))
+    }
+    if (!sink.persistent) {
+      // Loud degradation notice: with no exporter the plugin can only buffer in memory,
+      // so every audit line dies with the process. A silent downgrade is how an audit
+      // trail quietly disappears — say it out loud instead.
+      log.warn(JSON.stringify({
+        event: 'exporter-unavailable',
+        tool: name,
+        pluginVersion: PLUGIN_VERSION,
+        level: 'WARN',
+        schemaVersion: SCHEMA_VERSION,
+        reason: sink.reason,
+        impact: 'audit records stay in the in-memory log buffer only and are lost at process exit',
+      }))
+    }
+  } catch { /* a broken sink must never block plugin boot */ }
+
+  const emitHost = createHostAuditSink(ctx)
+
+  /**
+   * Build one audit record, push it to the host log, and return it for embedding
+   * in the result. Every record of one invocation shares `sessionId` + `callId`
+   * and carries a 1-based `seq` (1 = start, 2 = terminal) so a reader can tell a
+   * complete call from one that lost a record.
+   */
+  const makeEmit = (exec: { callId?: unknown; agent?: { session?: { id?: unknown } } | undefined }) => {
+    const sessionId = sessionIdOf(exec)
+    const callId = generateCallId() // spec §3: UUID v4 per invocation, always
+    const dshCallId = dshCallIdOf(exec)
+    let seq = 0
+    return (record: Omit<AuditRecord, 'sessionId' | 'callId' | 'seq' | 'tool' | 'schemaVersion'> & { tool: string }): AuditRecord => {
+      seq += 1
+      const full: AuditRecord = { sessionId, callId, ...(dshCallId === undefined ? {} : { dshCallId }), schemaVersion: SCHEMA_VERSION, seq, ...record }
+      emitHost(full)
+      return full
+    }
+  }
+
+  // ====================== Tool: call_external_api ======================
+  ctx.tools.register(defineTool({
+    name: TOOL_API,
+    description:
+      'Call an external HTTP API (GET/POST/PUT/PATCH/DELETE/HEAD). Only hosts listed in the plugin '
+      + 'whitelist are allowed; requests time out automatically. Extra query parameters are merged into '
+      + 'the URL with proper encoding. Every call emits a structured audit record (masked request, '
+      + 'truncated response, costMs, status code, errorType) that is persisted with this tool result and '
+      + 'written to the host log.',
+    parameters: {
+      url: { type: 'string', required: true, description: 'Request URL; host must be in api_allow_hosts' },
+      method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'], default: 'GET', description: 'HTTP method' },
+      headers: { type: 'object', additionalProperties: true, description: 'Request headers (string map); sensitive values are masked in logs only' },
+      query: { type: 'object', additionalProperties: true, description: 'Extra query parameters merged into the URL with proper percent-encoding; sensitive names are masked in logs only' },
+      body: { type: 'json', description: 'Request body for POST/PUT/PATCH/DELETE. Objects/arrays are JSON-encoded; a string is sent verbatim (e.g. form-urlencoded). Masked + truncated in logs only' },
+      timeoutMs: { type: 'integer', description: 'Per-call timeout override in ms; clamped to maxTimeoutMs (default 120000)' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          status: { type: 'integer', description: 'HTTP status code on transport success' },
+          responseHeaders: { type: 'object', additionalProperties: true, description: 'Response headers summary (byte-bounded); includes location on a 3xx' },
+          data: { type: 'json', description: 'Parsed response body (JSON when possible, raw text otherwise)' },
+          error: { type: 'string', description: 'Refusal/timeout/network/internal failure detail' },
+          audit: { type: 'object', additionalProperties: true, required: true, description: 'Structured audit record (masked + truncated); persisted with this result for Trajectory replay' },
+        },
+      },
+      render: (_args, value) => {
+        // The output schema types `audit` as an open JSON object — narrow defensively.
+        const audit = value.audit as AuditRecord
+        return [{
+          type: 'text',
+          text: value.ok
+            ? `API ${value.status} in ${audit.costMs}ms\n${JSON.stringify(value.audit)}`
+            : `API failed [${String(audit.errorType)}]: ${value.error ?? 'unknown error'}\n${JSON.stringify(value.audit)}`,
+        }]
+      },
+    },
+    // Top-level try/catch (spec §5.6): even a plugin-internal exception yields an
+    // INTERNAL_ERROR audit record — the audit trail never silently vanishes.
+    // Parameter types are contravariantly widened (`unknown`) over the schema-inferred
+    // JSON value shapes: the registry validates before dispatch, this accepts anything.
+    async execute(args: { url: string; method?: HttpMethod; headers?: Record<string, unknown>; query?: Record<string, unknown>; body?: unknown; timeoutMs?: number }, exec) {
+      const startTime = Date.now()
+      const emit = makeEmit(exec)
+      // Declared before the try so the INTERNAL_ERROR catch path can reference it.
+      let maskedRequest: AuditJsonValue | undefined
+
+      try {
+        // Resolve the effective timeout ONCE, log it, and hand the same number to the
+        // core: the audit record then states the budget that was truly applied, not the
+        // one that was requested and possibly clamped (spec §5.4).
+        const timeoutMs = resolveTimeoutMs(args.timeoutMs, cfg.defaultTimeoutMs, cfg.maxTimeoutMs)
+        const query = normalizeQuery(args.query)
+        const params: ApiCallParams = {
+          url: args.url,
+          method: args.method ?? 'GET',
+          headers: normalizeHeaders(args.headers),
+          query,
+          body: args.body,
+          timeoutMs,
+        }
+
+        // "This call was aimed at the metadata service" is the one fact an incident
+        // review needs and the one fact a URL never states out loud. Classified
+        // statically, so it costs no DNS lookup on the request path.
+        const hostRisk = (() => {
+          const host = hostOfUrl(params.url)
+          return host === null ? null : classifyHost(host)
+        })()
+
+        // Mask + truncate the LOG copy only — the live request below uses raw params.
+        // Never throws (the start record comes next and must not be lost). The URL is
+        // masked as a STRING too: `?token=…` and userinfo would otherwise escape
+        // key-based masking entirely (spec §5.3).
+        // `addressClass` sits high in the object on purpose: it is ~15 bytes, and if a
+        // tight maxReqLogBytes truncates the tail it must not be what falls off. Only
+        // the short class rides here — the explanation lives in the boot record.
+        // The name deliberately avoids the substrings `ak`/`sk`: the masker folds key
+        // names before keyword matching, so `hostRiskTier` would itself be redacted
+        // ("hostri[sk]tier"). See README's masking notes.
+        maskedRequest = maskRequestForLog(
+          {
+            url: maskUrlQuery(params.url),
+            method: params.method,
+            ...(hostRisk === null ? {} : { addressClass: hostRisk.tier }),
+            ...(Object.keys(query).length === 0 ? {} : { query: maskSensitive(query) }),
+            headers: params.headers ?? {},
+            body: params.body === undefined ? {} : params.body,
+            timeoutMs,
+          },
+          { url: bareUrl(params.url), method: params.method ?? 'GET', note: 'request masking failed' },
+          cfg.maxReqLogBytes,
+        )
+
+        // Event 1 (spec §4.1): start — INFO with the masked request. The trajectory
+        // channel has no counterpart for this record: it only ever receives the
+        // terminal one, so a call that begins and never returns is invisible there.
+        emit({ tool: TOOL_API, level: 'INFO', phase: 'start', request: maskedRequest, costMs: Date.now() - startTime })
+
+        const result = await callExternalApi(
+          params,
+          { apiAllowHosts: cfg.apiAllowHosts, defaultTimeoutMs: cfg.defaultTimeoutMs, maxTimeoutMs: cfg.maxTimeoutMs, maxResponseBytes: cfg.maxResponseBytes, maxRequestBytes: cfg.maxRequestBytes },
+          exec.signal,
+        )
+
+        if (result.ok) {
+          // Event 2 (spec §4.1): finished — INFO with costMs, HTTP code, truncated response summary.
+          // The response is masked too (spec §5.3: logs must never store credentials in
+          // plaintext) — an API that echoes request headers back would otherwise leak them.
+          const record = emit({
+            tool: TOOL_API,
+            level: 'INFO',
+            phase: 'finished',
+            request: maskedRequest,
+            response: asJsonSegment(truncateJson(maskSensitive({ status: result.status, headers: result.headers ?? {}, data: result.data }), cfg.maxRespLogBytes)),
+            costMs: Date.now() - startTime,
+            code: result.status,
+          })
+          // `data` is omitted when the response body was empty — undefined keys break
+          // DSH's lossless-JSON result validation (stringify round-trip).
+          return {
+            ok: true as const,
+            status: result.status,
+            ...(result.headers !== undefined ? { responseHeaders: result.headers } : {}),
+            ...(result.data !== undefined ? { data: result.data } : {}),
+            audit: record,
+          }
+        }
+
+        // Event 3 (spec §4.1): error — ERROR with classified errorType (response omitted per spec §3).
+        // The free-text diagnosis goes through the same masking path as the request
+        // segment: `network failure: …` routinely quotes the full URL, so a credential
+        // hiding in `?token=…` would otherwise ride into the record — and into the
+        // caller-visible error — in plaintext (spec §5.3).
+        const errorText = maskTextForLog(result.error ?? 'unknown error')
+        const record = emit({
+          tool: TOOL_API,
+          level: 'ERROR',
+          phase: 'error',
+          request: maskedRequest,
+          costMs: Date.now() - startTime,
+          ...(result.status !== undefined ? { code: result.status } : {}),
+          errorType: result.errorType as ErrorType,
+          error: errorText,
+        })
+        return { ok: false as const, ...(result.status !== undefined ? { status: result.status } : {}), error: errorText, audit: record }
+      } catch (err) {
+        // Plugin-internal failure (spec §5.6): INTERNAL_ERROR, still audited.
+        // An exception message is arbitrary text and can quote a URL — mask it too.
+        const errorText = maskTextForLog(`internal error: ${err instanceof Error ? err.message : String(err)}`)
+        const record = emit({
+          tool: TOOL_API,
+          level: 'ERROR',
+          phase: 'error',
+          // If the log pipeline itself threw before masking completed, fall back to a
+          // minimal request segment — the audit record must stay lossless JSON.
+          request: maskedRequest ?? { url: bareUrl(args.url) },
+          costMs: Date.now() - startTime,
+          errorType: ERROR_TYPES.INTERNAL_ERROR,
+          error: errorText,
+        })
+        return { ok: false as const, error: errorText, audit: record }
+      }
+    },
+  }))
+
+  // ====================== Tool: run_external_script ======================
+  ctx.tools.register(defineTool({
+    name: TOOL_SCRIPT,
+    description:
+      'Execute a script that lives inside the configured whitelist directory (pass ONLY the file '
+      + 'name — paths are refused). The interpreter is chosen from the file extension (.py/.js/.mjs/'
+      + '.cjs/.sh/.bash/.ps1/.bat/.cmd, or a directly executable file), so scripts need no executable '
+      + 'bit and run on Windows too. The process group is killed on timeout; stdout/stderr are '
+      + 'byte-capped. Every run emits a structured audit record persisted with this tool result.',
+    parameters: {
+      scriptName: { type: 'string', required: true, description: 'Bare script file name inside script_allow_dir — no paths, no separators' },
+      args: { type: 'array', items: { type: 'string' }, description: 'Script arguments, passed verbatim as argv (never through a shell)' },
+      stdin: { type: 'string', description: 'Text piped to the script stdin, then EOF. Only its byte count is logged (it may hold a credential)' },
+      timeoutMs: { type: 'integer', description: 'Per-call timeout override in ms; clamped to maxTimeoutMs (default 120000)' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          exitCode: { type: 'integer', description: 'Process exit code' },
+          interpreter: { type: 'string', description: 'Interpreter that actually ran the file (e.g. node, python, cmd.exe)' },
+          stdout: { type: 'string', description: 'Captured stdout, byte-capped with [TRUNCATED] marker when capped' },
+          stderr: { type: 'string', description: 'Captured stderr, byte-capped with [TRUNCATED] marker when capped' },
+          error: { type: 'string', description: 'Refusal/timeout/non-zero-exit/internal failure detail' },
+          audit: { type: 'object', additionalProperties: true, required: true, description: 'Structured audit record (masked + truncated); persisted with this result for Trajectory replay' },
+        },
+      },
+      render: (_args, value) => {
+        // The output schema types `audit` as an open JSON object — narrow defensively.
+        const audit = value.audit as AuditRecord
+        const scriptName = typeof audit.request === 'object' && audit.request !== null
+          ? (audit.request as { scriptName?: unknown }).scriptName
+          : undefined
+        const via = value.interpreter === undefined ? '' : ` via ${value.interpreter}`
+        return [{
+          type: 'text',
+          text: value.ok
+            ? `script ${String(scriptName ?? '(unknown)')}${via} exited 0 in ${audit.costMs}ms\n${JSON.stringify(value.audit)}`
+            : `script failed [${String(audit.errorType)}]: ${value.error ?? 'unknown error'}\n${JSON.stringify(value.audit)}`,
+        }]
+      },
+    },
+    async execute(args: { scriptName: string; args?: string[]; stdin?: string; timeoutMs?: number }, exec) {
+      const startTime = Date.now()
+      const emit = makeEmit(exec)
+
+      try {
+        // Same "resolve once, log the effective value" rule as the API tool. stdin is
+        // logged as a BYTE COUNT only — it is a plausible carrier of a credential and
+        // has no key names for the keyword masker to match against.
+        const timeoutMs = resolveTimeoutMs(args.timeoutMs, cfg.defaultTimeoutMs, cfg.maxTimeoutMs)
+        const stdinBytes = typeof args.stdin === 'string' ? Buffer.byteLength(args.stdin, 'utf8') : undefined
+        const requestSegment = {
+          scriptName: args.scriptName,
+          args: args.args ?? [],
+          timeoutMs,
+          ...(stdinBytes === undefined ? {} : { stdinBytes }),
+        }
+
+        // Event 1 (spec §4.2): start — INFO with the (already safe, file-name-only)
+        // request. Like the API tool, this record has no trajectory counterpart.
+        const maskedRequest = maskRequestForLog(
+          requestSegment,
+          { scriptName: args.scriptName, note: 'request masking failed' },
+          cfg.maxReqLogBytes,
+        )
+        emit({ tool: TOOL_SCRIPT, level: 'INFO', phase: 'start', request: maskedRequest, costMs: Date.now() - startTime })
+
+        const result = await runExternalScript(
+          { scriptName: args.scriptName, args: args.args, stdin: args.stdin, timeoutMs },
+          {
+            scriptAllowDir: cfg.scriptAllowDir,
+            defaultTimeoutMs: cfg.defaultTimeoutMs,
+            maxTimeoutMs: cfg.maxTimeoutMs,
+            maxOutputLogBytes: cfg.maxOutputLogBytes,
+            scriptWorkingDir: cfg.scriptWorkingDir,
+          },
+          exec.signal,
+        )
+
+        if (result.ok) {
+          // Event 2: finished — INFO with costMs, exit code, interpreter, truncated outputs.
+          const record = emit({
+            tool: TOOL_SCRIPT,
+            level: 'INFO',
+            phase: 'finished',
+            request: maskedRequest,
+            response: asJsonSegment(truncateJson(scriptOutputSegment(result), cfg.maxRespLogBytes)),
+            costMs: Date.now() - startTime,
+            code: result.exitCode,
+          })
+          return {
+            ok: true as const,
+            exitCode: result.exitCode,
+            ...(result.interpreter !== undefined ? { interpreter: result.interpreter } : {}),
+            stdout: result.stdout,
+            stderr: result.stderr,
+            audit: record,
+          }
+        }
+
+        // Event 3: error — ERROR with classified errorType (outputs kept for traceability).
+        // Refusal/timeout paths carry no exitCode or captured output — those keys are
+        // omitted entirely so the result stays lossless JSON. The message is masked:
+        // spawn/launch failures echo interpreter paths and the caller's own argv back.
+        const errorText = maskTextForLog(result.error ?? 'unknown error')
+        const record = emit({
+          tool: TOOL_SCRIPT,
+          level: 'ERROR',
+          phase: 'error',
+          request: maskedRequest,
+          response: asJsonSegment(truncateJson(scriptOutputSegment(result), cfg.maxRespLogBytes)),
+          costMs: Date.now() - startTime,
+          ...(result.exitCode !== undefined ? { code: result.exitCode } : {}),
+          errorType: result.errorType as ErrorType,
+          error: errorText,
+        })
+        return {
+          ok: false as const,
+          ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
+          ...(result.interpreter !== undefined ? { interpreter: result.interpreter } : {}),
+          ...(result.stdout !== undefined ? { stdout: result.stdout } : {}),
+          ...(result.stderr !== undefined ? { stderr: result.stderr } : {}),
+          error: errorText,
+          audit: record,
+        }
+      } catch (err) {
+        // Plugin-internal failure (spec §5.6): INTERNAL_ERROR, still audited.
+        // An exception message is arbitrary text and can quote a URL — mask it too.
+        const errorText = maskTextForLog(`internal error: ${err instanceof Error ? err.message : String(err)}`)
+        const record = emit({
+          tool: TOOL_SCRIPT,
+          level: 'ERROR',
+          phase: 'error',
+          request: maskRequestForLog(
+            { scriptName: args.scriptName, args: args.args ?? [] },
+            { scriptName: args.scriptName, note: 'request masking failed' },
+            cfg.maxReqLogBytes,
+          ),
+          costMs: Date.now() - startTime,
+          errorType: ERROR_TYPES.INTERNAL_ERROR,
+          error: errorText,
+        })
+        return { ok: false as const, error: errorText, audit: record }
+      }
+    },
+  }))
+}