@polylogicai/polycode 1.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Andrew Salvo / Polylogic AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Polycode is inspired by Claude Code's public architecture. No Claude Code
+code or system prompts are copied. Not affiliated with Anthropic.

package/README.md

@@ -0,0 +1,107 @@
+# polycode
+
+An agentic coding CLI. Runs on your machine with your keys. Every turn is appended to a SHA-256 chained session log on disk, so your history is auditable, replayable, and portable across machines.
+
+## Install
+
+```bash
+npm install -g @polylogicai/polycode
+```
+
+## Quick start
+
+```bash
+export GROQ_API_KEY=gsk_...
+polycode
+```
+
+That opens an interactive session. For one-shot mode, pass your prompt as an argument:
+
+```bash
+polycode "read README.md and summarize it in one sentence"
+```
+
+A free Groq API key is available at `console.groq.com`.
+
+## Configuration
+
+polycode reads configuration from environment variables and optionally from a `~/.polycode/secrets.env` file (chmod 600 recommended).
+
+| Variable | Purpose | Required |
+|---|---|---|
+| `GROQ_API_KEY` | Primary inference key for tool-use and reasoning | yes |
+| `ANTHROPIC_API_KEY` | Optional high-quality tier for long sessions | no |
+| `POLYCODE_MODEL` | Override the default model | no |
+| `POLYCODE_CWD` | Override the working directory | no |
+
+## Usage
+
+polycode runs a standard agentic loop: you ask, it thinks, it uses tools, it returns a result. Available tools are:
+
+- `bash` run a shell command in the working directory
+- `read_file` read a file relative to the working directory
+- `write_file` write a file to the working directory
+- `edit_file` replace a substring in a file
+- `glob` list files matching a pattern
+- `grep` search for a regex in files
+
+All tool calls are sandboxed to the working directory. polycode refuses any path that escapes it.
+
+## Session history
+
+Every turn polycode takes is appended to a SHA-256 chained JSONL file at `~/.polycode/history/YYYY-MM-DD.jsonl`. You own this file. You can:
+
+- Read it to see exactly what the agent did
+- Back it up by copying it
+- Hand it to a teammate, who can replay the session on their machine
+- Run `polycode --verify` to confirm the chain is intact
+
+## Slash commands
+
+Inside the REPL:
+
+```
+/help      show all commands
+/clear     clear the terminal
+/history   show the session history file path and row count
+/verify    verify session history integrity
+/exit      leave polycode
+```
+
+## Command-line flags
+
+```
+polycode                    interactive REPL
+polycode "<prompt>"         one-shot mode
+polycode --version          print version
+polycode --help             print help
+polycode --history          print session history status
+polycode --verify           verify session history integrity
+```
+
+## Safety rules
+
+polycode enforces a small set of non-negotiable safety rules out of the box:
+
+- Shell commands referencing system paths (`/etc/passwd`, `~/.ssh`, private key files) are refused
+- Code patterns that evaluate untrusted input are refused
+- Tool output containing recognized secret patterns (AWS, GitHub, Stripe, Anthropic, Groq, PEM blocks) is redacted before it reaches the model or the terminal
+
+Rules live in `~/.polycode/rules.yaml`. You can add your own.
+
+## Requirements
+
+- Node.js 20 or newer
+- macOS or Linux
+- A Groq API key
+
+## Documentation and support
+
+- Install and usage: `polylogicai.com/polycode`
+- Issues and questions: `ajs10845@psu.edu`
+
+## License
+
+MIT. See `LICENSE`. Built by Polylogic AI.
+
+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.

package/bin/polycode.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+// bin/polycode.mjs
+// polycode CLI entry point. Runs on your machine with your keys. Writes an
+// append-only session log on disk.
+//
+// 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.
+
+import { AgenticLoop } from '../lib/agentic.mjs';
+import { createCanon } from '../lib/canon.mjs';
+import { createRenderer, C } from '../lib/repl-ui.mjs';
+import { dispatchSlash } from '../lib/slash-commands.mjs';
+import { computeAgencyReceipt, formatReceipt } from '../lib/agency-receipt.mjs';
+import { fireHook } from '../lib/hooks.mjs';
+import { compilePacket } from '../lib/compiler.mjs';
+import { loadAnthropicKeys, reportKeyStatus } from '../lib/inference-router.mjs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import * as readline from 'node:readline/promises';
+import { stdin, stdout, exit, argv, env, cwd as getCwd } from 'node:process';
+import 'dotenv/config';
+
+function loadAmbientEnv() {
+  const candidates = [
+    join(homedir(), '.polycode/secrets.env'),
+    join(homedir(), 'orchestrator/.env'),
+    join(homedir(), '.polycode/.env'),
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const content = readFileSync(p, 'utf8');
+      for (const line of content.split('\n')) {
+        if (line.startsWith('#')) continue;
+        const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+        if (match && !env[match[1]]) {
+          env[match[1]] = match[2].replace(/^['"]|['"]$/g, '');
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+}
+
+loadAmbientEnv();
+
+function loadRules() {
+  const candidates = [
+    join(homedir(), '.polycode', 'rules.yaml'),
+    join(homedir(), 'polycode', 'rules', 'default.yaml'),
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const content = readFileSync(p, 'utf8');
+      // Minimal YAML parser for the flat subset we use: top-level scalars, top-level
+      // lists, and one level of nested map or list under a top-level key.
+      const rules = {};
+      let currentTopKey = null;
+      let currentTopIsList = false;
+      let currentNestedList = null;
+      for (const rawLine of content.split('\n')) {
+        const line = rawLine.replace(/#.*$/, '').replace(/\s+$/, '');
+        if (!line.trim()) continue;
+        const topMatch = line.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+        if (topMatch && !line.startsWith(' ')) {
+          currentTopKey = topMatch[1];
+          currentNestedList = null;
+          const inlineVal = topMatch[2].trim();
+          if (inlineVal === '') {
+            // May be a map or a list; decided by the next indented line.
+            rules[currentTopKey] = undefined;
+            currentTopIsList = false;
+          } else if (/^\[.*\]$/.test(inlineVal)) {
+            rules[currentTopKey] = inlineVal.slice(1, -1).split(',').map((x) => x.trim().replace(/^['"]|['"]$/g, ''));
+            currentTopIsList = false;
+          } else if (/^-?\d+(\.\d+)?$/.test(inlineVal)) {
+            rules[currentTopKey] = Number(inlineVal);
+            currentTopIsList = false;
+          } else if (inlineVal === 'true' || inlineVal === 'false') {
+            rules[currentTopKey] = inlineVal === 'true';
+            currentTopIsList = false;
+          } else {
+            rules[currentTopKey] = inlineVal.replace(/^['"]|['"]$/g, '');
+            currentTopIsList = false;
+          }
+          continue;
+        }
+        const topListMatch = line.match(/^\s{2}-\s*(.+)$/);
+        if (topListMatch && currentTopKey) {
+          if (!Array.isArray(rules[currentTopKey])) {
+            rules[currentTopKey] = [];
+            currentTopIsList = true;
+          }
+          rules[currentTopKey].push(topListMatch[1].trim().replace(/^['"]|['"]$/g, ''));
+          continue;
+        }
+        const subMatch = line.match(/^\s{2}([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+        if (subMatch && currentTopKey && !currentTopIsList) {
+          if (typeof rules[currentTopKey] !== 'object' || Array.isArray(rules[currentTopKey])) {
+            rules[currentTopKey] = {};
+          }
+          const subKey = subMatch[1];
+          const subVal = subMatch[2].trim();
+          if (subVal === '') {
+            rules[currentTopKey][subKey] = [];
+            currentNestedList = rules[currentTopKey][subKey];
+          } else if (/^-?\d+(\.\d+)?$/.test(subVal)) {
+            rules[currentTopKey][subKey] = Number(subVal);
+            currentNestedList = null;
+          } else if (subVal === 'true' || subVal === 'false') {
+            rules[currentTopKey][subKey] = subVal === 'true';
+            currentNestedList = null;
+          } else if (/^\[.*\]$/.test(subVal)) {
+            rules[currentTopKey][subKey] = subVal.slice(1, -1).split(',').map((x) => x.trim().replace(/^['"]|['"]$/g, ''));
+            currentNestedList = null;
+          } else {
+            rules[currentTopKey][subKey] = subVal.replace(/^['"]|['"]$/g, '');
+            currentNestedList = null;
+          }
+          continue;
+        }
+        const nestedListMatch = line.match(/^\s{4}-\s*(.+)$/);
+        if (nestedListMatch && currentNestedList) {
+          currentNestedList.push(nestedListMatch[1].trim().replace(/^['"]|['"]$/g, ''));
+        }
+      }
+      return rules;
+    } catch {
+      // next candidate
+    }
+  }
+  return {};
+}
+
+const VERSION = '1.1.0';
+const DOCS_URL = 'https://polylogicai.com/polycode';
+
+const BANNER = `${C.bold}${C.amber}polycode v${VERSION}${C.reset}
+${C.dim}An agentic coding CLI. Your keys, your machine, your session log.${C.reset}
+${C.dim}${DOCS_URL}${C.reset}
+`;
+
+const HELP = `${BANNER}
+
+${C.bold}Usage${C.reset}
+  polycode                          Interactive session
+  polycode "fix the failing test"   One-shot mode
+  polycode --version                Print version
+  polycode --help                   Print this message
+  polycode --history                Print session history status
+  polycode --verify                 Verify session history integrity
+
+${C.bold}Environment${C.reset}
+  GROQ_API_KEY                Required (free tier at console.groq.com)
+  ANTHROPIC_API_KEY           Optional high-quality tier for long sessions
+  POLYCODE_MODEL              Override the default model
+  POLYCODE_CWD                Override the working directory
+
+${C.bold}Documentation${C.reset}
+  ${DOCS_URL}
+`;
+
+function resolveConfigDir() {
+  const dir = join(homedir(), '.polycode');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (!existsSync(join(dir, 'canon'))) mkdirSync(join(dir, 'canon'), { recursive: true });
+  if (!existsSync(join(dir, 'hooks'))) mkdirSync(join(dir, 'hooks'), { recursive: true });
+  return dir;
+}
+
+async function runOneShot(message, { loop, canon, cwd, renderer, state, sessionId, hookDir }) {
+  await fireHook('UserPromptSubmit', {
+    session_id: sessionId, cwd, hook_event_name: 'UserPromptSubmit', prompt: message,
+  }, hookDir);
+
+  const result = await loop.runTurn({
+    canon,
+    userMessage: message,
+    cwd,
+    onEvent: (ev) => renderer.onEvent(ev),
+  });
+
+  state.lastTurnTokens = result.promptTokensUsed;
+  state.lastCompiler = result.compilerProvider;
+
+  const receipt = computeAgencyReceipt({
+    primitivesList: result.primitivesList,
+    wallClockMs: result.durationMs,
+    iterations: result.iterations,
+  });
+  stdout.write(`${C.dim}${formatReceipt(receipt)} . ${canon.size()} rows in log${C.reset}\n`);
+
+  await fireHook('Stop', { session_id: sessionId, cwd, hook_event_name: 'Stop' }, hookDir);
+  return result;
+}
+
+async function runRepl(opts) {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  stdout.write(BANNER + '\n');
+  stdout.write(`${C.dim}session log: ${opts.canon.size()} rows . ${opts.canon.lastHash().slice(0, 12)}...${C.reset}\n`);
+  stdout.write(`${C.dim}type /help for commands. ctrl+c or /exit to leave.${C.reset}\n\n`);
+
+  try {
+    while (true) {
+      const line = await rl.question(`${C.bold}${C.amber}> ${C.reset}`);
+      if (!line.trim()) continue;
+
+      if (line.startsWith('/')) {
+        const result = await dispatchSlash(line, { canon: opts.canon, state: opts.state, stdout });
+        if (result.exit) break;
+        stdout.write('\n');
+        continue;
+      }
+
+      await runOneShot(line, opts);
+      stdout.write('\n');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  const args = argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) { stdout.write(HELP); exit(0); }
+  if (args.includes('--version') || args.includes('-v')) {
+    stdout.write(`polycode ${VERSION}\n`);
+    exit(0);
+  }
+
+  const configDir = resolveConfigDir();
+
+  const apiKey = env.GROQ_API_KEY;
+  if (!apiKey) {
+    stdout.write(`${C.red}polycode error${C.reset}: GROQ_API_KEY is not set.\n`);
+    exit(1);
+  }
+
+  const rules = loadRules();
+  const model = env.POLYCODE_MODEL || 'moonshotai/kimi-k2-instruct';
+  const cwd = env.POLYCODE_CWD || getCwd();
+  const hookDir = env.POLYCODE_HOOK_DIR || join(configDir, 'hooks');
+  const canonFile = env.POLYCODE_CANON_FILE || join(configDir, 'canon', `${new Date().toISOString().slice(0, 10)}.jsonl`);
+
+  const canon = createCanon(canonFile);
+
+  if (args.includes('--history') || args.includes('--log')) {
+    stdout.write(`session log: ${canonFile}\nrows: ${canon.size()}\nlast_hash: ${canon.lastHash()}\n`);
+    exit(0);
+  }
+
+  if (args.includes('--verify')) {
+    const r = canon.verify();
+    if (r.valid) {
+      stdout.write(`${C.amber}session log verified${C.reset}: ${r.rows} rows, last ${r.last_hash}\n`);
+      exit(0);
+    } else {
+      stdout.write(`${C.red}session log broken${C.reset}: ${r.reason}\n`);
+      exit(1);
+    }
+  }
+
+  const packetFlagIndex = args.indexOf('--packet');
+  if (packetFlagIndex >= 0) {
+    const question = args.slice(packetFlagIndex + 1).join(' ').replace(/^["']|["']$/g, '') || 'default';
+    const pkt = await compilePacket(canon, question, cwd);
+    stdout.write(`--- polycode compile-packet preview ---\n`);
+    stdout.write(`compiler: ${pkt.compilerProvider}\n`);
+    stdout.write(`estimated_tokens: ${pkt.estimatedTokens}\n`);
+    stdout.write(`selected_rows: ${JSON.stringify(pkt.selectedRows)}\n`);
+    stdout.write(`fallback: ${pkt.fallback}\n`);
+    stdout.write(`---\n`);
+    stdout.write(pkt.prompt + '\n');
+    stdout.write(`---\n`);
+    exit(0);
+  }
+
+  const sessionId = randomUUID();
+  canon.append('session_start', { session_id: sessionId, cwd, model });
+
+  await fireHook('SessionStart', {
+    session_id: sessionId,
+    cwd,
+    hook_event_name: 'SessionStart',
+    matcher: 'startup',
+    canon_path: canonFile,
+  }, hookDir);
+
+  const loop = new AgenticLoop({ apiKey, model, rules });
+  const renderer = createRenderer(stdout);
+  const state = { lastTurnTokens: 0, lastCompiler: null };
+  const opts = { loop, canon, cwd, renderer, state, sessionId, hookDir };
+
+  const positional = args.filter((a) => !a.startsWith('--') && args[args.indexOf(a) - 1] !== '--packet');
+  if (positional.length > 0) {
+    await runOneShot(positional.join(' '), opts);
+  } else {
+    await runRepl(opts);
+  }
+
+  canon.append('session_end', { session_id: sessionId });
+  await fireHook('SessionEnd', { session_id: sessionId, cwd, hook_event_name: 'SessionEnd' }, hookDir);
+
+  exit(0);
+}
+
+main().catch((err) => {
+  stdout.write(`${C.red}polycode error${C.reset}: ${err.message}\n`);
+  if (env.POLYCODE_DEBUG) stdout.write(err.stack + '\n');
+  exit(1);
+});

package/lib/agency-receipt.mjs

@@ -0,0 +1,45 @@
+// lib/agency-receipt.mjs
+// Per-turn receipt computation. Aggregates verification results across all
+// commitments in the turn into a small set of numeric factors and a product.
+// Reported at the end of each REPL turn in plain-text form.
+
+export function computeAgencyReceipt({ primitivesList, wallClockMs, iterations }) {
+  const weights = { PASS: 1, PENDING: 0.5, FAIL: 0 };
+
+  let witnessSum = 0;
+  let witnessCount = 0;
+  let fidelityScalarSum = 0;
+  let fidelityScalarCount = 0;
+
+  for (const p of primitivesList) {
+    if (!p) continue;
+    for (const [name, prim] of Object.entries(p)) {
+      if (name === 'g_fidelity') {
+        if (typeof prim.scalar === 'number') {
+          fidelityScalarSum += prim.scalar;
+          fidelityScalarCount++;
+        }
+        continue;
+      }
+      const w = weights[prim?.verdict];
+      if (w != null) {
+        witnessSum += w;
+        witnessCount++;
+      }
+    }
+  }
+
+  const V = witnessCount > 0 ? witnessSum / witnessCount : 0;
+  const G = fidelityScalarCount > 0 ? fidelityScalarSum / fidelityScalarCount : 0.5;
+  const I = V * G;
+  const seconds = wallClockMs / 1000;
+  const E = iterations > 0 ? (seconds * 10) / iterations : seconds;
+  const A = I * E;
+
+  return { V, G, I, E, A, seconds, iterations };
+}
+
+export function formatReceipt(r) {
+  // Unambiguous-decimal format. Parsers can split on space-delimited keys.
+  return `Agency: V=${r.V.toFixed(2)} G=${r.G.toFixed(2)} I=${r.I.toFixed(2)} E=${r.E.toFixed(2)} A=${r.A.toFixed(2)} . ${r.seconds.toFixed(2)}s . ${r.iterations} iter`;
+}