freddie 0.0.88 → 0.0.90

package/AGENTS.md

@@ -302,3 +302,64 @@ To implement:
 4. Register `window.__debug.agents()` observability global
 
 **Blocked on**: Design decision (what metrics? count only? session associations? perf data?). Deferred pending user clarification.
+
+## Trajectory recorder schema v2 (2026-05-12)
+
+`src/agent/machine.js::writeTrajectory()` writes one JSON per turn under `<FREDDIE_HOME>/trajectories/<ts>-<slug>.json` whenever `agent.save_trajectories=true` OR `--witness <path>` is set on `freddie exec`. Schema (`schema_version: 2`):
+
+```
+{
+  schema_version: 2, ts, prompt, provider, model, skill, cwd,
+  iterations, result, error, error_stack,
+  state_transitions: ["PLAN"|"EXECUTE"|"VERIFY"|"COMPLETE", ...],
+  tool_calls: [{name, arguments, id}],
+  tool_results: [{tool_call_id, content}],
+  llm_calls: [{ok, durationMs, provider, model, content_length, tool_calls_count, ts, error?, stack?}],
+  llm_chunks_count, compressor_invocations, events, messages
+}
+```
+
+Optional `--witness <path>` writes a parallel JSONL stream with one event per line (`session_start`, `message`, `llm_call`, `session_end`) for downstream tail/grep. `runTurn({witnessPath})` is the in-code equivalent.
+
+Captured fields per acceptance bar:
+- (a) tool_call args → `tool_calls[].arguments` + `messages[].tool_calls`
+- (b) tool_result → `tool_results[]` + `messages[role:'tool']`
+- (c) LLM call timing/duration/provider/content_length/tool_calls_count → `llm_calls[]`
+- (d) compressor invocations → counted from `messages[role:'system']` matching `[trajectory.compressed]`
+- (e) errors with stack → `error_stack` + per-`llm_call` `stack` field
+
+Witnessed 2026-05-12: mistral-large 4-iteration loop on penguins repo produced 4 successful llm_calls + 1 failing (429 rate-limit) all captured with full stack trace. See `.gm/agent-loop-witness.jsonl` for canonical example.
+
+## LLM validation witness format (.gm/llm-validation.json)
+
+`.gm/llm-validation.json` is the canonical witness for provider reachability. Generated by an out-of-band validator script (per session) that probes every key in `process.env` matching `<PROVIDER>_API_KEY`, plus the acp-daemon endpoints (kilo on 4780, opencode on 4790) and claude-cli subprocess. Shape:
+
+```
+{
+  timestamp, env_keys: [...], targets: [{provider, source, daemonUp}],
+  results: [{provider, ok, ms, excerpt, error, source}],
+  sampler: [{provider, ok, failCount, nextCheckIn}],
+  pass_count, total
+}
+```
+
+Witnessed 2026-05-12: 7/15 pass — groq, google, mistral, openrouter, sambanova, kilo, claude-cli green. opencode-via-acp daemonUp=false until `opencode serve --port 4790` is started (see opencode caveat below).
+
+## opencode CLI shim caveat (2026-05-12)
+
+`opencode-ai@1.14.48` installs successfully via `npm install -g opencode-ai` and exposes a working binary at `C:\Users\user\AppData\Roaming\npm\opencode.cmd` (Windows). The bun-installed shim at `C:\Users\user\.bun\bin\opencode.exe` is BROKEN — its wrapper looks for `C:\Users\user\node_modules\opencode-ai\bin\opencode` (wrong path) and fails with `MODULE_NOT_FOUND`. **Workflow**: use npm version; do NOT `bun install -g opencode-ai`. To start ACP daemon: `& 'C:\Users\user\AppData\Roaming\npm\opencode.cmd' serve --port 4790 --hostname 127.0.0.1`. Verified by GET http://127.0.0.1:4790/ returning 200 (HTML shell). Warning `OPENCODE_SERVER_PASSWORD is not set` is harmless for localhost use.
+
+## gm-cc skill registry (2026-05-12)
+
+`plugins/gm-cc/plugin.js` auto-discovers 12 SKILL.md files from npm `gm-cc` package and registers them via `pi.skills.register({name: 'gm:<name>', description, content, source: 'gm-cc'})`. Registered skills: browser, code-search, create-lang-plugin, gm, gm-complete, gm-emit, gm-execute, governance, pages, planning, ssh, update-docs. Inspect with `node bin/freddie.js skills | findstr gm:`.
+
+## kilo ACP integration (2026-05-12)
+
+`src/agent/llm_resolver.js::acpChat()` (line 33) speaks the kilo ACP protocol: POST `/session` → GET `/event` (SSE) → POST `/session/<id>/message`. Streams `message.part.updated` events to assemble content; terminates on `session.idle`. Required ordering: `/event` must be opened BEFORE `/message` POST or messages drop. Configured in `ACP_BACKENDS` at line 14: kilo on `http://localhost:4780`, opencode on `http://localhost:4790`.
+
+Note: kilo + opencode ACP backends return content only, no tool_calls (the LLM-side tool layer is opaque to freddie). For multi-iteration tool-using loops, use OpenAI-compatible providers (mistral, openrouter, sambanova, groq) instead.
+
+## scripts/sync-upstream.mjs (2026-05-12)
+
+`node scripts/sync-upstream.mjs [--dry-run] [pkg ...]` bumps sibling dep entries (plugsdk, acptoapi, anentrypoint-design, gm-cc) in package.json to `^<latest>` from npm registry, then runs `npm install --package-lock-only`. Skips `file:` deps (local-dev pattern). Wired into `.github/workflows/sync-upstream.yml` (weekly cron + workflow_dispatch) which opens a PR via peter-evans/create-pull-request@v6 when changes land. Dry-run validated: detected `acptoapi: ^1.0.52 -> ^1.0.54`.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freddie",
-  "version": "0.0.88",
+  "version": "0.0.90",
   "type": "module",
   "description": "Open JS agent harness built on pi-mono, floosie, xstate, and anentrypoint-design",
   "bin": {
@@ -27,7 +27,7 @@
     "xstate": "^5.31.0",
     "zod": "^4.0.0",
     "anentrypoint-design": "^0.0.94",
-    "acptoapi": "^1.0.51"
+    "acptoapi": "^1.0.55"
   },
   "optionalDependencies": {
     "@libsql/darwin-arm64": "0.3.19",
@@ -41,6 +41,9 @@
   "engines": {
     "node": ">=20.6.0"
   },
+  "overrides": {
+    "fast-xml-builder": "^1.1.7"
+  },
   "files": [
     "bin/",
     "src/",

package/plugins/core-cli/plugin.js

@@ -15,7 +15,14 @@ export default {
             if (action === 'get' && name) { console.log(JSON.stringify(host.pi.tools.get(name)?.schema, null, 2)); return }
             for (const t of host.pi.tools.list()) console.log(`${(t.toolset || 'core').padEnd(10)} ${t.name}\t${(t.schema?.description || '').slice(0, 60)}`)
         } })
-        C({ name: 'skills', description: 'List skills', args: [{ name: 'action', default: 'list' }], action: () => { for (const s of listSkills()) console.log(`${s.name}\t${(s.description || '').slice(0, 80)}`) } })
+        C({ name: 'skills', description: 'List/show skills (filesystem + registered via pi.skills)', args: [{ name: 'action', default: 'list' }, { name: 'name' }], action: (action, name) => {
+            const fsSkills = listSkills().map(s => ({ name: s.name, description: s.description || '', source: 'fs', body: s.body, file: s.file }))
+            const piSkills = host.pi.skills.list().map(s => ({ name: s.name, description: s.description || '', source: s.source || 'pi', body: s.content || s.body || '', file: s.file }))
+            const seen = new Set(); const all = []
+            for (const s of [...piSkills, ...fsSkills]) { if (seen.has(s.name)) continue; seen.add(s.name); all.push(s) }
+            if (action === 'show' && name) { const s = all.find(x => x.name === name); if (!s) { console.error('skill not found:', name); process.exit(1) } console.log(s.body); return }
+            for (const s of all) console.log(`${(s.source || 'fs').padEnd(8)} ${s.name}\t${s.description.slice(0, 80)}`)
+        } })
         C({ name: 'profile', description: 'Manage profiles', args: [{ name: 'action', default: 'list' }, { name: 'name' }], action: (action, name) => {
             if (action === 'list') { for (const p of listAllProfiles()) console.log(p); return }
             if (action === 'create') { createProfile(name); console.log('created:', name); return }
@@ -49,12 +56,12 @@ export default {
             try { ({ callLLM } = await import('../../src/agent/pi-bridge.js')) } catch {}
             await interactive({ callLLM })
         } })
-        C({ name: 'exec', description: 'Run a single prompt through the agent and exit', options: [{ flag: '--prompt <prompt>', required: true }, { flag: '--model <model>', default: '' }, { flag: '--provider <provider>', default: '' }, { flag: '--skill <skill>', default: '' }, { flag: '--cwd <cwd>', default: '' }, { flag: '--timeout <ms>', default: '60000' }], action: async (opts) => {
+        C({ name: 'exec', description: 'Run a single prompt through the agent and exit', options: [{ flag: '--prompt <prompt>', required: true }, { flag: '--model <model>', default: '' }, { flag: '--provider <provider>', default: '' }, { flag: '--skill <skill>', default: '' }, { flag: '--cwd <cwd>', default: '' }, { flag: '--timeout <ms>', default: '60000' }, { flag: '--witness <path>', default: '' }], action: async (opts) => {
             const { runTurn } = await import('../../src/agent/machine.js')
             let provider = opts.provider || undefined
             let model = opts.model || undefined
             if (!provider && model && /^[a-z][a-z0-9-]*\//.test(model)) { provider = model.split('/')[0]; model = model.slice(provider.length + 1) }
-            const out = await runTurn({ prompt: opts.prompt, provider, model, skill: opts.skill || undefined, cwd: opts.cwd || undefined, timeoutMs: Number(opts.timeout) })
+            const out = await runTurn({ prompt: opts.prompt, provider, model, skill: opts.skill || undefined, cwd: opts.cwd || undefined, timeoutMs: Number(opts.timeout), witnessPath: opts.witness || undefined })
             if (out.error) { console.error('error:', out.error); process.exit(1) }
             console.log(out.result || out.messages?.at(-1)?.content || '')
             process.exit(0)

package/src/agent/llm_resolver.js

@@ -12,7 +12,7 @@ export const PROVIDER_KEYS = sdk.PROVIDER_KEYS
 export const DEFAULTS = sdk.PROVIDER_DEFAULTS
 
 const ACP_BACKENDS = {
-    kilo: { base: 'http://localhost:4780', providerID: 'kilo', defaultModel: 'x-ai/grok-code-fast-1:optimized:free' },
+    kilo: { base: 'http://localhost:4780', providerID: 'kilo', defaultModel: 'openrouter/free' },
     opencode: { base: 'http://localhost:4790', providerID: 'opencode', defaultModel: 'minimax-m2.5-free' },
 }
 
@@ -36,13 +36,12 @@ async function acpChat(prefix, model, input) {
     if (!sessRes.ok) throw new Error(`ACP ${prefix} /session ${sessRes.status}`)
     const sessionId = (await sessRes.json()).id
     const userMsg = input.messages.filter(m => m.role === 'user').slice(-1)[0]?.content || ''
-    const body = { parts: [{ type: 'text', text: String(userMsg) }] }
-    if (b.providerID === 'opencode') body.model = { providerID: 'opencode', modelID: model || b.defaultModel }
-    else { body.providerID = 'kilo'; body.modelID = model || b.defaultModel }
-    await fetch(`${b.base}/session/${sessionId}/message`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(120000) })
-    let content = ''
+    const body = { parts: [{ type: 'text', text: String(userMsg) }], model: { providerID: b.providerID, modelID: model || b.defaultModel } }
     const evRes = await fetch(`${b.base}/event`, { method: 'GET', signal: AbortSignal.timeout(120000) })
     if (!evRes.ok) throw new Error(`ACP ${prefix} /event ${evRes.status}`)
+    const msgRes = await fetch(`${b.base}/session/${sessionId}/message`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(120000) })
+    if (!msgRes.ok) throw new Error(`ACP ${prefix} /message ${msgRes.status}: ${(await msgRes.text()).slice(0,200)}`)
+    let content = ''; let sawAssistantText = false
     const reader = evRes.body.getReader(); const dec = new TextDecoder(); let buf = ''
     while (true) {
         const { value, done } = await reader.read(); if (done) break
@@ -52,9 +51,10 @@ async function acpChat(prefix, model, input) {
             if (!raw.startsWith('data: ')) continue
             try { const ev = JSON.parse(raw.slice(6))
                 if (ev.properties?.sessionID && ev.properties.sessionID !== sessionId) continue
-                if (ev.properties?.part?.type === 'text' && ev.properties.part.text) content += ev.properties.part.text
-                if (ev.event === 'session.complete' || ev.properties?.complete) return { content: content.trim(), tool_calls: [], raw: { provider: prefix, model } }
-            } catch {}
+                if (ev.type === 'message.part.updated' && ev.properties?.part?.type === 'text' && ev.properties.part.text) { content = ev.properties.part.text; sawAssistantText = true }
+                if (ev.type === 'session.error') throw new Error(`ACP ${prefix} session.error: ${JSON.stringify(ev.properties?.error || {}).slice(0,200)}`)
+                if (ev.type === 'session.idle') return { content: content.trim(), tool_calls: [], raw: { provider: prefix, model } }
+            } catch (e) { if (/session.error/.test(e.message)) throw e }
         }
     }
     return { content: content.trim(), tool_calls: [], raw: { provider: prefix, model } }
@@ -115,7 +115,9 @@ function tryParseJson(s) { try { return typeof s === 'string' ? JSON.parse(s) :
 async function hasKey(provider) {
     if (provider === 'claude-cli' || provider === 'kilo' || provider === 'opencode') return true
     const resolved = await resolveKey(provider).catch(() => ({ value: null }))
-    return !!resolved.value
+    if (!resolved.value) return false
+    if (provider === 'cloudflare' && !process.env.CLOUDFLARE_ACCOUNT_ID) return false
+    return true
 }
 
 function defaultModel(provider) {

package/src/agent/machine.js

@@ -6,8 +6,19 @@ import { resolveCallLLM } from './llm_resolver.js'
 
 const log = logger('agent')
 
-export function createAgentMachine({ provider, model, maxIterations = 90, callLLM, enabledToolsets = ['core'], disabledToolsets = [] } = {}) {
-    const llm = callLLM || resolveCallLLM({ provider, model })
+export function createAgentMachine({ provider, model, maxIterations = 90, callLLM, enabledToolsets = ['core'], disabledToolsets = [], events } = {}) {
+    const baseLLM = callLLM || resolveCallLLM({ provider, model })
+    const llm = events ? async (input) => {
+        const t0 = Date.now()
+        try {
+            const out = await baseLLM(input)
+            events.push({ type: 'llm_call', ok: true, durationMs: Date.now() - t0, provider: out?.raw?.provider || provider, model: out?.raw?.model || model, content_length: (out?.content || '').length, tool_calls_count: (out?.tool_calls || []).length, ts: new Date().toISOString() })
+            return out
+        } catch (e) {
+            events.push({ type: 'llm_call', ok: false, durationMs: Date.now() - t0, provider, model, error: String(e?.message || e), stack: e?.stack || null, ts: new Date().toISOString() })
+            throw e
+        }
+    } : baseLLM
     return createMachine({
         id: 'freddie-agent',
         initial: 'idle',
@@ -85,10 +96,10 @@ export function createAgentMachine({ provider, model, maxIterations = 90, callLL
     })
 }
 
-async function writeTrajectory(out, { prompt, provider, model, skill, cwd }) {
+async function writeTrajectory(out, { prompt, provider, model, skill, cwd, events = [], errorStack = null, witnessPath = null }) {
     try {
         const { getConfigValue } = await import('../config.js')
-        if (!getConfigValue('agent.save_trajectories', false)) return
+        if (!getConfigValue('agent.save_trajectories', false) && !witnessPath) return
         const { getFreddieHome } = await import('../home.js')
         const fs = await import('node:fs')
         const path = await import('node:path')
@@ -96,25 +107,44 @@ async function writeTrajectory(out, { prompt, provider, model, skill, cwd }) {
         fs.mkdirSync(dir, { recursive: true })
         const states = []
         const toolCalls = []
+        const toolResults = []
+        let compressorInvocations = 0
         for (const m of out.messages || []) {
-            if (m.role === 'assistant' && m.tool_calls?.length) { states.push('EXECUTE'); for (const tc of m.tool_calls) toolCalls.push({ name: tc.name || tc.function?.name, arguments: tc.arguments || tc.function?.arguments || {} }) }
+            if (m.role === 'assistant' && m.tool_calls?.length) { states.push('EXECUTE'); for (const tc of m.tool_calls) toolCalls.push({ name: tc.name || tc.function?.name, arguments: tc.arguments || tc.function?.arguments || {}, id: tc.id }) }
             else if (m.role === 'user') states.push('PLAN')
             else if (m.role === 'assistant') states.push('COMPLETE')
-            else if (m.role === 'tool') states.push('VERIFY')
+            else if (m.role === 'tool') { states.push('VERIFY'); toolResults.push({ tool_call_id: m.tool_call_id, content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content) }) }
+            if (m.role === 'system' && typeof m.content === 'string' && /\[trajectory\.compressed\]/.test(m.content)) compressorInvocations += 1
         }
         const ts = new Date().toISOString().replace(/[:.]/g, '-').replace(/Z$/, '')
         const slug = (prompt || 'turn').slice(0, 40).replace(/[^a-zA-Z0-9-]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase()
+        const llmCalls = events.filter(e => e.type === 'llm_call')
+        const streamChunks = events.filter(e => e.type === 'llm_chunk')
+        const payload = {
+            schema_version: 2, ts, prompt, provider, model, skill, cwd,
+            iterations: out.iterations, result: out.result, error: out.error, error_stack: errorStack,
+            state_transitions: states, tool_calls: toolCalls, tool_results: toolResults,
+            llm_calls: llmCalls, llm_chunks_count: streamChunks.length,
+            compressor_invocations: compressorInvocations,
+            events, messages: out.messages,
+        }
         const file = path.join(dir, `${ts}-${slug}.json`)
-        fs.writeFileSync(file, JSON.stringify({
-            ts, prompt, provider, model, skill, cwd,
-            iterations: out.iterations, result: out.result, error: out.error,
-            state_transitions: states, tool_calls: toolCalls,
-            messages: out.messages,
-        }, null, 2))
+        fs.writeFileSync(file, JSON.stringify(payload, null, 2))
+        if (witnessPath) {
+            const jsonl = [
+                JSON.stringify({ event: 'session_start', ts, prompt, provider, model, skill, cwd }),
+                ...(out.messages || []).map((m, i) => JSON.stringify({ event: 'message', index: i, role: m.role, content: m.content, tool_calls: m.tool_calls || null, tool_call_id: m.tool_call_id || null })),
+                ...llmCalls.map(e => JSON.stringify({ event: 'llm_call', ...e })),
+                JSON.stringify({ event: 'session_end', iterations: out.iterations, error: out.error, error_stack: errorStack, compressor_invocations: compressorInvocations }),
+            ].join('\n')
+            fs.mkdirSync(path.dirname(witnessPath), { recursive: true })
+            fs.writeFileSync(witnessPath, jsonl)
+        }
     } catch (_) {}
 }
 
-export async function runTurn({ prompt, messages = [], model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill } = {}) {
+export async function runTurn({ prompt, messages = [], model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath } = {}) {
+    const events = []
     const initMessages = [...messages]
     const systemParts = []
     if (cwd) systemParts.push(`Working directory: ${cwd}. Always pass cwd="${cwd}" to bash tool calls. When reading or writing files use paths relative to this directory or absolute paths under it.`)
@@ -124,7 +154,7 @@ export async function runTurn({ prompt, messages = [], model, provider, callLLM,
         if (skillDef?.content) systemParts.push('Skill context:\n' + skillDef.content)
     }
     if (systemParts.length > 0) initMessages.unshift({ role: 'user', content: systemParts.join('\n\n') })
-    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations })
+    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events })
     const actor = createActor(machine, { input: { messages: initMessages } })
     actor.start()
     actor.send({ type: 'SUBMIT', prompt })
@@ -133,7 +163,8 @@ export async function runTurn({ prompt, messages = [], model, provider, callLLM,
         actor.subscribe(snap => {
             if (snap.status === 'done') {
                 clearTimeout(t)
-                writeTrajectory(snap.output, { prompt, provider, model, skill, cwd }).finally(() => resolve(snap.output))
+                const errorStack = snap.output?.error ? (events.find(e => e.type === 'llm_call' && !e.ok)?.stack || null) : null
+                writeTrajectory(snap.output, { prompt, provider, model, skill, cwd, events, errorStack, witnessPath }).finally(() => resolve(snap.output))
             }
         })
     })