@polylogicai/polycode 1.1.0

package/lib/agentic.mjs

@@ -0,0 +1,505 @@
+// lib/agentic.mjs
+// polycode agentic loop. Runs a standard intent -> plan -> act -> record cycle
+// per user turn. The context for each turn is built from the session log via
+// lib/compiler.mjs, passed through lib/witness/secret-scrubber.mjs before any
+// network call, and every tool call lands as a signed row in the session log.
+//
+// polycode is inspired by Claude Code's public architecture at docs.claude.com.
+// polycode is not affiliated with Anthropic. No Claude Code code or system
+// prompts are copied. The hook contract event names match the public Claude
+// Code hook spec so that portable hook scripts work in both tools.
+
+import Groq from 'groq-sdk';
+import { promises as fs } from 'node:fs';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve, relative, sep, dirname } from 'node:path';
+import { compilePacket } from './compiler.mjs';
+import { mintCommitment } from './commitment.mjs';
+import { ensureActiveIntent } from './intent.mjs';
+import { scrubSecrets } from './witness/secret-scrubber.mjs';
+
+const execAsync = promisify(exec);
+
+const DEFAULT_MODEL = 'moonshotai/kimi-k2-instruct';
+const FALLBACK_MODEL = 'llama-3.3-70b-versatile';
+const DEFAULT_MAX_ITERATIONS = 12;
+const TEMPERATURE = 0.2;
+const MAX_TOKENS = 4096;
+const MAX_BASH_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_BYTES = 3200;
+
+const SYSTEM_PROMPT = `You are polycode, a terminal coding agent. Each turn you receive the current user message along with a small set of context rows selected from the session log by a separate selection step. You do not need to hold conversation history in your own memory. Produce a short plan and the tool calls needed to address the current message, then call task_done with a one or two sentence summary.
+
+Discipline:
+- Use periods, commas, or colons. Not em dashes.
+- No hype words: no "revolutionary", "game-changer", "unprecedented".
+- Read files before asserting their content. Test before claiming something works.
+- Tools available: task_done, bash, read_file, write_file, edit_file, glob, grep.
+- When the current user message has been addressed, call task_done.
+
+Every tool call you make is checked by a deterministic verification layer before it is written to the session log. Checks include content grounding, file existence, rule compliance against a forbidden list, and secret scrubbing on tool output. If a check fails, the record is marked REFUTED and you should acknowledge and correct rather than retry the same action.`;
+
+const TOOL_SCHEMAS = [
+  {
+    type: 'function',
+    function: {
+      name: 'task_done',
+      description: "Call this when the user's current message has been addressed. Summary is the final user-facing message for this turn.",
+      parameters: {
+        type: 'object',
+        properties: { summary: { type: 'string' } },
+        required: ['summary'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'bash',
+      description: 'Run a shell command in the working directory. 30 second timeout. Output truncated at 3200 bytes.',
+      parameters: {
+        type: 'object',
+        properties: { command: { type: 'string' } },
+        required: ['command'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'read_file',
+      description: 'Read a file relative to the working directory. Returns the first 3200 bytes.',
+      parameters: {
+        type: 'object',
+        properties: { path: { type: 'string' } },
+        required: ['path'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'write_file',
+      description: 'Write content to a file. Creates parent directories. Overwrites if exists.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          content: { type: 'string' },
+        },
+        required: ['path', 'content'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'edit_file',
+      description: 'Replace a single exact substring in a file. old_string must appear exactly once.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          old_string: { type: 'string' },
+          new_string: { type: 'string' },
+        },
+        required: ['path', 'old_string', 'new_string'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'glob',
+      description: 'List files matching a glob rooted at the working directory. First 200 matches.',
+      parameters: {
+        type: 'object',
+        properties: { pattern: { type: 'string' } },
+        required: ['pattern'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'grep',
+      description: 'Search for a regex in files rooted at the working directory. First 100 matching lines.',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+          glob: { type: 'string' },
+        },
+        required: ['pattern'],
+      },
+    },
+  },
+];
+
+function ensureInsideCwd(cwd, targetPath) {
+  const abs = resolve(cwd, targetPath);
+  const rel = relative(cwd, abs);
+  if (rel.startsWith('..') || rel.includes(`..${sep}`)) {
+    throw new Error(`path escapes working directory: ${targetPath}`);
+  }
+  return abs;
+}
+
+function truncateStr(s, bytes = MAX_OUTPUT_BYTES) {
+  const buf = Buffer.from(String(s || ''));
+  if (buf.length <= bytes) return buf.toString();
+  return buf.slice(0, bytes).toString() + `\n...[truncated ${buf.length - bytes} bytes]`;
+}
+
+async function runTool(name, args, cwd) {
+  switch (name) {
+    case 'bash': {
+      const cmd = String(args.command ?? '');
+      try {
+        const { stdout, stderr } = await execAsync(cmd, {
+          cwd,
+          timeout: MAX_BASH_TIMEOUT_MS,
+          maxBuffer: 10 * 1024 * 1024,
+        });
+        return truncateStr([stdout, stderr].filter(Boolean).join('\n') || '(no output)');
+      } catch (err) {
+        return truncateStr(`exit=${err.code ?? 'unknown'}\n${err.message}\nstdout=${err.stdout ?? ''}\nstderr=${err.stderr ?? ''}`);
+      }
+    }
+    case 'read_file': {
+      const abs = ensureInsideCwd(cwd, String(args.path ?? ''));
+      try {
+        return truncateStr(await fs.readFile(abs, 'utf8'));
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
+    case 'write_file': {
+      const abs = ensureInsideCwd(cwd, String(args.path ?? ''));
+      try {
+        await fs.mkdir(dirname(abs), { recursive: true });
+        await fs.writeFile(abs, String(args.content ?? ''), 'utf8');
+        return `ok: wrote ${Buffer.byteLength(String(args.content ?? ''))} bytes to ${args.path}`;
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
+    case 'edit_file': {
+      const abs = ensureInsideCwd(cwd, String(args.path ?? ''));
+      try {
+        const content = await fs.readFile(abs, 'utf8');
+        const oldStr = String(args.old_string ?? '');
+        const newStr = String(args.new_string ?? '');
+        if (!content.includes(oldStr)) return `error: old_string not found in ${args.path}`;
+        const occ = content.split(oldStr).length - 1;
+        if (occ > 1) return `error: old_string appears ${occ} times in ${args.path}, must be unique`;
+        await fs.writeFile(abs, content.replace(oldStr, newStr), 'utf8');
+        return `ok: edited ${args.path} (${oldStr.length} -> ${newStr.length} bytes)`;
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
+    case 'glob': {
+      const pattern = String(args.pattern ?? '').replace(/'/g, "'\\''");
+      try {
+        const { stdout } = await execAsync(`find . -type f -name '${pattern}' 2>/dev/null | head -200`, { cwd });
+        return truncateStr(stdout || '(no matches)');
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
+    case 'grep': {
+      const pattern = String(args.pattern ?? '').replace(/'/g, "'\\''");
+      const glob = String(args.glob ?? '').replace(/'/g, "'\\''");
+      try {
+        const cmd = glob
+          ? `grep -rn --include='${glob}' -E '${pattern}' . 2>/dev/null | head -100`
+          : `grep -rn -E '${pattern}' . 2>/dev/null | head -100`;
+        const { stdout } = await execAsync(cmd, { cwd });
+        return truncateStr(stdout || '(no matches)');
+      } catch (err) {
+        return `error: ${err.message}`;
+      }
+    }
+    default:
+      return `error: unknown tool "${name}"`;
+  }
+}
+
+function recoverInlineToolCalls(content) {
+  if (!content) return [];
+  const out = [];
+  const re = /<function=([\w_-]+)>?(\{[\s\S]*?\})\s*<\/function>/g;
+  let m;
+  let n = 0;
+  while ((m = re.exec(content)) !== null) {
+    try { JSON.parse(m[2]); } catch { continue; }
+    out.push({ id: `recovered_${Date.now()}_${n++}`, name: m[1], argsJson: m[2] });
+  }
+  return out;
+}
+
+export class AgenticLoop {
+  constructor({ apiKey, model, logger, rules } = {}) {
+    this.apiKey = apiKey;
+    this.defaultModel = model || DEFAULT_MODEL;
+    this.logger = logger || console;
+    this.rules = rules || {};
+  }
+
+  async runTurn({ canon, userMessage, cwd, onEvent, maxIterations }) {
+    const start = Date.now();
+    const groq = new Groq({ apiKey: this.apiKey || process.env.GROQ_API_KEY });
+    let model = this.defaultModel;
+    let didFallback = false;
+    const limit = maxIterations || DEFAULT_MAX_ITERATIONS;
+    const emit = onEvent || (() => {});
+    const primitivesList = [];
+    const commitments = [];
+
+    // Phase 1: INTENT
+    emit({ phase: 'intent' });
+    const intent = ensureActiveIntent(canon, userMessage);
+    const intentId = intent.payload.intent_id;
+    const turnId = `turn_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+    canon.append('user_turn', { intent_id: intentId, turn_id: turnId, message: userMessage });
+
+    // Phase 2: GROUND. Build the bounded turn context from the session log.
+    const ctx = await compilePacket(canon, userMessage, cwd);
+    canon.append('compile_result', {
+      intent_id: intentId,
+      turn_id: turnId,
+      compiler_provider: ctx.compilerProvider,
+      selected_rows: ctx.selectedRows,
+      estimated_tokens: ctx.estimatedTokens,
+      fallback: ctx.fallback,
+      usage: ctx.compilerUsage,
+    });
+    emit({
+      phase: 'ground_complete',
+      estimatedTokens: ctx.estimatedTokens,
+      compilerProvider: ctx.compilerProvider,
+      selectedRows: ctx.selectedRows?.length || 0,
+      fallback: ctx.fallback,
+    });
+
+    // Phase 2b: SCRUB -> non-LLM secret scrubber must PASS before any dispatch
+    const scrub = scrubSecrets(ctx.prompt);
+    if (scrub.blocked) {
+      emit({ phase: 'scrub_blocked', findings: scrub.findings });
+      const c = await mintCommitment(canon, {
+        intentId,
+        turnId,
+        claim: `secret_bleed_blocked: ${scrub.reason}`,
+        substrate: `(redacted: scrubber blocked dispatch on ${scrub.findings.length} secret patterns)`,
+        toolName: null,
+        toolArgs: null,
+        toolResult: scrub.reason,
+        cwd,
+        packet: '(redacted)',
+        rules: this.rules,
+      });
+      commitments.push(c);
+      primitivesList.push(c.primitives);
+      emit({ phase: 'record', commitment: c });
+      return {
+        finalMessage: `(secret bleed blocked: ${scrub.reason}. turn aborted before dispatch, no network call was made.)`,
+        iterations: 0,
+        durationMs: Date.now() - start,
+        commitments,
+        primitivesList,
+        intentId,
+        turnId,
+        promptTokensUsed: 0,
+        scrubBlocked: true,
+      };
+    }
+
+    // Phase 3 + Phase 4: DISPATCH and ACT
+    const messages = [
+      { role: 'system', content: SYSTEM_PROMPT },
+      { role: 'user', content: ctx.prompt },
+    ];
+
+    let iteration = 0;
+    let finalMessage = '';
+    let done = false;
+
+    while (iteration < limit && !done) {
+      iteration++;
+      emit({ phase: 'dispatch', iteration });
+
+      let completion;
+      try {
+        completion = await groq.chat.completions.create({
+          model,
+          messages,
+          tools: TOOL_SCHEMAS,
+          tool_choice: 'auto',
+          temperature: TEMPERATURE,
+          max_tokens: MAX_TOKENS,
+        });
+      } catch (err) {
+        if (!didFallback && model !== FALLBACK_MODEL) {
+          didFallback = true;
+          model = FALLBACK_MODEL;
+          emit({ phase: 'fallback', to: FALLBACK_MODEL, reason: err.message });
+          iteration--;
+          continue;
+        }
+        emit({ phase: 'error', message: `groq call failed: ${err.message}` });
+        break;
+      }
+
+      const choice = completion.choices?.[0];
+      if (!choice) {
+        emit({ phase: 'error', message: 'no choice in groq response' });
+        break;
+      }
+
+      const assistantMsg = choice.message;
+      let toolCalls = assistantMsg.tool_calls;
+
+      if ((!toolCalls || toolCalls.length === 0) && assistantMsg.content) {
+        const recovered = recoverInlineToolCalls(assistantMsg.content);
+        if (recovered.length > 0) {
+          toolCalls = recovered.map((r) => ({
+            id: r.id,
+            type: 'function',
+            function: { name: r.name, arguments: r.argsJson },
+          }));
+        }
+      }
+
+      messages.push({
+        role: 'assistant',
+        content: assistantMsg.content ?? null,
+        tool_calls: toolCalls?.map((tc) => ({
+          id: tc.id,
+          type: 'function',
+          function: { name: tc.function.name, arguments: tc.function.arguments },
+        })),
+      });
+
+      if (assistantMsg.content) {
+        const cleaned = assistantMsg.content
+          .replace(/<function=[\w_-]+>?\{[\s\S]*?\}\s*<\/function>/g, '')
+          .trim();
+        if (cleaned) emit({ phase: 'act', kind: 'message', content: cleaned, iteration });
+      }
+
+      if (!toolCalls || toolCalls.length === 0) {
+        finalMessage = assistantMsg.content ?? '';
+        const c = await mintCommitment(canon, {
+          intentId,
+          turnId,
+          claim: finalMessage || '(empty final message)',
+          substrate: ctx.prompt,
+          toolName: null,
+          toolArgs: null,
+          toolResult: null,
+          cwd,
+          packet: ctx.prompt,
+          rules: this.rules,
+        });
+        commitments.push(c);
+        primitivesList.push(c.primitives);
+        emit({ phase: 'record', commitment: c });
+        done = true;
+        break;
+      }
+
+      for (const tc of toolCalls) {
+        let parsedArgs = {};
+        try {
+          parsedArgs = JSON.parse(tc.function.arguments);
+        } catch {
+          messages.push({ role: 'tool', tool_call_id: tc.id, content: JSON.stringify({ error: 'invalid JSON args' }) });
+          continue;
+        }
+
+        emit({ phase: 'act', kind: 'tool_call', name: tc.function.name, args: parsedArgs, iteration });
+
+        if (tc.function.name === 'task_done') {
+          let summary = String(parsedArgs.summary ?? '');
+          // Scrub secrets out of the task_done summary before it is printed or
+          // stored in the canon.
+          const summaryScrub = scrubSecrets(summary);
+          if (summaryScrub.blocked) {
+            summary = `(secrets redacted in summary: ${summaryScrub.findings.map((f) => f.pattern).join(', ')}) ${summaryScrub.redacted}`;
+          }
+          finalMessage = summary;
+          const c = await mintCommitment(canon, {
+            intentId,
+            turnId,
+            claim: summary,
+            substrate: ctx.prompt,
+            toolName: 'task_done',
+            toolArgs: parsedArgs,
+            toolResult: summary,
+            cwd,
+            packet: ctx.prompt,
+            rules: this.rules,
+          });
+          commitments.push(c);
+          primitivesList.push(c.primitives);
+          emit({ phase: 'record', commitment: c });
+          messages.push({ role: 'tool', tool_call_id: tc.id, content: summary });
+          done = true;
+          break;
+        }
+
+        let result;
+        try {
+          result = await runTool(tc.function.name, parsedArgs, cwd);
+        } catch (err) {
+          result = `error: ${err.message}`;
+        }
+
+        // Scrub secrets out of the tool result BEFORE it reaches the terminal,
+        // the canon, or the next model iteration. Tool results are the primary
+        // vector for accidental secret bleed (.env files, private keys on disk,
+        // hardcoded tokens). The scrubber redacts in place.
+        const resultScrub = scrubSecrets(typeof result === 'string' ? result : String(result));
+        if (resultScrub.blocked) {
+          result = `(secrets redacted in tool result: ${resultScrub.findings.map((f) => f.pattern).join(', ')})\n${resultScrub.redacted}`;
+        }
+
+        emit({ phase: 'act', kind: 'tool_result', name: tc.function.name, result, iteration });
+
+        const claim = assistantMsg.content ? assistantMsg.content.slice(0, 500) : `${tc.function.name} call`;
+        const c = await mintCommitment(canon, {
+          intentId,
+          turnId,
+          claim,
+          substrate: typeof result === 'string' ? result : String(result),
+          toolName: tc.function.name,
+          toolArgs: parsedArgs,
+          toolResult: result,
+          cwd,
+          packet: ctx.prompt,
+          rules: this.rules,
+        });
+        commitments.push(c);
+        primitivesList.push(c.primitives);
+        emit({ phase: 'record', commitment: c });
+
+        messages.push({ role: 'tool', tool_call_id: tc.id, content: result });
+      }
+    }
+
+    const durationMs = Date.now() - start;
+    return {
+      finalMessage,
+      iterations: iteration,
+      durationMs,
+      commitments,
+      primitivesList,
+      intentId,
+      turnId,
+      promptTokensUsed: ctx.estimatedTokens,
+      compilerProvider: ctx.compilerProvider,
+    };
+  }
+}

package/lib/canon.mjs

@@ -0,0 +1,123 @@
+// lib/canon.mjs
+// SHA-256 chained append-only JSONL session log. Every turn and every
+// verified tool call is a row. Rows chain by prev_hash to row_hash so a
+// single edit anywhere in the file breaks chain verification at that row.
+// The session is replayable by walking the chain forward from the first row.
+
+import { appendFileSync, existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const ZERO_HASH = '0000000000000000000000000000000000000000000000000000000000000000';
+
+function hashRow(row, prevHash) {
+  const base = JSON.stringify({
+    row_index: row.row_index,
+    ts: row.ts,
+    type: row.type,
+    payload: row.payload,
+    prev_hash: prevHash,
+  });
+  return createHash('sha256').update(base).digest('hex');
+}
+
+export function createCanon(canonFile) {
+  const dir = dirname(canonFile);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (!existsSync(canonFile)) writeFileSync(canonFile, '');
+
+  let rows = loadRows();
+  let lastHash = rows.length > 0 ? rows[rows.length - 1].row_hash : ZERO_HASH;
+  let nextIndex = rows.length;
+
+  function loadRows() {
+    if (!existsSync(canonFile)) return [];
+    const raw = readFileSync(canonFile, 'utf8');
+    const lines = raw.split('\n').filter(Boolean);
+    const out = [];
+    for (const l of lines) {
+      try {
+        out.push(JSON.parse(l));
+      } catch {
+        // Skip malformed lines. The chain verify will catch any integrity break.
+      }
+    }
+    return out;
+  }
+
+  function verify() {
+    let prev = ZERO_HASH;
+    for (let i = 0; i < rows.length; i++) {
+      const r = rows[i];
+      if (r.prev_hash !== prev) {
+        return { valid: false, broken_at: i, reason: `prev_hash mismatch at row ${i}` };
+      }
+      const expected = hashRow(r, prev);
+      if (r.row_hash !== expected) {
+        return { valid: false, broken_at: i, reason: `row_hash mismatch at row ${i}` };
+      }
+      prev = r.row_hash;
+    }
+    return { valid: true, rows: rows.length, last_hash: prev };
+  }
+
+  function append(type, payload) {
+    const row = {
+      row_index: nextIndex,
+      ts: new Date().toISOString(),
+      type,
+      payload,
+      prev_hash: lastHash,
+    };
+    row.row_hash = hashRow(row, lastHash);
+    appendFileSync(canonFile, JSON.stringify(row) + '\n');
+    rows.push(row);
+    lastHash = row.row_hash;
+    nextIndex++;
+    return row;
+  }
+
+  function queryByIntent(intentId, limit = 20) {
+    const matched = [];
+    for (let i = rows.length - 1; i >= 0 && matched.length < limit; i--) {
+      const r = rows[i];
+      if (r.payload && r.payload.intent_id === intentId) matched.push(r);
+    }
+    return matched.reverse();
+  }
+
+  function queryByType(type, limit = 10000) {
+    const matched = [];
+    for (let i = rows.length - 1; i >= 0 && matched.length < limit; i--) {
+      if (rows[i].type === type) matched.push(rows[i]);
+    }
+    return matched.reverse();
+  }
+
+  function activeIntent() {
+    for (let i = rows.length - 1; i >= 0; i--) {
+      if (rows[i].type === 'user_intent') return rows[i];
+    }
+    return null;
+  }
+
+  function size() {
+    return rows.length;
+  }
+
+  function tail(n = 5) {
+    return rows.slice(-n);
+  }
+
+  return {
+    append,
+    queryByIntent,
+    queryByType,
+    activeIntent,
+    size,
+    tail,
+    verify,
+    path: canonFile,
+    lastHash: () => lastHash,
+  };
+}

package/lib/commitment.mjs

@@ -0,0 +1,59 @@
+// lib/commitment.mjs
+// The atomic commit-a-row-to-the-session-log operation. Every tool call and
+// every final message lands in this function. The verification layer runs
+// first; its verdict determines the trust delta and whether the row is
+// marked VERIFIED or REFUTED. The row is then appended to the session log.
+
+import { witness } from './witness/index.mjs';
+
+function trustDelta(verdict) {
+  return (
+    verdict === 'SURVIVED' ? 3 :
+    verdict === 'VERIFIED' ? 1 :
+    verdict === 'REFUTED' ? -2 :
+    verdict === 'CHALLENGED' ? -1 :
+    verdict === 'PENDING' ? -0.1 : 0
+  );
+}
+
+export async function mintCommitment(canon, {
+  intentId,
+  turnId,
+  claim,
+  substrate,
+  toolName,
+  toolArgs,
+  toolResult,
+  cwd,
+  packet,
+  rules,
+}) {
+  const verdictResult = await witness({
+    claim,
+    substrate,
+    toolName,
+    toolArgs,
+    toolResult,
+    cwd,
+    packet,
+    canon,
+    intentId,
+    rules,
+  });
+
+  const delta = trustDelta(verdictResult.verdict);
+
+  const row = canon.append('witnessed_commitment', {
+    intent_id: intentId,
+    turn_id: turnId,
+    claim,
+    tool_name: toolName || null,
+    tool_args: toolArgs || null,
+    tool_result_snippet: typeof toolResult === 'string' ? toolResult.slice(0, 400) : null,
+    verdict: verdictResult.verdict,
+    primitives: verdictResult.primitives,
+    trust_delta: delta,
+  });
+
+  return { row, verdict: verdictResult.verdict, primitives: verdictResult.primitives, trustDelta: delta };
+}