@ludi-uni/ludi-agent-kit 0.1.0

package/adapters/pi/lib/subagent.mjs

@@ -0,0 +1,175 @@
+// Tool-capable child: `pi --mode json -p` with an explicit tool allowlist and the shell gate extension.
+// Sessions stay out of ~/.pi (`--no-session`). The child id is ours and is recorded on the task trace.
+import { spawn } from 'node:child_process';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { locatePiEntry } from './invoke.mjs';
+import { classifyRun } from '../../../lib/orchestrator/failures.mjs';
+import { progressScore } from '../../../lib/orchestrator/turn-budget.mjs';
+
+const shellGate = join(dirname(fileURLToPath(import.meta.url)), '..', 'shell-gate', 'index.js');
+
+export function inspectPiEvents(events) {
+  let text = '';
+  let error = '';
+  let toolCalls = 0;
+  let turns = 0;
+  const commands = [];
+  const toolNames = {};
+  const uniqueFiles = new Set();
+  for (const event of events) {
+    const message = event?.message;
+    if (event?.type === 'message_end' && message?.role === 'assistant') {
+      turns++;
+      if (message.errorMessage) error = String(message.errorMessage);
+      for (const part of message.content ?? []) {
+        if (part.type === 'text' && part.text) text = part.text;
+        if (part.type === 'toolCall') {
+          toolCalls++;
+          const name = part.name ?? part.toolName ?? 'tool';
+          toolNames[name] = (toolNames[name] ?? 0) + 1;
+          const command = part.arguments?.command ?? part.args?.command;
+          if (command) commands.push(String(command));
+          // Track files the tool touched (read/edit/write/grep path args) for progress scoring.
+          const fileArg = part.arguments?.path ?? part.arguments?.file ?? part.args?.path ?? part.args?.file;
+          if (fileArg) uniqueFiles.add(String(fileArg));
+        }
+      }
+    }
+  }
+  return { text, error, toolCalls, turns, commands, toolNames, uniqueFilesInspected: uniqueFiles.size, uniqueFiles, successfulToolCalls: toolCalls };
+}
+
+export function createPiSubagentRunner(options = {}) {
+  return req => runPiSubagent(req, options);
+}
+
+export async function runPiSubagent(req, { piEntry = locatePiEntry(), spawnImpl = spawn, timeoutMs = null } = {}) {
+  if (!piEntry) return { ok: false, error: 'pi CLI entry not found on PATH', failureClass: 'MODEL_FAILURE' };
+  const limits = req.limits ?? {};
+  const runtimeMs = timeoutMs ?? limits.max_runtime_ms ?? 600000;
+  const childSessionId = `child-${randomBytes(4).toString('hex')}`;
+  const startedAt = new Date().toISOString();
+  const dir = mkdtempSync(join(tmpdir(), 'ludi-sub-'));
+  const promptPath = join(dir, 'task.md');
+  writeFileSync(promptPath, req.prompt ?? '');
+  const tools = req.toolNames ?? [];
+  // Extension discovery stays ON: providers that are registered by pi extensions
+  // (e.g. qoder, devin — absent from the static model store) only resolve when their
+  // extension has loaded; `--no-extensions` makes `--model` fail with "not found".
+  // Kit extensions the child needs are passed explicitly with `-e`.
+  const args = [piEntry, '--mode', 'json', '-p', '--no-session', '--no-approve', '--no-skills', '--model', req.modelId];
+  if (tools.length) args.push('--tools', tools.join(','));
+  else args.push('--no-tools');
+  if (tools.includes('ludi_exec')) args.push('-e', shellGate);
+  args.push('--system-prompt', req.systemPrompt ?? '', '--', `@${promptPath}`);
+  // Execution budget: req.limits carries the RESOLVED initial turn budget for this
+  // task's role+complexity (runner computes it). Extension is bounded and only
+  // granted while the subagent keeps making meaningful progress — an extension is
+  // inside the same model invocation and does NOT consume the attempt budget.
+  const initialTurns = limits.max_turns ?? 12;
+  const extensionTurns = limits.extension_turns ?? 0;
+  const maxExtensions = limits.max_extensions ?? 0;
+  const absoluteMax = limits.absolute_max_turns ?? initialTurns;
+  let turnCap = initialTurns;
+  let extensionsGranted = 0;
+  // Live progress for the orchestrator's public activity snapshot. Events are
+  // sanitized (tool name / file only — never arguments, output, or prompt text).
+  const emit = (type, data = {}) => { try { req.onEvent?.(type, data); } catch { /* never break a child on telemetry */ } };
+  let lastTurn = 0;
+  const seenTools = new Set();
+  const child = {
+    taskId: req.taskId ?? null, runId: req.runId ?? null, childSessionId, agent: req.agent ?? null,
+    modelId: req.modelId, backend: req.backend ?? null, startedAt, finishedAt: null, status: 'running',
+    toolCalls: 0, turns: 0, uniqueFilesInspected: 0, toolNames: {}, extensionsGranted: 0, initialTurns, finalTurnLimit: initialTurns, stopReason: null,
+  };
+  const events = [];
+  let stdout = '';
+  let stderr = '';
+  try {
+    const result = await new Promise(resolvePromise => {
+      const proc = spawnImpl(process.execPath, args, {
+        cwd: req.cwd, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, PI_SKIP_VERSION_CHECK: '1', LUDI_SHELL_MODE: req.access?.shell ?? 'false', LUDI_SHELL_NETWORK: req.access?.network ? '1' : '0' },
+      });
+      let settled = false;
+      const finish = (value) => { if (!settled) { settled = true; clearTimeout(timer); resolvePromise(value); } };
+      const timer = setTimeout(() => { proc.kill(); finish({ ok: false, error: `child timed out after ${runtimeMs}ms`, failureClass: 'TIMEOUT' }); }, runtimeMs);
+      proc.stdout?.setEncoding?.('utf8');
+      proc.stderr?.setEncoding?.('utf8');
+      proc.stdout?.on?.('data', chunk => {
+        stdout += chunk;
+        const lines = stdout.split(/\r?\n/);
+        stdout = lines.pop() ?? '';
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const parsedLine = JSON.parse(line);
+            events.push(parsedLine);
+            if (parsedLine?.type === 'tool_execution_start') {
+              const key = parsedLine.toolCallId ?? `tool-${events.length}`;
+              if (!seenTools.has(key)) {
+                seenTools.add(key);
+                emit('invocation-tool', { tool: { name: parsedLine.toolName ?? 'tool', file: parsedLine.args?.path ?? parsedLine.args?.file } });
+              }
+            }
+            if (parsedLine?.type === 'tool_execution_end') {
+              emit('invocation-tool-completed', { tool: { name: parsedLine.toolName ?? 'tool' } });
+            }
+          } catch { /* non-json diagnostic */ }
+          const seen = inspectPiEvents(events);
+          if (seen.turns > lastTurn) { lastTurn = seen.turns; emit('invocation-turn', { turn: seen.turns, turnCap, toolCalls: seen.toolCalls }); }
+          if (limits.max_tool_calls && seen.toolCalls > limits.max_tool_calls) { child.stopReason = 'tool-call-limit'; proc.kill(); finish({ ok: false, error: `tool call limit ${limits.max_tool_calls}`, failureClass: 'TIMEOUT', telemetry: seen }); }
+          if (seen.turns > turnCap) {
+            // Turn cap reached. Evaluate progress deterministically: if the agent is
+            // still doing useful work, grant a bounded extension; otherwise stop now.
+            const prog = progressScore(seen);
+            if (prog.meaningful && extensionsGranted < maxExtensions && turnCap < absoluteMax) {
+              extensionsGranted++;
+              child.extensionsGranted = extensionsGranted;
+              const oldLimit = turnCap;
+              turnCap = Math.min(turnCap + extensionTurns, absoluteMax);
+              child.finalTurnLimit = turnCap;
+              child.lastProgressReasons = prog.reasons;
+              emit('invocation-extension', { turn: seen.turns, turnCap, oldLimit, newLimit: turnCap, extensionsGranted, reason: 'meaningful progress' });
+            } else {
+              child.stopReason = prog.meaningful ? 'absolute-turn-limit' : 'no-progress-turn-limit';
+              proc.kill();
+              finish({ ok: false, error: `turn limit ${turnCap}`, failureClass: prog.meaningful ? 'PROGRESS_TIMEOUT' : 'NO_PROGRESS_TIMEOUT', telemetry: seen, progress: prog });
+            }
+          }
+        }
+      });
+      proc.stderr?.on?.('data', chunk => { stderr += chunk; });
+      proc.on?.('error', error => finish({ ok: false, error: error.message, failureClass: 'MODEL_FAILURE' }));
+      proc.on?.('close', code => {
+        if (stdout.trim()) { try { events.push(JSON.parse(stdout)); } catch { /* remainder */ } }
+        const seen = inspectPiEvents(events);
+        child.toolCalls = seen.toolCalls;
+        child.turns = seen.turns;
+        child.uniqueFilesInspected = seen.uniqueFilesInspected;
+        child.toolNames = seen.toolNames;
+        child.commandsExecuted = seen.commands.length;
+        const reason = seen.error || stderr.trim();
+        if (code !== 0) finish({ ok: false, error: `pi exited ${code}: ${(reason || seen.text || '').slice(-800)}`, failureClass: classifyRun({ error: reason || seen.text }), text: seen.text, telemetry: seen });
+        else if (!seen.text.trim()) finish({ ok: false, error: (reason || 'empty model response').slice(-800), failureClass: classifyRun({ error: reason || 'empty model response' }), text: '', telemetry: seen });
+        else finish({ ok: true, text: seen.text, toolCalls: seen.toolCalls, turns: seen.turns, commands: seen.commands, telemetry: seen });
+      });
+    });
+    child.finishedAt = new Date().toISOString();
+    child.status = result.ok ? 'finished' : 'failed';
+    const tel = result.telemetry ?? {};
+    child.toolCalls = result.toolCalls ?? tel.toolCalls ?? child.toolCalls;
+    child.turns = result.turns ?? tel.turns ?? child.turns;
+    child.uniqueFilesInspected = tel.uniqueFilesInspected ?? child.uniqueFilesInspected;
+    child.toolNames = tel.toolNames ?? child.toolNames;
+    child.commandsExecuted = tel.commands?.length ?? child.commandsExecuted;
+    if (!child.stopReason) child.stopReason = result.ok ? 'completed' : (result.failureClass ?? 'failed');
+    return { ...result, child };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/adapters/pi/loop-guard/index.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Keep fingerprints, never tool output or commands, in bounded session memory.
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
+  return value;
+}
+function fingerprint(value) {
+  return createHash('sha256').update(JSON.stringify(stable(value))).digest('hex');
+}
+export default function loopGuard(pi) {
+  const policy = readFileSync(resolve(dirname(realpathSync(fileURLToPath(import.meta.url))), '../../../rules/loop-prevention.md'), 'utf8').trim();
+  let history = [], halted = false;
+  const reset = () => { history = []; halted = false; };
+  pi.on('session_start', reset);
+  pi.on('model_select', reset);
+  pi.on('input', event => {
+    // An automatic goal/follow-up must not silently bypass a tripped guard.
+    if (event.source === 'interactive' || event.source === 'rpc') reset();
+  });
+  pi.on('before_agent_start', event => {
+    return { systemPrompt: event.systemPrompt.includes(policy) ? event.systemPrompt : event.systemPrompt + '\n\n' + policy };
+  });
+  pi.on('tool_call', (_event, ctx) => {
+    if (halted) return { block: true, terminate: true, reason: 'Loop guard: stopped after repeated identical tool results. Wait for new user input.' };
+  });
+  pi.on('tool_result', (event, ctx) => {
+    if (halted) return;
+    const key = fingerprint([event.toolName, event.input]);
+    const output = fingerprint([event.content, Boolean(event.isError)]);
+    history.push({ key, output });
+    if (history.length > 12) history.shift();
+    let repeats = 0;
+    for (let i = history.length - 1; i >= 0; i--) {
+      if (history[i].key !== key) continue;
+      if (history[i].output !== output) break;
+      repeats++;
+    }
+    if (repeats < 3) return;
+    halted = true;
+    ctx.abort();
+    pi.sendMessage({
+      customType: 'loop-guard', display: true,
+      content: `反復を停止しました。直近12件の結果中、同じ${event.toolName}入力から同じ結果が3回続きました。既存の結果を確認し、調査方針を変えて新しい指示を送ってください。自動再開は行いません。`,
+    }, { triggerTurn: false });
+  });
+}

package/adapters/pi/maintenance-policy.json

@@ -0,0 +1,36 @@
+{
+  "$comment": "Phase 2 maintenance execution policy for the pi adapter. requiredQuality is the 0-100 quality bar per execution tier (free models below the bar are NOT used). costWeights blends api $/1M, local electricity $/run and a speed penalty into effectiveCostUsd. escalation rules decide when evaluate hands off to the reconfigure tier. No model names — selection reads model-catalog.json.",
+  "version": 1,
+  "requiredQuality": { "monitor": 40, "evaluate": 65, "reconfigure": 80 },
+  "costWeights": { "api": 1, "electricity": 1, "speed": 0.02 },
+  "electricityPricePerKwh": 0.30,
+  "taskProfiles": {
+    "monitor":     { "estimatedInputTokens": 8000,  "estimatedOutputTokens": 800,  "estimatedTaskMinutes": 1 },
+    "evaluate":    { "estimatedInputTokens": 20000, "estimatedOutputTokens": 3000, "estimatedTaskMinutes": 3 },
+    "reconfigure": { "estimatedInputTokens": 60000, "estimatedOutputTokens": 8000, "estimatedTaskMinutes": 8 }
+  },
+  "qualityTier": { "monitor": "low", "evaluate": "mid", "reconfigure": "high" },
+  "capabilityRequirements": {
+    "cheap-code": { "coding": 50 },
+    "strong-code": { "coding": 75, "reasoning": 65 },
+    "deep-review": { "coding": 70, "reasoning": 70 },
+    "orchestration": { "reasoning": 55 },
+    "browser": { "reasoning": 70 },
+    "vision-reasoning": { "reasoning": 80 }
+  },
+  "escalation": {
+    "minCapabilities": 2,
+    "minAgents": 3,
+    "minQualitySwing": 15,
+    "maxScoreDelta": 4,
+    "structuralEvents": ["removed", "deprecated"],
+    "escalateOnLowConfidence": true,
+    "escalateOnStructural": false,
+    "minEvaluateConfidence": 0.5
+  },
+  "budget": {
+    "maxEstimatedCostPerRunUsd": 0.05,
+    "maxPremiumInvocationsPerRun": 1,
+    "maxTotalInvocationsPerRun": 4
+  }
+}

package/adapters/pi/mcp.template.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "Template for ~/.pi/agent/mcp.json (pi-mcp-adapter format). No credentials here: use ${ENV_VAR} placeholders or the adapter's own auth store. Actual server list is composed from ../../mcp/servers.json by sync-pi.ps1.",
+  "mcpServers": {}
+}

package/adapters/pi/model-catalog.json

@@ -0,0 +1,97 @@
+{
+  "$comment": "Model knowledge for the maintenance task (scripts/reevaluate-models.mjs). Concrete ids live here because this is the pi adapter; lib/maintenance.mjs stays neutral. Update `updatedAt` and entries from provider pricing/model docs or market snapshots (see docs/model-maintenance.md). Scores are heuristic 0-100; null = unknown (excluded from scoring, lowers confidence). status: active | free-campaign | deprecated | removed. cost in USD per 1M tokens; free:true means currently $0. postCampaignCost is the expected price when a free campaign ends. Never store credentials.",
+  "version": 1,
+  "updatedAt": "2026-09-25",
+  "models": [
+    {
+      "provider": "freetoken",
+      "model": "Qwen3.6-35B-A3B-NVFP4",
+      "status": "active",
+      "cost": { "free": true },
+      "location": "local",
+      "local": { "powerWatts": 450, "taskMinutes": 4 },
+      "contextK": 64,
+      "vision": false,
+      "toolUse": "basic",
+      "thinking": "off",
+      "scores": { "coding": 40, "reasoning": 35, "speed": 70 },
+      "notes": "Local NVFP4 quant served through the freetoken endpoint. Electricity estimate: 450W x 4min at the policy electricity price."
+    },
+    {
+      "provider": "qoder",
+      "model": "Qwen3.8-Flash",
+      "status": "free-campaign",
+      "cost": { "free": true },
+      "postCampaignCost": null,
+      "freeUntil": null,
+      "contextK": 1024,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "low",
+      "scores": { "coding": 62, "reasoning": 55, "speed": 85 },
+      "notes": "Verified 2026-09-24 via `pi --list-models` + ~/.pi/agent/qoder-models-cache.json: priceFactor 0 (free campaign), 1M context, 128K max output, reasoning+effort, image input. Qoder pricing is subscription priceFactor-based, not per-token — post-campaign per-token cost is genuinely unknown (postCampaignCost null -> costUnknown on campaign end, re-evaluated by maintenance). freeUntil not published by the provider."
+    },
+    {
+      "provider": "devin",
+      "model": "swe-2-high",
+      "status": "free-campaign",
+      "cost": { "free": true },
+      "postCampaignCost": { "usdPerMInput": 0.75, "usdPerMOutput": 3.75 },
+      "freeUntil": "2026-10-10T15:00:00Z",
+      "contextK": 256,
+      "vision": true,
+      "toolUse": "good",
+      "thinking": "high",
+      "scores": { "coding": 80, "reasoning": 75, "speed": 50 },
+      "notes": "User-reported Devin free campaign through 2026-10-10 (interpreted inclusive JST, cutoff 2026-10-11 00:00 JST; independently unverified). 2026-09-24 pi model metadata lists $0.75/$3.75 per 1M tokens as post-campaign reference, 256K context, 128K max output. Actual entitlement and billing must be checked before live usage. Scores are heuristic placeholders pending measured results; sibling variants are not assumed free."
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.6-luna",
+      "status": "active",
+      "cost": { "usdPerMInput": 0.4, "usdPerMOutput": 1.6 },
+      "contextK": 272,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "low",
+      "scores": { "coding": 68, "reasoning": 60, "speed": 80 },
+      "notes": "Current cheap backend binding."
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.6-sol",
+      "status": "active",
+      "cost": { "usdPerMInput": 1.5, "usdPerMOutput": 6.0 },
+      "contextK": 400,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "medium",
+      "scores": { "coding": 85, "reasoning": 82, "speed": 55 },
+      "notes": "Current sol backend binding."
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-6-astra",
+      "status": "active",
+      "cost": { "usdPerMInput": 2.5, "usdPerMOutput": 10.0 },
+      "contextK": 400,
+      "vision": true,
+      "toolUse": "good",
+      "thinking": "medium",
+      "scores": { "coding": 88, "reasoning": 90, "speed": 50 },
+      "notes": "Current astra backend binding; vision-capable."
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.5",
+      "status": "active",
+      "cost": { "usdPerMInput": 1.25, "usdPerMOutput": 5.0 },
+      "contextK": 400,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "high",
+      "scores": { "coding": 82, "reasoning": 84, "speed": 45 },
+      "notes": "Current codex backend binding."
+    }
+  ]
+}

package/adapters/pi/models.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "Shared TEMPLATE binding of logical routing backends to pi provider/model ids. Real per-machine bindings go in models.local.json (gitignored) and override these per backend. TODO-* values are placeholders that the resolver skips. Allowed binding keys: provider, model, thinking, vision, note. Never store credentials here.",
+  "version": 1,
+  "backends": {
+    "local":  { "provider": "TODO-provider", "model": "TODO-local-model",  "thinking": "off",    "note": "OpenAI-compatible local endpoint declared in ~/.pi/agent/models.json" },
+    "cheap":  { "provider": "TODO-provider", "model": "TODO-cheap-model",  "thinking": "low" },
+    "sol":    { "provider": "TODO-provider", "model": "TODO-sol-model",    "thinking": "high" },
+    "astra":  { "provider": "TODO-provider", "model": "TODO-astra-model",  "thinking": "medium", "vision": true },
+    "codex":  { "provider": "TODO-provider", "model": "TODO-codex-model",  "thinking": "high",   "note": "Codex as a pi provider; or use pi-subagents codex-exec adapter instead" },
+    "qoder":  { "provider": "TODO-provider", "model": "TODO-qoder-model",  "thinking": "low",    "note": "Qoder-hosted model slot; bind in models.local.json from `pi --list-models`" },
+    "devin":  { "provider": "TODO-provider", "model": "TODO-devin-model",  "thinking": "high",   "note": "Devin-hosted model slot; bind in models.local.json from `pi --list-models`" }
+  }
+}

package/adapters/pi/models.local.example.json

@@ -0,0 +1,14 @@
+{
+  "$comment": "EXAMPLE of models.local.json. Copy to models.local.json and replace with ids from `pi --list-models`; check readiness with `pi auth check --provider <p>`.",
+  "version": 1,
+  "backends": {
+    "local": { "provider": "freetoken",    "model": "Qwen3.6-35B-A3B-NVFP4", "thinking": "off" },
+    "cheap": { "provider": "openai-codex", "model": "gpt-5.6-luna",  "thinking": "low" },
+    "sol":   { "provider": "openai-codex", "model": "gpt-5.6-sol",   "thinking": "medium" },
+    "astra": { "provider": "openai-codex", "model": "gpt-6-astra",   "thinking": "medium", "vision": true },
+    "codex": { "provider": "openai-codex", "model": "gpt-5.5",       "thinking": "high" },
+    "qoder": { "provider": "qoder",        "model": "Qwen3.8-Flash", "thinking": "low",    "note": "Qoder-hosted slot; id from `pi --list-models` / qoder-models-cache.json (priceFactor 0 = free campaign)" },
+    "devin": { "provider": "devin",        "model": "swe-2-high",    "thinking": "high",   "note": "Devin-hosted slot; api devin-cloud via server.codeium.com, ids from `pi --list-models`" }
+  }
+}
+

package/adapters/pi/orchestrator-ext/command.mjs

@@ -0,0 +1,14 @@
+// Pure slash-command routing; read-only verbs must never become a new request.
+export function parseOrchestrateCommand(args) {
+  const parts = String(args ?? '').trim().split(/\s+/).filter(Boolean);
+  const cmd = parts[0] || 'list';
+  if (['list', 'status', 'children', 'result', 'decisions'].includes(cmd)) {
+    return { action: cmd, params: { runId: parts[1] } };
+  }
+  if (cmd === 'resume') return { action: cmd, params: { runId: parts[1] } };
+  if (cmd === 'answer') return { action: cmd, params: { runId: parts[1], decisionId: parts[2], answer: parts.slice(3).join(' ') } };
+  if (cmd === 'prune') return { action: cmd, params: { olderThan: parts[1] } };
+  if (cmd === 'delete') return { action: cmd, params: { runId: parts[1], force: parts.includes('--force') } };
+  if (cmd === 'clear') return { action: cmd, params: { force: parts.includes('--force'), includeActive: parts.includes('--include-active') } };
+  return { action: 'start', params: { request: parts.join(' ') } };
+}

package/adapters/pi/orchestrator-ext/index.js

@@ -0,0 +1,150 @@
+// pi extension: slash commands and one tool over the persistent orchestration API.
+// Loaded from adapters/pi/orchestrator-ext (junction extensions/ludi-orchestrator). No pi core changes.
+// When accessed via a junction/symlink (e.g. ~/.pi/agent/extensions/…/index.js) the file URL
+// points at the junction, so relative imports would resolve wrong.  Resolve via realpathSync
+// to the physical location and use dynamic imports built from kitRoot.
+import { Type } from 'typebox';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { parseOrchestrateCommand } from './command.mjs';
+
+// Resolve junctions so that __dir is the physical location under the kit tree.
+const __file = realpathSync(fileURLToPath(import.meta.url));
+const __dir = dirname(__file);
+const kitRoot = resolve(__dir, '../../../');
+
+// Lazy-import cache – resolved once via file:// URL built from kitRoot.
+let _imports = null;
+async function _importsFn() {
+  if (!_imports) {
+    _imports = {
+      invoke: await import(pathToFileURL(resolve(kitRoot, 'adapters/pi/lib/invoke.mjs')).href),
+      subagent: await import(pathToFileURL(resolve(kitRoot, 'adapters/pi/lib/subagent.mjs')).href),
+      api: await import(pathToFileURL(resolve(kitRoot, 'lib/orchestrator/api.mjs')).href),
+    };
+  }
+  return _imports;
+}
+
+function kitPath() {
+  return decodeURIComponent(resolve(kitRoot).replace(/^\/[A-Za-z]:/, '$1'));
+}
+
+function text(body) {
+  return { content: [{ type: 'text', text: body }], details: undefined };
+}
+
+export default function orchestratorExtension(pi) {
+  // The pi session id is AUTHORITATIVE for clientContext kind 'pi-web'. A caller
+  // may not claim a different session — mismatch is rejected before any run starts.
+  const run = async (action, params, executionCtx = null) => {
+    const root = kitPath();
+    const im = await _importsFn();
+    const { loadOrchestrationContext, listOrchestrationRuns, showRun, formatReport, formatRunList, defaultStorePath, pendingDecisions, createRunHealth, createRunRunner, startOrchestration, resumeOrchestration, answerOrchestration, parseOlderThan, pruneOrchestrationRuns, deleteOrchestrationRun, clearOrchestrationRuns, previewRunCleanup, formatCleanup } = im.api;
+    const createPiInvoker = im.invoke.createPiInvoker;
+    const createPiSubagentRunner = im.subagent.createPiSubagentRunner;
+    const requestedClient = params.clientContext;
+    const sessionId = executionCtx?.sessionManager?.getSessionId?.() ?? null;
+    if (requestedClient && requestedClient.kind !== 'pi-web') return 'unsupported clientContext.kind';
+    if (requestedClient && !sessionId) return 'pi session id unavailable; cannot bind run';
+    if (requestedClient?.sessionId && requestedClient.sessionId !== sessionId) return 'clientContext sessionId mismatch';
+    const cc = requestedClient ? { kind: 'pi-web', sessionId } : null;
+    const ctx = loadOrchestrationContext({ kit: root, storePath: params.store || defaultStorePath(root), clientContext: cc });
+    try {
+      if (ctx.errors.length) return ctx.errors.join('\n');
+      if (action === 'list') return formatRunList(listOrchestrationRuns(ctx, { status: params.status || null }));
+      if (action === 'status' && !params.runId) return formatRunList(listOrchestrationRuns(ctx, { status: params.status || null }));
+      if (['status', 'children', 'result'].includes(action) && !params.runId) return `${action} requires runId`;
+      if (params.runId && ['status', 'children', 'result'].includes(action)) {
+        const shown = showRun(ctx, params.runId);
+        const children = (shown.trace ?? []).filter(e => e.type === 'child');
+        const active = shown.tasks.filter(t => t.status === 'running');
+        if (action === 'children') return active.length ? active.map(t => `${t.id} ${t.assignedAgent} running`).join('\n') : 'active children: none';
+        if (action === 'result') return shown.tasks.map(t => `${t.id} ${t.status} ${String(t.result?.summary ?? '').split('\n')[0]}`).join('\n');
+        return `${formatReport(shown)}\n\nactive children: ${active.length ? active.map(t => t.id).join(', ') : 'none'}\nchild sessions: ${children.length}`;
+      }
+      if (action === 'decisions') {
+        const rows = pendingDecisions(ctx, { runId: params.runId || null });
+        return rows.length ? rows.map(d => `${d.runId}  ${d.id}  [${d.taskId}] ${d.question}`).join('\n') : 'decisions: none';
+      }
+      if (action === 'prune') {
+        // Destructive: deletes terminal run history. Always previews in the reply.
+        const ms = params.olderThan ? parseOlderThan(params.olderThan) : undefined;
+        return formatCleanup(pruneOrchestrationRuns(ctx, { olderThanMs: ms }), { verb: '削除' });
+      }
+      if (action === 'delete') {
+        // Destructive only with force=true; otherwise a preview of that one run.
+        if (!params.runId) return 'delete requires runId';
+        if (params.force) {
+          const r = deleteOrchestrationRun(ctx, params.runId, { force: true });
+          return `削除しました: ${r.id} (tasks:${r.deleted.tasks} decisions:${r.deleted.decisions} trace:${r.deleted.trace} health:${r.deleted.health})`;
+        }
+        const target = previewRunCleanup(ctx, { includeActive: true }).runs.find(r => r.id === params.runId);
+        if (!target) return `run not found: ${params.runId}`;
+        if (!target.deletable) return `削除できません: ${target.id} — ${target.reason}`;
+        return `削除対象（プレビュー）: ${target.id} ${target.status} tasks:${target.counts.tasks} decisions:${target.counts.decisions} trace:${target.counts.trace}\n実行するには force=true`;
+      }
+      if (action === 'clear') {
+        // force=false previews; force=true deletes all terminal runs; includeActive adds active ones.
+        return formatCleanup(clearOrchestrationRuns(ctx, { force: !!params.force, includeActive: !!params.includeActive }), { verb: '削除' });
+      }
+      const health = createRunHealth(ctx);
+      const invoke = createPiInvoker();
+      const runner = createRunRunner(ctx, { invoke, runSubagent: createPiSubagentRunner(), repoRoot: params.repo || null, apply: false, health });
+      if (action === 'answer') {
+        answerOrchestration(ctx, { runId: params.runId, decisionId: params.decisionId, answer: params.answer });
+        const result = await resumeOrchestration(ctx, { runId: params.runId, repoRoot: params.repo || null, runner, invoke, health });
+        return formatReport(result);
+      }
+      if (action === 'resume') {
+        const result = await resumeOrchestration(ctx, { runId: params.runId, repoRoot: params.repo || null, runner, invoke, health });
+        return formatReport(result);
+      }
+      const result = await startOrchestration(ctx, { request: params.request, repoRoot: params.repo || null, runner, invoke, health });
+      return formatReport(result);
+    } finally {
+      ctx.session.close();
+    }
+  };
+
+  pi.registerCommand('orchestrate', {
+    description: 'Start, list, resume, or answer a persistent ludi orchestration run',
+    handler: async (args, ctx) => {
+      const { action, params } = parseOrchestrateCommand(args);
+      try {
+        const body = await run(action, params, ctx);
+        ctx.ui.notify(body.slice(0, 500), 'info');
+      } catch (e) { ctx.ui.notify(`orchestration error: ${e.message}`, 'error'); }
+    },
+  });
+
+  pi.registerTool({
+    name: 'ludi_orchestrate',
+    label: 'Ludi orchestrate',
+    description: 'Persistent ludi orchestrator: start, list, status, children, result, decisions, resume, answer, or clean up run history (prune/delete/clear).',
+    promptSnippet: 'ludi_orchestrate: start, list, resume, answer, or clean up history of a persistent orchestration run.',
+    promptGuidelines: [
+      'Use ludi_orchestrate to continue a high-level request across sessions. Do not re-ask a decision that is already pending; answer it or list it.',
+      'prune, delete and clear are destructive. delete and clear preview unless force=true; delete active requires force=true; clear active requires both force=true and includeActive=true.',
+    ],
+    parameters: Type.Object({
+      action: Type.String({ description: 'start | list | status | children | result | decisions | resume | answer | prune | delete | clear' }),
+      request: Type.Optional(Type.String({ description: 'High-level request for action=start' })),
+      runId: Type.Optional(Type.String({ description: 'Run id for status, children, result, decisions, resume, answer, or delete' })),
+      decisionId: Type.Optional(Type.String({ description: 'Pending decision id for action=answer' })),
+      answer: Type.Optional(Type.String({ description: 'User answer text for action=answer' })),
+      status: Type.Optional(Type.String({ description: 'Filter for action=list' })),
+      olderThan: Type.Optional(Type.String({ description: 'Duration for action=prune, e.g. "7d", "12h", "30m", "2w"' })),
+      force: Type.Optional(Type.Boolean({ description: 'Actually delete for action=delete/clear (otherwise preview only)' })),
+      includeActive: Type.Optional(Type.Boolean({ description: 'For action=clear with force=true: also delete active and resumable runs' })),
+      repo: Type.Optional(Type.String({ description: 'Repository root the agents should read' })),
+      store: Type.Optional(Type.String({ description: 'Override path to the orchestration sqlite file' })),
+      clientContext: Type.Optional(Type.Object({ kind: Type.String(), sessionId: Type.Optional(Type.String()) }, { description: 'Client binding request; pi-web session UUID is obtained from the current pi session' })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      try { return text(await run(params.action || 'list', params, ctx)); }
+      catch (e) { return text(`orchestration error: ${e.message}`); }
+    },
+  });
+}

package/adapters/pi/settings.template.json

@@ -0,0 +1,7 @@
+{
+  "$comment": "Template fragment. sync-pi.ps1 never writes settings.json; it only reports the diff between this fragment and the live file. Model/provider stay user-owned.",
+  "defaultTools": ["read", "powershell", "edit", "write"],
+  "enableSkillCommands": true,
+  "defaultProjectTrust": "ask",
+  "enableInstallTelemetry": false
+}

package/adapters/pi/shell-gate/index.js

@@ -0,0 +1,70 @@
+// pi extension loaded only by the orchestrator's tool-capable child.
+// Replaces raw shell: every command is classified before it runs, and a refusal stays inside the child
+// so the model returns a decision instead of asking the user directly.
+import { spawn } from 'node:child_process';
+import { Type } from 'typebox';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+
+// Resolve junctions so that __dir is the physical location under the kit tree.
+const __file = realpathSync(fileURLToPath(import.meta.url));
+const __dir = dirname(__file);
+const kitRoot = resolve(__dir, '../../../');
+
+// Lazy-import for the shell-policy module.
+let _decideShell = null;
+async function _load() {
+  if (!_decideShell) {
+    const m = await import(pathToFileURL(resolve(kitRoot, 'lib/orchestrator/shell-policy.mjs')).href);
+    _decideShell = m.decideShell;
+  }
+  return _decideShell;
+}
+
+function runCommand(command, cwd) {
+  return new Promise(resolve => {
+    const proc = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], { cwd, windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => { proc.kill(); resolve({ code: 124, stdout, stderr: `${stderr}\ntimeout` }); }, 120000);
+    proc.stdout.on('data', chunk => { stdout += chunk; });
+    proc.stderr.on('data', chunk => { stderr += chunk; });
+    proc.on('error', error => { clearTimeout(timer); resolve({ code: 1, stdout, stderr: error.message }); });
+    proc.on('close', code => { clearTimeout(timer); resolve({ code: code ?? 1, stdout, stderr }); });
+  });
+}
+
+let _decideShellPromise = null;
+
+function _ensureDecideShell() {
+  if (!_decideShellPromise) {
+    _decideShellPromise = _load();
+  }
+  return _decideShellPromise;
+}
+
+export default function shellGate(pi) {
+  // Tool registration is synchronous, but decideShell is loaded via dynamic import.
+  // The execute callback awaits the promise on first use.
+  pi.registerTool({
+    name: 'ludi_exec',
+    label: 'Ludi exec',
+    description: 'Run one workspace command. Tests, lint, build, and read-only git are allowed. Push, publish, deploy, reset, and recursive delete are refused.',
+    promptSnippet: 'ludi_exec: run an allowed shell command in the task workspace.',
+    promptGuidelines: ['Use ludi_exec instead of powershell or bash. If it returns POLICY_BLOCK, do not retry the command; report status needs_decision.'],
+    parameters: Type.Object({
+      command: Type.String({ description: 'One shell command. No user prompts.' }),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const decideShell = await _ensureDecideShell();
+      const decision = decideShell(params.command, { shell: process.env.LUDI_SHELL_MODE ?? 'limited', network: process.env.LUDI_SHELL_NETWORK === '1' });
+      if (!decision.allow) {
+        return { content: [{ type: 'text', text: `POLICY_BLOCK ${decision.reason}. Do not run this command. Return status "needs_decision" with the command in decisions.` }], isError: true };
+      }
+      const ran = await runCommand(params.command, ctx?.cwd);
+      const body = [`exit ${ran.code}`, ran.stdout.slice(-4000), ran.stderr.slice(-2000)].filter(Boolean).join('\n');
+      return { content: [{ type: 'text', text: body }], isError: ran.code !== 0, details: { command: params.command, exitCode: ran.code } };
+    },
+  });
+}