feat(tree-sitter-bash): add a pure-TypeScript bash parser and an agent-core-v2 bashParser service

.changeset/bash-parser-service.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Add an internal bash parsing capability that turns shell command strings into syntax trees, in preparation for per-command permission analysis. No user-facing behavior change yet.

AGENTS.md

@@ -28,6 +28,7 @@ This is a TypeScript monorepo built for agent-assisted development. Keep the roo
 - `packages/kap-server`: the Kimi Code server, backed by the DI × Scope agent engine (`@moonshot-ai/agent-core-v2`). Exposes sessions over REST + WebSocket (`/api/v1` + `/api/v1/ws`); bootstrapped from `src/start.ts` and consumed by `apps/kimi-code`. The RPC surface is `/api/v1/debug/*` — a reflection dispatcher over the ENTIRE scoped DI registry (every Service callable, no whitelist; `src/transport/registerDebugRoutes.ts` + `serviceDispatcherRoutes.ts`), mounted only with `--debug-endpoints` on a loopback bind and gated by the global bearer auth; repo dev scripts pass the flag. Its transcript surface implements the op-batch sequencing contract: `TranscriptService.dispatchOps` assigns every dispatched batch a per-agent consecutive `seq` and retains it in a bounded in-memory journal (`TRANSCRIPT_OPS_JOURNAL_CAPACITY`, dies with the live store); WS `transcript.ops`/`transcript.reset` payloads carry the seq/watermark, a `transcript_since` subscription cursor (carried, with the per-agent grades, by the `subscribe_v2` control frame — the only transcript subscription channel; its agent-grained counterpart `unsubscribe_v2` detaches listed agents' streams, or the whole session's when `agent_ids` is absent, letting the detached agents' legacy events flow again) replays journaled batches instead of a baseline reset when the journal covers it, and `GET /sessions/{id}/transcript/ops?since_seq=` serves point-to-point catch-up (`complete: false` = journal can't cover or session cold → caller falls back to a full refresh). Beside the paged route, `GET /sessions/{id}/transcript/plan?agent_id=[&tool_call_id=]` projects an agent's ExitPlanMode plan info (content / path / options / review outcome; `tool_call_id` narrows to one call, omitted lists every recoverable plan) from the first available fact — the linked approval interaction's persisted request display, the live tool frame's display, or the tool result output text. The baseline `transcript.reset` itself is items-empty (`TRANSCRIPT_RESET_TAIL_TURNS = 0`): it carries only global state + the watermark + `has_more_older`, because history always pages in over REST. When a WS connection subscribes to the transcript protocol (grade ≠ `off` for an agent), the broadcaster suppresses the transcript-projected `session_event` types for that connection × agent (`TRANSCRIPT_PROJECTED_EVENT_TYPES` + `suppressedByTranscript` in `sessionEventBroadcaster.ts`; cursor replay via `getBufferedSince` applies the same filter). Suppression is only a per-connection send view — the journal still records everything, and connections without transcript grades are unaffected. The session's work aggregate behind `event.session.work_changed` (`busy` / `main_turn_active` / `pending_interaction` / `last_turn_reason`) is owned by the core's `ISessionActivityView` (`sessionActivity` domain, Session scope): the broadcaster only schedules the wire emission around turn frames (`busy:false` lands after `turn.ended`), and `resolveSessionFacts` (`src/routes/sessions.ts`) reads the same view — never fold per-agent activity at the edge. Delivery split on `/api/v1/ws`: global events (`session.meta.updated` and the `event.session.*` / `event.workspace.*` / `event.config.*` families, including every activated session's `event.session.work_changed`) fan out to EVERY established connection — `WsConnectionV1` registers itself via `broadcaster.addGlobalTarget` on construction and unregisters on close — while session/agent-grained events only reach connections subscribed to that session (subject to `agent_filter` and the transcript suppression above); transcript frames are a separate channel governed by the per-agent grades alone and bypass `agent_filter` entirely.
 - `packages/klient`: the client SDK — a contract-driven facade over agent-core-v2 with aggregated `global.*` / `session(id).*` / `agent(id).*` methods, zod validation on every call, and klient-level typed event forwarding. Transport is chosen once at creation via subpath entry (`@moonshot-ai/klient/ipc|memory`); both return the same `Klient`. The package also hosts the e2e suites: the legacy `/api/v1` live suites (`test/e2e/legacy/`) and the docker e2e runner (`pnpm --filter @moonshot-ai/klient docker:e2e`). See `packages/klient/AGENTS.md`.
 - `packages/server-e2e`: live e2e tests and scenarios against a running server (`KIMI_SERVER_URL`, default `http://127.0.0.1:58627`). See `packages/server-e2e/AGENTS.md`.
+- `packages/tree-sitter-bash`: a pure-TypeScript bash parser (no runtime deps, no wasm) that produces a syntax tree with tree-sitter-bash 0.25.0 named-node type names and UTF-16 code-unit offsets. `parse(source, { timeoutMs, maxNodes })` runs under a deterministic budget (default 50 ms / 50k nodes, plus per-chain recursion depth caps) and returns a discriminated `ParseResult` (`{ ok, rootNode, hasError }` or `{ ok: false, reason: 'aborted' }`) — callers must treat aborted/hasError trees as "cannot analyze" and degrade. Parser only, no safety judgments; consumers (e.g. Bash tool permission matching) live elsewhere. Known deviations from the reference are tracked in the package README's "Known differences" section, pinned by differential fixtures tested against the real `tree-sitter-bash` wasm (dev-only).
 
 ## Environment Requirements
 

apps/kimi-inspect/src/App.tsx

@@ -8,7 +8,9 @@
  * / State tabs), the chat column, and the right dock (`RightPanel`) merging
  * the transcript audit and the agent inspector under Audit / Agent tabs;
  * the `models` view is the full-width model catalog; the `services` view is
- * the full-width app-scope Service reflection (`AppServicesView`).
+ * the full-width app-scope Service reflection (`AppServicesView`); the
+ * `bash` view is the full-width `IBashParserService` playground
+ * (`BashParserView`).
  */
 
 import { useEffect, useState } from 'react';
@@ -17,6 +19,7 @@ import { ISessionLifecycleService } from '@moonshot-ai/agent-core-v2/app/session
 
 import type { AuditTrail } from './audit/trail';
 import { AppServicesView } from './components/AppServicesView';
+import { BashParserView } from './components/BashParserView';
 import { ChatView } from './components/ChatView';
 import { ModelCatalogView } from './components/ModelCatalogView';
 import { NavRail, type AppView } from './components/NavRail';
@@ -82,6 +85,8 @@ export function App() {
         <NavRail view={view} onChange={setView} />
         {view === 'services' ? (
           <AppServicesView />
+        ) : view === 'bash' ? (
+          <BashParserView />
         ) : view === 'models' ? (
           <ModelCatalogView
             onOpenSession={(id) => {

apps/kimi-inspect/src/components/BashParserView.tsx

@@ -0,0 +1,279 @@
+/**
+ * Bash Parser view — a playground for the App-scope `IBashParserService`
+ * (the `bashParser` domain, a thin adapter over `@moonshot-ai/tree-sitter-bash`).
+ *
+ *   left:  the bash source textarea plus the parse budget (timeoutMs /
+ *          maxNodes, empty = package default); the `examples…` dropdown
+ *          fills the textarea with curated snippets from the parser's own
+ *          differential fixtures;
+ *   right: the parse result — status badges (hasError / aborted / node
+ *          count) and the syntax tree, one row per node with its type,
+ *          UTF-16 range and (for leaves) the source text. Anonymous tokens
+ *          are dimmed; rows expand/collapse.
+ *
+ * Parsing is debounced off the textarea and rides the same `/api/v1/debug`
+ * channel as every other panel (`klient.core(IBashParserService).parse`) —
+ * the budgeted parse never throws, `{ ok: false }` means budget exhaustion.
+ */
+
+import { useEffect, useState } from 'react';
+
+import {
+  IBashParserService,
+  type BashParseResult,
+  type BashSyntaxNode,
+} from '@moonshot-ai/agent-core-v2/app/bashParser/bashParser';
+
+import { useConnection } from '../connection';
+import { Badge, errorMessage } from '../ui';
+
+const DEFAULT_SOURCE = `if [ -f config.sh ]; then
+  source config.sh && echo "loaded" | tee -a setup.log
+else
+  echo "missing" >&2; exit 1
+fi
+`;
+
+const PARSE_DEBOUNCE_MS = 300;
+
+/**
+ * Quick-fill examples, adapted from the parser's own differential fixtures
+ * (`packages/tree-sitter-bash/test/fixtures/differential/*.txt`) — each one
+ * exercises a distinct area of the grammar. The last three probe the
+ * non-happy paths: deep nesting (a left-associative arithmetic chain, the
+ * case that once overflowed the DTO conversion) and the error-recovery
+ * paths that set `hasError`.
+ */
+const EXAMPLES: readonly { readonly name: string; readonly source: string }[] = [
+  {
+    name: 'deep arithmetic (1000 operands)',
+    // A thousand left-nested binary_expression levels. Deeper chains parse
+    // fine in-process, but past ~2500 levels the JSON RPC transport itself
+    // cannot serialize the tree (V8 call-stack limit in JSON.stringify).
+    source: `echo $((${'1+'.repeat(1000)}1))`,
+  },
+  {
+    name: 'pipeline & redirects',
+    source: `git log --oneline | head -20 | tee /tmp/log.txt
+find . -name '*.ts' -print0 2>/dev/null | xargs -0 grep -l TODO
+cmd <<< "$input" >out.txt 2>&1
+`,
+  },
+  {
+    name: 'case statement',
+    source: `case $x in
+  a) echo A ;;
+  b|c) echo BC ;&
+  foo*|bar) echo match ;;
+  [a-z]) echo lower ;;
+  *) echo other ;;
+esac
+`,
+  },
+  {
+    name: 'heredoc',
+    source: `foo() { cat <<EOF
+body $x
+EOF
+}
+
+cat <<-'RAW'
+	indented $notexpanded
+	RAW
+`,
+  },
+  {
+    name: 'expansions & arithmetic',
+    source: `echo "\${var:-default} \${#arr[@]} \${path##*/}"
+echo $((x << 2 | 1)) $[y + 1]
+result=$(command -v jq) && echo "$result"
+`,
+  },
+  {
+    name: 'process substitution',
+    source: `diff <(sort a.txt) <(sort b.txt)
+while read -r line; do echo "$line"; done < <(git status --short)
+`,
+  },
+  {
+    name: 'loops & conditions',
+    source: `for f in src/*.ts; do
+  [ -f "$f" ] || continue
+  grep -q FIXME "$f" && echo "$f has FIXME"
+done
+
+while IFS= read -r line; do printf '%s\\n' "$line"; done < list.txt
+until [ "$n" -le 0 ]; do n=$((n - 1)); done
+`,
+  },
+  {
+    name: 'error: unclosed substitution',
+    source: 'echo $(date | wc -l\n',
+  },
+  {
+    name: 'error: unterminated if',
+    source: `if cat <<EOF; then x; fi
+body
+EOF
+`,
+  },
+];
+
+function countNodes(node: BashSyntaxNode): number {
+  return 1 + node.children.reduce((sum, child) => sum + countNodes(child), 0);
+}
+
+export function BashParserView() {
+  const { klient } = useConnection();
+  const [source, setSource] = useState(DEFAULT_SOURCE);
+  const [timeoutMs, setTimeoutMs] = useState('');
+  const [maxNodes, setMaxNodes] = useState('');
+  const [result, setResult] = useState<BashParseResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const handle = setTimeout(() => {
+      klient
+        .core(IBashParserService)
+        .parse(source, {
+          timeoutMs: timeoutMs === '' ? undefined : Number(timeoutMs),
+          maxNodes: maxNodes === '' ? undefined : Number(maxNodes),
+        })
+        .then(setResult, (e: unknown) => {
+          setResult(null);
+          setError(errorMessage(e));
+        });
+    }, PARSE_DEBOUNCE_MS);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [klient, source, timeoutMs, maxNodes]);
+
+  const nodeCount = result !== null && result.ok ? countNodes(result.root) : null;
+
+  return (
+    <div className="flex min-h-0 flex-1">
+      <div className="flex w-[44%] shrink-0 flex-col border-r border-neutral-800">
+        <div className="flex items-center gap-3 border-b border-neutral-800 px-3 py-2">
+          <span className="text-[11px] font-semibold text-neutral-300">bash source</span>
+          <select
+            className="rounded border border-neutral-700 bg-neutral-950 px-1.5 py-0.5 text-[11px] text-neutral-300 outline-none focus:border-sky-600"
+            value=""
+            onChange={(e) => {
+              const example = EXAMPLES.find((x) => x.name === e.target.value);
+              if (example !== undefined) setSource(example.source);
+            }}
+          >
+            <option value="" disabled>
+              examples…
+            </option>
+            {EXAMPLES.map((x) => (
+              <option key={x.name} value={x.name}>
+                {x.name}
+              </option>
+            ))}
+          </select>
+          <div className="flex-1" />
+          <label className="flex items-center gap-1 text-[10px] text-neutral-500">
+            timeoutMs
+            <input
+              className="w-16 rounded border border-neutral-700 bg-neutral-950 px-1.5 py-0.5 font-mono text-[11px] text-neutral-200 outline-none focus:border-sky-600"
+              placeholder="50"
+              value={timeoutMs}
+              onChange={(e) => setTimeoutMs(e.target.value)}
+            />
+          </label>
+          <label className="flex items-center gap-1 text-[10px] text-neutral-500">
+            maxNodes
+            <input
+              className="w-20 rounded border border-neutral-700 bg-neutral-950 px-1.5 py-0.5 font-mono text-[11px] text-neutral-200 outline-none focus:border-sky-600"
+              placeholder="50000"
+              value={maxNodes}
+              onChange={(e) => setMaxNodes(e.target.value)}
+            />
+          </label>
+        </div>
+        <textarea
+          className="min-h-0 flex-1 resize-none bg-neutral-950 p-3 font-mono text-[12px] leading-relaxed text-neutral-200 outline-none"
+          spellCheck={false}
+          value={source}
+          onChange={(e) => setSource(e.target.value)}
+        />
+      </div>
+      <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+        <div className="flex items-center gap-2 border-b border-neutral-800 px-3 py-2">
+          <span className="text-[11px] font-semibold text-neutral-300">syntax tree</span>
+          {error !== null ? <Badge tone="red">rpc error</Badge> : null}
+          {result !== null && !result.ok ? <Badge tone="red">aborted</Badge> : null}
+          {result !== null && result.ok && result.hasError ? (
+            <Badge tone="amber">hasError</Badge>
+          ) : null}
+          {nodeCount !== null ? <Badge tone="neutral">{nodeCount} nodes</Badge> : null}
+        </div>
+        <div className="min-h-0 flex-1 overflow-auto p-2">
+          {error !== null ? (
+            <div className="rounded bg-red-950/50 px-2 py-1 text-[11px] text-red-400">{error}</div>
+          ) : result === null ? (
+            <div className="text-[11px] text-neutral-600 italic">parsing…</div>
+          ) : !result.ok ? (
+            <div className="text-[11px] text-neutral-500">
+              Parse budget exhausted (<span className="font-mono">reason: {result.reason}</span>) —
+              the tree cannot be analyzed; raise the budget or shrink the input.
+            </div>
+          ) : (
+            <SyntaxTreeNode node={result.root} depth={0} defaultDepth={2} />
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function SyntaxTreeNode({
+  node,
+  depth,
+  defaultDepth,
+}: {
+  readonly node: BashSyntaxNode;
+  readonly depth: number;
+  readonly defaultDepth: number;
+}) {
+  const [open, setOpen] = useState(depth < defaultDepth);
+  const expandable = node.children.length > 0;
+  const range = `[${String(node.startIndex)}, ${String(node.endIndex)})`;
+  const text = node.text.length > 60 ? `${node.text.slice(0, 60)}…` : node.text;
+
+  return (
+    <div>
+      <div
+        className="flex cursor-pointer items-baseline gap-2 truncate rounded px-1 font-mono text-[11px] leading-[1.7] hover:bg-neutral-800/70"
+        style={{ paddingLeft: `${depth * 14 + 4}px` }}
+        onClick={() => {
+          if (expandable) setOpen((v) => !v);
+        }}
+        title={node.text}
+      >
+        <span className="select-none text-neutral-600">
+          {expandable ? (open ? '▾' : '▸') : '·'}
+        </span>
+        <span className={node.isNamed ? 'text-sky-300' : 'text-neutral-500'}>{node.type}</span>
+        <span className="text-neutral-600">{range}</span>
+        {!expandable ? (
+          <span className="truncate text-emerald-300/70">{JSON.stringify(text)}</span>
+        ) : null}
+      </div>
+      {open
+        ? node.children.map((child, index) => (
+            <SyntaxTreeNode
+              // Children are source-ordered and sibling ranges never overlap,
+              // so range + index is a stable key.
+              key={`${String(child.startIndex)}:${String(child.endIndex)}:${String(index)}`}
+              node={child}
+              depth={depth + 1}
+              defaultDepth={defaultDepth}
+            />
+          ))
+        : null}
+    </div>
+  );
+}

apps/kimi-inspect/src/components/NavRail.tsx

@@ -6,7 +6,7 @@
 
 import type { ReactNode } from 'react';
 
-export type AppView = 'chat' | 'models' | 'services';
+export type AppView = 'chat' | 'models' | 'services' | 'bash';
 
 interface ViewDef {
   readonly id: AppView;
@@ -58,6 +58,16 @@ const VIEWS: readonly ViewDef[] = [
       </svg>
     ),
   },
+  {
+    id: 'bash',
+    title: 'Bash Parser',
+    icon: (
+      <svg {...iconProps}>
+        <polyline points="4 17 10 11 4 5" />
+        <line x1="12" y1="19" x2="20" y2="19" />
+      </svg>
+    ),
+  },
 ];
 
 export function NavRail({

flake.nix

@@ -77,6 +77,7 @@
         ./packages/protocol
         ./packages/telemetry
         ./packages/transcript
+        ./packages/tree-sitter-bash
         ./apps/kimi-code
         ./apps/vscode
         ./apps/kimi-inspect
@@ -103,6 +104,7 @@
         "@moonshot-ai/protocol"
         "@moonshot-ai/kimi-telemetry"
         "@moonshot-ai/transcript"
+        "@moonshot-ai/tree-sitter-bash"
         "@moonshot-ai/kimi-code"
         "kimi-code"
         "@moonshot-ai/kimi-inspect"
@@ -160,7 +162,7 @@
               inherit (finalAttrs) pname version src pnpmWorkspaces;
               inherit pnpm;
               fetcherVersion = 3;
-              hash = "sha256-k2McTzqvLoSzXQwwHJYdzA4prhJUlOa4JKbDektSHiA=";
+              hash = "sha256-bL1AaInlb8dE+ua7a6llvQWkibEwEzfI3oQW5IOpX6I=";
             };
 
             nativeBuildInputs = [

packages/agent-core-v2/package.json

@@ -66,6 +66,7 @@
     "@moonshot-ai/kimi-code-oauth": "workspace:^",
     "@moonshot-ai/minidb": "workspace:^",
     "@moonshot-ai/protocol": "workspace:^",
+    "@moonshot-ai/tree-sitter-bash": "workspace:^",
     "@mozilla/readability": "^0.6.0",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",

packages/agent-core-v2/scripts/check-domain-layers.mjs

@@ -108,6 +108,11 @@ const DOMAIN_LAYER = new Map([
   // It wraps the `_base` `StateRegistry` and depends on nothing else, so any
   // domain may hold its plain-data state through it; sits in L1 beside `event`.
   ['state', 1],
+  // `bashParser` is the App-scope adapter over the pure
+  // `@moonshot-ai/tree-sitter-bash` package (bash source → syntax tree DTO).
+  // It injects no services, so it sits in L1 beside the other pure
+  // capabilities.
+  ['bashParser', 1],
   // persistence/ and os/ — the two-level scopes. `interface` holds contracts
   // (same layer as the old domains they replace); `backends` holds
   // implementations that may depend on cross-domain services at various layers.