dsh-context-toolkit 0.0.0-stage → 0.1.0

package/lib/runner.js

@@ -0,0 +1,265 @@
+/**
+ * Sandboxed code/command execution.
+ *
+ * Everything here exists for one reason: a command or script can produce
+ * megabytes of output, while the answer a conversation needs is usually a few
+ * hundred bytes. The raw bytes are captured in this process and never returned;
+ * only the measured head/tail plus the byte count crosses back.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, statSync, writeFileSync, mkdtempSync, rmSync, mkdirSync } from 'node:fs'
+import { tmpdir, homedir } from 'node:os'
+import { join, extname, isAbsolute, resolve, dirname } from 'node:path'
+
+/**
+ * Locate the interpreters we can actually launch.
+ *
+ * process.execPath is NOT usable here: inside the harness it points at the host
+ * application binary, not at a scripting runtime. Each candidate is therefore
+ * probed on disk, and PATH names are kept as-is so the OS resolves them.
+ */
+let RUNTIME_CACHE = null
+
+function firstExisting(paths) {
+  for (const candidate of paths) {
+    if (typeof candidate !== 'string' || !candidate) continue
+    if (!/[\\/]/.test(candidate)) return candidate      // a bare name: let PATH resolve it
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+export function probeRuntimes() {
+  if (RUNTIME_CACHE !== null) return RUNTIME_CACHE
+  const steps = (process.env.PATH || '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean)
+  const nodeNames = process.platform === 'win32' ? ['node.exe'] : ['node']
+  const fromPath = steps.flatMap((dir) => nodeNames.map((n) => join(dir, n)))
+  const node = firstExisting([
+    process.env.CTK_NODE,
+    process.env.NODE_BINARY,
+    'C:\\Program Files\\nodejs\\node.exe',
+    join(homedir(), 'AppData', 'Local', 'Programs', 'nodejs', 'node.exe'),
+    ...fromPath,
+    'node',
+  ])
+  const bun = firstExisting([
+    process.env.CTK_BUN,
+    join(homedir(), '.bun', 'bin', process.platform === 'win32' ? 'bun.exe' : 'bun'),
+    'bun',
+  ])
+  const shell = process.platform === 'win32'
+    ? firstExisting([
+        join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+        'powershell',
+      ])
+    : firstExisting(['/bin/bash', 'bash', '/bin/sh', 'sh'])
+  const found = {}
+  if (node) { found.javascript = node; found.typescript = node }
+  if (bun) found.bun = bun
+  if (shell) found.shell = shell
+  RUNTIME_CACHE = found
+  return found
+}
+
+export function availableRuntimes() {
+  return Object.keys(probeRuntimes())
+}
+
+/** The shell plan a command runner should use on this platform. */
+export function shellPlan() {
+  if (process.platform === 'win32') {
+    const ps = probeRuntimes().shell || 'powershell'
+    return { command: ps, args: (code) => ['-NoProfile', '-NonInteractive', '-Command', code] }
+  }
+  return { command: probeRuntimes().shell || 'bash', args: (code) => ['-c', code] }
+}
+
+/**
+ * Run one child process, capturing stdout/stderr with a hard byte cap.
+ *
+ * The cap is applied on the fly: once a stream exceeds it, further chunks are
+ * counted but not retained. That keeps memory bounded even for a runaway
+ * command, while still reporting the true total size.
+ */
+export function runProcess(command, args, options = {}) {
+  const {
+    cwd = process.cwd(),
+    env = {},
+    timeoutMs = 120000,
+    maxCaptureBytes = 262144,
+    shell = false,
+    input = null,
+  } = options
+
+  return new Promise((settle) => {
+    let child
+    try {
+      child = spawn(command, args, {
+        cwd,
+        shell,
+        env: childEnv(env),
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+      })
+    } catch (error) {
+      settle({ ok: false, error: String((error && error.message) || error), stdout: '', stderr: '', stdoutBytes: 0, stderrBytes: 0, exitCode: null, timedOut: false })
+      return
+    }
+
+    const state = { outBytes: 0, errBytes: 0, outKept: 0, errKept: 0, outCap: false, errCap: false }
+    const outChunks = []
+    const errChunks = []
+    let timedOut = false
+    let settled = false
+
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true
+          try { child.kill('SIGKILL') } catch { /* already gone */ }
+        }, timeoutMs)
+      : null
+
+    const collect = (chunk, isOut) => {
+      const size = chunk.length
+      if (isOut) {
+        state.outBytes += size
+        if (state.outKept < maxCaptureBytes) {
+          const room = maxCaptureBytes - state.outKept
+          outChunks.push(room >= size ? chunk : chunk.subarray(0, room))
+          state.outKept += Math.min(size, room)
+        } else state.outCap = true
+      } else {
+        state.errBytes += size
+        if (state.errKept < maxCaptureBytes) {
+          const room = maxCaptureBytes - state.errKept
+          errChunks.push(room >= size ? chunk : chunk.subarray(0, room))
+          state.errKept += Math.min(size, room)
+        } else state.errCap = true
+      }
+    }
+
+    child.stdout.on('data', (c) => collect(c, true))
+    child.stderr.on('data', (c) => collect(c, false))
+
+    const finish = (exitCode, signal, error) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      settle({
+        ok: !timedOut && error === undefined && exitCode === 0,
+        error,
+        exitCode,
+        signal: signal || null,
+        timedOut,
+        stdout: Buffer.concat(outChunks).toString('utf8'),
+        stderr: Buffer.concat(errChunks).toString('utf8'),
+        stdoutBytes: state.outBytes,
+        stderrBytes: state.errBytes,
+        stdoutTruncated: state.outCap || state.outKept < state.outBytes,
+        stderrTruncated: state.errCap || state.errKept < state.errBytes,
+        stdoutKeptBytes: state.outKept,
+      })
+    }
+
+    child.on('error', (error) => finish(null, null, String((error && error.message) || error)))
+    child.on('close', (code, signal) => finish(code, signal, undefined))
+
+    if (input !== null) {
+      try { child.stdin.end(String(input)) } catch { /* close races are fine */ }
+    } else {
+      try { child.stdin.end() } catch { /* ignore */ }
+    }
+  })
+}
+
+/**
+ * Build the environment a child process sees.
+ *
+ * The harness sandbox exports neither PATH entries for the interpreters we found
+ * nor TEMP/TMPDIR, so a plain {...process.env} spawn cannot run "node" by name
+ * even when we located the binary. This adds the directories we resolved, plus a
+ * working scratch dir, without discarding whatever the parent did export.
+ */
+function childEnv(extra) {
+  const env = { ...process.env, ...extra }
+  const dirs = []
+  const runtimes = probeRuntimes()
+  for (const key of ['javascript', 'bun', 'shell']) {
+    const bin = runtimes[key]
+    if (typeof bin === 'string' && /[\\/]/.test(bin)) dirs.push(dirname(bin))
+  }
+  const scratch = scratchDir()
+  dirs.push(scratch)
+  const sep = process.platform === 'win32' ? ';' : ':'
+  const existing = String(env.PATH || env.Path || '').split(sep).filter(Boolean)
+  env.PATH = [...new Set([...dirs, ...existing])].join(sep)
+  if (!env.TEMP) env.TEMP = scratch
+  if (!env.TMP) env.TMP = scratch
+  if (!env.TMPDIR) env.TMPDIR = scratch
+
+  if (process.platform === 'win32') {
+    // Measured: this sandbox exports PATHEXT as ".CPL" only and leaves COMSPEC
+    // empty. PowerShell then resolves no .exe at all — not even "cmd" — even
+    // though the file is on disk and PATH. Restoring both turns command lookup
+    // back on. Done only when the inherited value is unusable, so a normal
+    // environment is never overridden.
+    const systemRoot = env.SystemRoot || env.windir || 'C:\\Windows'
+    const wantedExt = '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.CPL'
+    const currentExt = String(env.PATHEXT || '')
+    const hasExe = /\\.EXE/i.test(currentExt)
+    if (!hasExe) env.PATHEXT = wantedExt
+    if (!env.COMSPEC) env.COMSPEC = join(systemRoot, 'System32', 'cmd.exe')
+    if (!env.SystemRoot) env.SystemRoot = systemRoot
+    if (!env.windir) env.windir = systemRoot
+  }
+  return env
+}
+
+/**
+ * Resolve a writable scratch directory.
+ *
+ * os.tmpdir() returns a bogus value ("undefined\temp") when TEMP/TMPDIR are not
+ * exported, which is exactly what happens inside the harness sandbox. So the
+ * candidates are probed in order and the first writable one wins.
+ */
+let SCRATCH_DIR = null
+export function scratchDir() {
+  if (SCRATCH_DIR !== null) return SCRATCH_DIR
+  const candidates = [
+    process.env.CTK_TMP,
+    process.env.TEMP,
+    process.env.TMP,
+    process.env.TMPDIR,
+    join(homedir(), 'AppData', 'Local', 'Temp'),
+    join(homedir(), '.cache', 'dsh-context-toolkit'),
+    '/tmp',
+    dirname(tmpdir()),
+  ]
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string' || !candidate.trim()) continue
+    if (/undefined/i.test(candidate)) continue
+    try {
+      mkdirSync(candidate, { recursive: true })
+      const probe = mkdtempSync(join(candidate, 'ctk-check-'))
+      rmSync(probe, { recursive: true, force: true })
+      SCRATCH_DIR = candidate
+      return SCRATCH_DIR
+    } catch { /* try the next candidate */ }
+  }
+  const fallback = process.cwd()
+  SCRATCH_DIR = fallback
+  return fallback
+}
+
+/** Write a script to a temp file so its real name shows up in stack traces. */
+export function withTempScript(extension, body, fn) {
+  const dir = mkdtempSync(join(scratchDir(), 'ctk-run-'))
+  const file = join(dir, 'script' + extension)
+  writeFileSync(file, body, 'utf8')
+  return Promise.resolve()
+    .then(() => fn(file))
+    .finally(() => { try { rmSync(dir, { recursive: true, force: true }) } catch { /* best effort */ } })
+}
+
+export const SANDBOX_TMP = () => mkdtempSync(join(scratchDir(), 'ctk-'))
+export { extname, isAbsolute, resolve, readFileSync, statSync, existsSync }

package/lib/store.js

@@ -0,0 +1,243 @@
+/**
+ * The local knowledge base.
+ *
+ * Large material is filed here and retrieved by section later, so the bytes
+ * never occupy the conversation in the meantime. The whole store rides on
+ * node:sqlite, whose FTS5 module ships with Node itself — no native build, no
+ * third-party package, which is what keeps this plugin installable anywhere.
+ *
+ * Layout: one database per workspace. Documents are split into chunks at
+ * heading boundaries so a search hit returns the relevant section rather than a
+ * whole file, and chunk text is indexed with BM25 ranking.
+ */
+import { DatabaseSync } from 'node:sqlite'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { join, basename, resolve } from 'node:path'
+
+const SCHEMA_VERSION = 1
+
+/** Split text into indexable chunks at markdown headings, keeping code fences intact. */
+export function chunkText(text, options = {}) {
+  const { maxChars = 1800, minChars = 1 } = options
+  const source = String(text || '')
+  if (!source.trim()) return []
+
+  const lines = source.split('\n')
+  const chunks = []
+  let heading = ''
+  let buffer = []
+  let size = 0
+  let inFence = false
+
+  const flush = () => {
+    const body = buffer.join('\n').trim()
+    if (body.length >= minChars) chunks.push({ heading, text: body })
+    buffer = []
+    size = 0
+  }
+
+  for (const line of lines) {
+    // A fence toggles raw mode: a "## " inside a code block is not a heading.
+    if (/^```/.test(line)) inFence = !inFence
+    const isHeading = !inFence && /^#{1,6}\s+/.test(line)
+    if (isHeading && size > 0) flush()
+    if (isHeading) heading = line.replace(/^#{1,6}\s+/, '').trim()
+    buffer.push(line)
+    size += line.length + 1
+    if (size >= maxChars && !inFence) flush()
+  }
+  flush()
+  return chunks
+}
+
+/** A stable id for a document path, so re-indexing replaces rather than duplicates. */
+export function documentKey(absPath) {
+  const normalized = resolve(String(absPath)).replace(/\\/g, '/').toLowerCase()
+  return createHash('sha256').update(normalized).digest('hex').slice(0, 24)
+}
+
+/**
+ * Build a readable excerpt centred on the first query term found.
+ *
+ * Slicing from the start of a chunk hides the very words that matched whenever
+ * the hit sits mid-chunk, which makes a search result useless for judging
+ * relevance. The window opens just before the match and is marked when it is
+ * not the beginning of the chunk.
+ */
+export function excerptAround(text, query, maxChars = 900) {
+  const body = String(text || '')
+  if (body.length <= maxChars) return body
+  const terms = String(query || '').split(/\s+/).filter((t) => t.length > 1)
+  let at = -1
+  for (const term of terms) {
+    const found = body.toLowerCase().indexOf(term.toLowerCase())
+    if (found >= 0 && (at < 0 || found < at)) at = found
+  }
+  if (at < 0) return body.slice(0, maxChars)
+  const back = Math.floor(maxChars * 0.3)
+  const start = Math.max(0, at - back)
+  const end = Math.min(body.length, start + maxChars)
+  return (start > 0 ? '…' : '') + body.slice(start, end) + (end < body.length ? '…' : '')
+}
+
+export function openStore(storageDir) {
+  mkdirSync(storageDir, { recursive: true })
+  const dbPath = join(storageDir, 'knowledge.db')
+  const db = new DatabaseSync(dbPath)
+
+  // The schema is created idempotently; an FTS5 virtual table backs retrieval.
+  db.exec(`
+    PRAGMA journal_mode = WAL;
+    CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+    CREATE TABLE IF NOT EXISTS documents (
+      doc_key TEXT PRIMARY KEY,
+      path TEXT NOT NULL,
+      title TEXT,
+      bytes INTEGER,
+      mtime_ms INTEGER,
+      chunks INTEGER,
+      indexed_at_ms INTEGER
+    );
+    CREATE VIRTUAL TABLE IF NOT EXISTS chunks USING fts5(
+      body,
+      doc_key UNINDEXED,
+      path UNINDEXED,
+      title UNINDEXED,
+      heading UNINDEXED,
+      ord UNINDEXED,
+      tokenize = 'unicode61'
+    );
+  `)
+  db.prepare('INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)').run('schema_version', String(SCHEMA_VERSION))
+  return makeApi(db, dbPath, storageDir)
+}
+
+/** Paths that are labels rather than disk locations must survive resolve(). */
+export function normalizeTarget(path) {
+  const value = String(path || '')
+  if (/^(text|memory|https?):/i.test(value)) return value
+  return resolve(value)
+}
+
+function makeApi(db, dbPath, storageDir) {
+  const insertChunk = db.prepare('INSERT INTO chunks(body, doc_key, path, title, heading, ord) VALUES (?, ?, ?, ?, ?, ?)')
+  const deleteChunks = db.prepare('DELETE FROM chunks WHERE doc_key = ?')
+  const upsertDoc = db.prepare(`INSERT OR REPLACE INTO documents
+    (doc_key, path, title, bytes, mtime_ms, chunks, indexed_at_ms) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+  const findDoc = db.prepare('SELECT * FROM documents WHERE doc_key = ?')
+
+  return {
+    /** File one document, replacing any earlier version of the same path. */
+    indexDocument({ path, title, text, mtimeMs }) {
+      const abs = normalizeTarget(path)
+      const key = documentKey(abs)
+      const body = String(text == null ? '' : text)
+      const chunks = chunkText(body)
+      const meta = findDoc.get(key)
+      const now = Date.now()
+
+      const write = db.prepare('BEGIN')
+      write.run()
+      try {
+        deleteChunks.run(key)
+        upsertDoc.run(key, abs, String(title || basename(abs)), Buffer.byteLength(body, 'utf8'),
+          Number(mtimeMs) || 0, chunks.length, now)
+        chunks.forEach((c, i) => insertChunk.run(c.text, key, abs, String(title || basename(abs)), c.heading || '', i))
+        db.prepare('COMMIT').run()
+      } catch (error) {
+        try { db.prepare('ROLLBACK').run() } catch { /* already rolled back */ }
+        throw error
+      }
+      return { key, path: abs, chunks: chunks.length, bytes: Buffer.byteLength(body, 'utf8'), replaced: Boolean(meta) }
+    },
+
+    /** Index a file straight from disk. */
+    indexFile(path, options = {}) {
+      const abs = normalizeTarget(path)
+      if (!existsSync(abs)) throw new Error('no such file: ' + abs)
+      const st = statSync(abs)
+      if (!st.isFile()) throw new Error('not a regular file: ' + abs)
+      const text = readFileSync(abs, 'utf8')
+      return this.indexDocument({ path: abs, title: options.title, text, mtimeMs: st.mtimeMs })
+    },
+
+    /**
+     * Search the knowledge base.
+     *
+     * BM25 ranks the chunks; results carry the heading so a caller can decide
+     * which section is worth opening in full.
+     */
+    search(queries, options = {}) {
+      const list = Array.isArray(queries) ? queries : [queries]
+      const { limit = 5, maxChars = 900 } = options
+      const results = []
+      for (const raw of list) {
+        const query = String(raw || '').trim()
+        if (!query) continue
+        // Quote each term so FTS5 treats user text as terms, not as operators.
+        const terms = query.split(/\s+/).filter(Boolean).map((t) => '"' + t.replace(/"/g, '""') + '"')
+        if (!terms.length) continue
+        const match = terms.join(' OR ')
+        let rows = []
+        try {
+          rows = db.prepare(`
+            SELECT body, path, title, heading, bm25(chunks) AS score
+            FROM chunks WHERE chunks MATCH ? ORDER BY score LIMIT ?
+          `).all(match, limit)
+        } catch (error) {
+          results.push({ query, error: String((error && error.message) || error), hits: [] })
+          continue
+        }
+        results.push({
+          query,
+          hits: rows.map((row) => {
+            const body = String(row.body || '')
+            return {
+              path: row.path,
+              title: row.title,
+              heading: row.heading,
+              snippet: excerptAround(body, query, maxChars),
+              score: Number(row.score),
+            }
+          }),
+        })
+      }
+      return results
+    },
+
+    /** Every document currently filed. */
+    list() {
+      return db.prepare('SELECT path, title, bytes, chunks, indexed_at_ms FROM documents ORDER BY indexed_at_ms DESC').all()
+        .map((r) => ({ path: r.path, title: r.title, bytes: r.bytes, chunks: r.chunks, indexedAt: r.indexed_at_ms }))
+    },
+
+    /** Remove documents by path, by key, or all of them. */
+    purge({ path, all = false } = {}) {
+      if (all) {
+        const count = db.prepare('SELECT COUNT(*) AS n FROM documents').get().n
+        db.exec('DELETE FROM chunks; DELETE FROM documents;')
+        return { removed: Number(count) || 0, scope: 'all' }
+      }
+      if (!path) return { removed: 0, scope: 'none' }
+      const key = documentKey(path)
+      const before = findDoc.get(key)
+      deleteChunks.run(key)
+      db.prepare('DELETE FROM documents WHERE doc_key = ?').run(key)
+      return { removed: before ? 1 : 0, scope: 'path', path: normalizeTarget(path) }
+    },
+
+    stats() {
+      const docs = db.prepare('SELECT COUNT(*) AS n FROM documents').get().n
+      const chunks = db.prepare('SELECT COUNT(*) AS n FROM chunks').get().n
+      const bytes = db.prepare('SELECT COALESCE(SUM(bytes),0) AS n FROM documents').get().n
+      return { documents: Number(docs) || 0, chunks: Number(chunks) || 0, bytes: Number(bytes) || 0, dbPath }
+    },
+
+    close() { try { db.close() } catch { /* already closed */ } },
+    _db: db,
+    _storageDir: storageDir,
+  }
+}
+
+export { SCHEMA_VERSION }

package/locale/en.json

@@ -0,0 +1,83 @@
+{
+  "meta": {
+    "title": "Context Toolkit",
+    "description": "Run code in a sandbox, file large material into a local searchable knowledge base, and block the fetches and whole-file reads that flood a conversation. Ships a live context-occupancy panel."
+  },
+  "strings": {
+    "title": "Context Toolkit",
+    "description": "Run code in a sandbox, file large material into a local searchable knowledge base, and block the fetches and whole-file reads that flood a conversation. Ships a live context-occupancy panel.",
+    "hint": "These switches apply immediately, no restart: the gate is read before every tool call.",
+    "routing": "Routing gate",
+    "routingHint": "Master switch. When on, every tool call passes through the gate before running.",
+    "denyCurlWget": "Block curl / wget",
+    "denyCurlWgetHint": "Both exist to paste whole responses into the conversation; blocked here, use ctk_fetch_and_index instead.",
+    "bashNudgeMinCommandBytes": "Long-command nudge (bytes)",
+    "bashNudgeMinCommandBytesHint": "Commands longer than this get a nudge toward ctk_batch_execute. 0 disables it.",
+    "maxReadBytesBeforeAsk": "Whole-file read nudge (bytes)",
+    "maxReadBytesBeforeAskHint": "Reading a file larger than this gets a nudge toward ctk_execute_file. 0 disables it.",
+    "trustedReadBasenames": "Filenames exempt from the read nudge",
+    "trustedReadBasenamesHint": "Comma separated; these may be read whole however large they are.",
+    "compressNudgeTokens": "Occupancy warning (tokens)",
+    "compressNudgeTokensHint": "At this surface occupancy the report suggests compaction. 0 disables it.",
+    "searchLimit": "Search result limit",
+    "searchLimitHint": "How many excerpts ctk_search returns per query.",
+    "snippetChars": "Excerpt size (chars)",
+    "snippetCharsHint": "Character ceiling on each excerpt from ctk_search.",
+    "fetchMaxBytes": "Per-page fetch ceiling (bytes)",
+    "fetchMaxBytesHint": "ctk_fetch_and_index keeps at most this many bytes of each page.",
+    "storageDir": "Knowledge-base root",
+    "storageDirHint": "Empty = <DSH_HOME>/context-toolkit.",
+    "toolsTitle": "Tool switches",
+    "toolsHint": "Enable or disable individual ctk_* tools.",
+    "overridden": "overridden",
+    "reset": "reset",
+    "readOnly": "This deployment is read-only.",
+    "unavailable": "The plugin is not loaded right now; it cannot be configured.",
+    "save": "Save",
+    "saving": "Saving…",
+    "saveFailed": "This deployment did not accept those values; they are kept for you to edit.",
+    "invalidNumber": "Numbers only; blank means the default.",
+    "note": "Gate switches apply immediately; reopen the page to confirm tool-switch changes.",
+    "ctxTitle": "Context occupancy",
+    "ctxLoading": "Reading…",
+    "ctxReload": "Refresh",
+    "ctxFailed": "Read failed: ",
+    "ctxNoSession": "No measurable projection in this session yet.",
+    "ctxStale": "Snapshot from the last real measurement ({time}): a page request has no session boundary; ask ctk_context_report in the conversation for a live reading.",
+    "ctxTotal": "{n} tokens total",
+    "ctxSurface": "{n} tokens on the surface",
+    "ctxBudget": "warning at {n} tokens",
+    "ctxOver": "Above the warning threshold — route bulk output through ctk_execute / ctk_index.",
+    "ctxUnder": "Below the warning threshold; nothing to do.",
+    "ctxSystem": "System prompt",
+    "ctxTools": "Tool schemas",
+    "ctxMessages": "Conversation",
+    "ctxEstimated": " (estimated)",
+    "ctxNodes": "Biggest contributors (top {n})",
+    "ctxLedger": "This plugin's ledger",
+    "ctxLedgerLine": "The gate blocked {n} calls, about {bytes} bytes kept out of context; the sandbox kept out {sandbox} bytes; {tools} ctk_* tools registered.",
+    "ctxKnowledge": "Knowledge base: {docs} documents / {chunks} chunks ({bytes} bytes)",
+    "ctxStorage": "Knowledge base at {path}",
+    "tools.execute": "ctk_execute (run code in the sandbox, return only the answer)",
+    "tools.executeHint": "For analysis where you want the conclusion, not the raw output.",
+    "tools.executeFile": "ctk_execute_file (run code over a file, return only the answer)",
+    "tools.executeFileHint": "Read a big file, compute over it, keep its bytes in the sandbox.",
+    "tools.batchExecute": "ctk_batch_execute (many commands in one call, per-command status)",
+    "tools.batchExecuteHint": "One call for many commands; only conclusions come back.",
+    "tools.index": "ctk_index (file large material into the local knowledge base)",
+    "tools.indexHint": "Archive long docs, logs or specs, then pull sections with ctk_search.",
+    "tools.search": "ctk_search (retrieve excerpts on demand, not the whole thing)",
+    "tools.searchHint": "Prefer this for material already in the knowledge base.",
+    "tools.fetchAndIndex": "ctk_fetch_and_index (fetch a page straight into the index)",
+    "tools.fetchAndIndexHint": "When a whole page would flood the conversation; curl/wget are gated.",
+    "tools.purge": "ctk_purge (delete indexed content — permanent)",
+    "tools.purgeHint": "Clears the knowledge base; permanent, so the call must confirm:true.",
+    "tools.stats": "ctk_stats (this plugin's savings ledger and knowledge usage)",
+    "tools.statsHint": "How much this plugin saved, and how much it filed.",
+    "tools.doctor": "ctk_doctor (self-check: runtimes, scratch dir, knowledge round-trip)",
+    "tools.doctorHint": "Run it first when a child process or indexing misbehaves.",
+    "tools.contextReport": "ctk_context_report (session context occupancy report)",
+    "tools.contextReportHint": "Lets the model ask for this session context occupancy and composition.",
+    "restart": "needs a restart"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,83 @@
+{
+  "meta": {
+    "title": "上下文工具箱",
+    "description": "在沙箱里跑代码、把大块材料归档成可检索的本地知识库、并挡住会灌满对话的抓取与整读。附一张实时上下文占用面板。"
+  },
+  "strings": {
+    "title": "上下文工具箱",
+    "description": "在沙箱里跑代码、把大块材料归档成可检索的本地知识库、并挡住会灌满对话的抓取与整读。附一张实时上下文占用面板。",
+    "hint": "下列开关即时生效，无需重启：门禁在每次工具调用前读取。",
+    "routing": "路由门禁",
+    "routingHint": "总开关。开启后，每次工具调用执行前都会经过门禁检查。",
+    "denyCurlWget": "硬拦 curl / wget",
+    "denyCurlWgetHint": "这两个工具的设计就是把整页内容塞进对话；拦掉，改用 ctk_fetch_and_index。",
+    "bashNudgeMinCommandBytes": "长命令引导阈值（字节）",
+    "bashNudgeMinCommandBytesHint": "命令超过这个长度时提示改用 ctk_batch_execute。填 0 表示不提示。",
+    "maxReadBytesBeforeAsk": "大文件整读引导阈值（字节）",
+    "maxReadBytesBeforeAskHint": "整读超过这个大小的文件时提示改用 ctk_execute_file。填 0 表示不提示。",
+    "trustedReadBasenames": "不受整读门禁限制的文件名",
+    "trustedReadBasenamesHint": "逗号分隔；这些文件即使很大也允许整读。",
+    "compressNudgeTokens": "占用提示阈值（tokens）",
+    "compressNudgeTokensHint": "表面占用达到此值时，占用报告给出压缩建议。填 0 表示不提示。",
+    "searchLimit": "检索返回条数上限",
+    "searchLimitHint": "ctk_search 每次查询返回的片段数上限。",
+    "snippetChars": "片段最大字符数",
+    "snippetCharsHint": "ctk_search 每个片段返回的字符上限，超出部分省略。",
+    "fetchMaxBytes": "单页抓取上限（字节）",
+    "fetchMaxBytesHint": "ctk_fetch_and_index 抓取单页的最大字节数，超出部分丢弃。",
+    "storageDir": "知识库根目录",
+    "storageDirHint": "留空 = <DSH_HOME>/context-toolkit。",
+    "toolsTitle": "工具开关",
+    "toolsHint": "逐个启用或停用 ctk_* 工具。",
+    "overridden": "已覆盖",
+    "reset": "恢复默认",
+    "readOnly": "本部署的设置为只读。",
+    "unavailable": "该插件当前未加载，暂时无法配置。",
+    "save": "保存",
+    "saving": "保存中…",
+    "saveFailed": "本部署没有接受这些值，已保留供你修改。",
+    "invalidNumber": "请填数字；留空表示使用默认值。",
+    "note": "门禁开关即时生效；工具开关改动后建议重开页面确认。",
+    "ctxTitle": "上下文情况",
+    "ctxLoading": "正在读取…",
+    "ctxReload": "刷新",
+    "ctxFailed": "读取失败：",
+    "ctxNoSession": "本会话暂无可测量的投影。",
+    "ctxStale": "以下为最近一次实测快照（{time}）：网页请求没有会话边界，实时值请在对话中调用 ctk_context_report。",
+    "ctxTotal": "总压力 {n} tokens",
+    "ctxSurface": "表面占用 {n} tokens",
+    "ctxBudget": "提示阈值 {n} tokens",
+    "ctxOver": "已超过提示阈值，建议把大块输出改走 ctk_execute / ctk_index。",
+    "ctxUnder": "低于提示阈值，暂不需要干预。",
+    "ctxSystem": "系统提示",
+    "ctxTools": "工具 schema",
+    "ctxMessages": "会话消息",
+    "ctxEstimated": "（估算）",
+    "ctxNodes": "占用大头（前 {n} 项）",
+    "ctxLedger": "本插件节约台账",
+    "ctxLedgerLine": "门禁已拦截 {n} 次，约 {bytes} 字节未进入上下文；沙箱保留 {sandbox} 字节；已注册 {tools} 个 ctk_* 工具。",
+    "ctxKnowledge": "知识库：{docs} 文档 / {chunks} 片段（{bytes} 字节）",
+    "ctxStorage": "知识库位置：{path}",
+    "tools.execute": "ctk_execute（在沙箱里跑代码，只把结论带回来）",
+    "tools.executeHint": "用于「只想要结论、不想让原始输出占满上下文」的分析型任务。",
+    "tools.executeFile": "ctk_execute_file（对某个文件跑代码，只回结论）",
+    "tools.executeFileHint": "适合读大文件后做统计或抽取，文件原文留在沙箱里。",
+    "tools.batchExecute": "ctk_batch_execute（一次跑多条命令，逐条状态）",
+    "tools.batchExecuteHint": "多条命令一次调用，只有结论回来。",
+    "tools.index": "ctk_index（把大块材料存进本地知识库）",
+    "tools.indexHint": "把长文档、日志、规范归档，之后用 ctk_search 按需取用。",
+    "tools.search": "ctk_search（按需检索知识库，取片段而非整份）",
+    "tools.searchHint": "知识库里已有的内容优先用它检索，不要整份读进来。",
+    "tools.fetchAndIndex": "ctk_fetch_and_index（抓网页并直接并入索引）",
+    "tools.fetchAndIndexHint": "抓整页网页又不让它淹没对话时用；curl/wget 会被门禁拦掉。",
+    "tools.purge": "ctk_purge（删除已索引内容，不可恢复）",
+    "tools.purgeHint": "清理知识库用；会永久删除，调用必须带 confirm:true。",
+    "tools.stats": "ctk_stats（节约台账与知识库用量）",
+    "tools.statsHint": "想知道这个插件省了多少、归档了多少时看它。",
+    "tools.doctor": "ctk_doctor（自检：运行时、临时目录、知识库往返）",
+    "tools.doctorHint": "出现异常（子进程跑不起来、索引失败）时先跑它定位。",
+    "tools.contextReport": "ctk_context_report（会话上下文占用报告）",
+    "tools.contextReportHint": "让模型可以主动查询本会话的上下文占用与构成。",
+    "restart": "需重启"
+  }
+}