freddie 0.0.120 → 0.0.122

package/plugins/platform-discord/handler.js

@@ -1,4 +1,10 @@
 import { EventEmitter } from 'node:events'
+import WebSocket from 'ws'
+
+// Discord gateway opcodes
+const OP = { DISPATCH: 0, HEARTBEAT: 1, IDENTIFY: 2, RESUME: 6, RECONNECT: 7, INVALID_SESSION: 9, HELLO: 10, HEARTBEAT_ACK: 11 }
+// GUILD_MESSAGES(1<<9) + DIRECT_MESSAGES(1<<12) + MESSAGE_CONTENT(1<<15)
+const DEFAULT_INTENTS = (1 << 9) | (1 << 12) | (1 << 15)
 
 export class DiscordAdapter extends EventEmitter {
     constructor(opts = {}) {
@@ -6,16 +12,92 @@ export class DiscordAdapter extends EventEmitter {
         this.platform = 'discord'
         this.token = opts.token || process.env.DISCORD_BOT_TOKEN
         this.api = opts.api || 'https://discord.com/api/v10'
+        this.intents = opts.intents ?? DEFAULT_INTENTS
+        this.receive = opts.receive !== false   // open the gateway WS to receive messages
         this._ws = null
+        this._heartbeat = null
+        this._seq = null
+        this._sessionId = null
+        this._resumeUrl = null
+        this._acked = true
+        this._closed = false
     }
     getRequiredEnv() { return ['DISCORD_BOT_TOKEN'] }
+
     async start() {
         if (!this.token) throw new Error('DiscordAdapter: DISCORD_BOT_TOKEN required')
         const gw = await fetch(`${this.api}/gateway/bot`, { headers: { authorization: `Bot ${this.token}` } }).then(r => r.json())
         if (!gw.url) throw new Error('DiscordAdapter: gateway lookup failed: ' + JSON.stringify(gw))
         this.gatewayUrl = gw.url + '/?v=10&encoding=json'
+        // Open the gateway WebSocket so inbound messages are emitted as 'message'
+        // events { from, text, raw, platform }. Without this the adapter can send
+        // but never receives.
+        if (this.receive) { this._closed = false; this._connect() }
+    }
+
+    _connect(resume = false) {
+        const url = resume && this._resumeUrl ? this._resumeUrl + '/?v=10&encoding=json' : this.gatewayUrl
+        const ws = this._ws = new WebSocket(url)
+        ws.on('message', (raw) => {
+            let p; try { p = JSON.parse(raw.toString()) } catch { return }
+            if (p.s != null) this._seq = p.s
+            switch (p.op) {
+                case OP.HELLO:
+                    this._startHeartbeat(p.d.heartbeat_interval)
+                    if (resume && this._sessionId) this._send({ op: OP.RESUME, d: { token: this.token, session_id: this._sessionId, seq: this._seq } })
+                    else this._identify()
+                    break
+                case OP.HEARTBEAT: this._send({ op: OP.HEARTBEAT, d: this._seq }); break
+                case OP.HEARTBEAT_ACK: this._acked = true; break
+                case OP.RECONNECT: this._reconnect(true); break
+                case OP.INVALID_SESSION: this._sessionId = null; setTimeout(() => this._reconnect(false), 1500); break
+                case OP.DISPATCH: this._dispatch(p); break
+            }
+        })
+        ws.on('close', () => {
+            clearInterval(this._heartbeat)
+            if (!this._closed) setTimeout(() => this._reconnect(true), 2500)
+        })
+        ws.on('error', () => { /* close handler drives reconnect */ })
+    }
+
+    _dispatch(p) {
+        if (p.t === 'READY') { this._sessionId = p.d?.session_id; this._resumeUrl = p.d?.resume_gateway_url; return }
+        if (p.t === 'MESSAGE_CREATE') {
+            const m = p.d
+            if (m.author?.bot) return   // ignore bots and our own messages
+            this.emit('message', { from: m.author?.id, text: m.content || '', raw: m, platform: 'discord' })
+        }
+    }
+
+    _identify() {
+        this._send({ op: OP.IDENTIFY, d: { token: this.token, intents: this.intents, properties: { os: 'linux', browser: 'freddie', device: 'freddie' } } })
     }
-    async stop() { try { this._ws?.close?.() } catch {} }
+
+    _startHeartbeat(interval) {
+        clearInterval(this._heartbeat)
+        this._acked = true
+        this._heartbeat = setInterval(() => {
+            if (!this._acked) { try { this._ws.terminate() } catch {} return }   // zombie connection
+            this._acked = false
+            this._send({ op: OP.HEARTBEAT, d: this._seq })
+        }, interval)
+    }
+
+    _reconnect(resume) {
+        if (this._closed) return
+        try { this._ws?.removeAllListeners?.(); this._ws?.close?.() } catch {}
+        this._connect(resume)
+    }
+
+    _send(obj) { try { this._ws?.send(JSON.stringify(obj)) } catch {} }
+
+    async stop() {
+        this._closed = true
+        clearInterval(this._heartbeat)
+        try { this._ws?.close?.() } catch {}
+    }
+
     async send(reply) {
         if (!this.token) throw new Error('DiscordAdapter: token required')
         const url = `${this.api}/channels/${reply.to}/messages`

package/plugins/platform-whatsapp/handler.js

@@ -1,4 +1,5 @@
 import express from 'express'
+import crypto from 'node:crypto'
 import { EventEmitter } from 'node:events'
 
 export class WhatsappAdapter extends EventEmitter {
@@ -8,24 +9,49 @@ export class WhatsappAdapter extends EventEmitter {
         this.token = opts.token || process.env.WHATSAPP_API_TOKEN
         this.phoneId = opts.phoneId || process.env.WHATSAPP_PHONE_NUMBER_ID
         this.verifyToken = opts.verifyToken || process.env.WHATSAPP_VERIFY_TOKEN || 'freddie'
-        this.port = opts.port || 0
+        // App secret enables X-Hub-Signature-256 verification on inbound webhooks.
+        // When set, unsigned or wrongly-signed requests are rejected.
+        this.appSecret = opts.appSecret || process.env.WHATSAPP_APP_SECRET || ''
+        this.port = opts.port ?? Number(process.env.WHATSAPP_WEBHOOK_PORT || 0)
+        this.path = opts.path || process.env.WHATSAPP_WEBHOOK_PATH || '/webhook'
         this.api = opts.api || 'https://graph.facebook.com/v20.0'
         this._server = null
     }
     getRequiredEnv() { return ['WHATSAPP_API_TOKEN', 'WHATSAPP_PHONE_NUMBER_ID'] }
+
+    // Verify Meta's HMAC-SHA256 signature over the raw request body.
+    _verifySignature(req) {
+        if (!this.appSecret) return true   // verification disabled when no secret
+        const sig = req.get('x-hub-signature-256') || ''
+        if (!sig.startsWith('sha256=')) return false
+        const expected = 'sha256=' + crypto.createHmac('sha256', this.appSecret).update(req.rawBody || Buffer.alloc(0)).digest('hex')
+        try { return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)) } catch { return false }
+    }
+
     async start() {
         if (!this.token || !this.phoneId) throw new Error('WhatsappAdapter: WHATSAPP_API_TOKEN + WHATSAPP_PHONE_NUMBER_ID required')
         const app = express()
-        app.use(express.json())
-        app.get('/webhook', (req, res) => {
+        // Capture the raw body so the signature can be verified over exact bytes.
+        app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf } }))
+
+        app.get(this.path, (req, res) => {
             if (req.query['hub.verify_token'] === this.verifyToken) return res.send(req.query['hub.challenge'])
             res.sendStatus(403)
         })
-        app.post('/webhook', (req, res) => {
+        app.post(this.path, (req, res) => {
+            if (!this._verifySignature(req)) return res.sendStatus(401)
             const entries = req.body?.entry || []
             for (const e of entries) for (const c of (e.changes || [])) {
                 const msgs = c.value?.messages || []
-                for (const m of msgs) this.emit('message', { from: m.from, text: m.text?.body || '', raw: m })
+                for (const m of msgs) {
+                    this.emit('message', {
+                        from: m.from,
+                        text: m.text?.body || '',
+                        // surface the platform message id for dedup, and the message type
+                        // so media-only messages are recognisable upstream.
+                        raw: { ...m, id: m.id, type: m.type },
+                    })
+                }
             }
             res.json({ ok: true })
         })

package/src/acp/server.js

@@ -8,6 +8,7 @@ import { checkPermission, rememberAllow, rememberDeny } from './permissions.js'
 import { AcpSessionManager } from './session.js'
 import { createMachine, createActor } from 'xstate'
 import { persist, load, clear } from '../machines/snapshot-store.js'
+import { runStep, clearSteps } from '../machines/step-journal.js'
 
 const log = logger('acp')
 
@@ -40,7 +41,7 @@ export class AcpServer extends EventEmitter {
         this._pendingPerm = new Map()
         this.machine = createAcpMachine()
         this.actor = createActor(this.machine)
-        this.actor.subscribe(() => { persist('acp', 'lifecycle', this.actor.getPersistedSnapshot()).catch(() => {}) })
+        this.actor.subscribe(() => { persist('acp', 'lifecycle', this.actor.getPersistedSnapshot()).catch(e => log.error('acp lifecycle persist failed', { err: String(e) })) })
         this.actor.start()
     }
     get state() { return this.actor.getSnapshot().value }
@@ -102,9 +103,15 @@ const METHODS = {
         // refresh mid-turn is observable + resumable (the agent snapshot for the
         // turn itself lives under kind=agent via runTurn sessionKey).
         await persist('acp-prompt', sessionId, { status: 'active', value: 'running', context: { sessionId, prompt } })
-        const out = await runTurn({ prompt, callLLM: srv.callLLM, sessionKey: 'acp:' + sessionId })
+        const sk = 'acp:' + sessionId
+        // The agent turn itself is step-journaled under sessionKey=sk (at-most-once
+        // LLM + tool effects). The post-turn persistence (session append) is its
+        // own journaled step so a crash between runTurn return and appendAssistant
+        // does not double-append on resume.
+        const out = await runTurn({ prompt, callLLM: srv.callLLM, sessionKey: sk })
+        await runStep(sk, 'acp-persist', async () => { await srv.sessions.appendAssistant(sessionId, out.result || ''); return { ok: true } })
         await clear('acp-prompt', sessionId)
-        srv.sessions.appendAssistant(sessionId, out.result || '')
+        await clearSteps(sk)
         Events.messageComplete((o) => srv.send(o), { sessionId, role: 'assistant', content: out.result || '' })
         return { result: out.result, error: out.error, iterations: out.iterations }
     },

package/src/acp/tools.js

@@ -2,7 +2,11 @@ import { bootHost } from '../host/index.js'
 import { Events } from './events.js'
 export async function listToolsForAcp() {
     const h = await bootHost()
-    return h.pi.tools.list().map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema, requiresEnv: t.requiresEnv || [] }))
+    // Advertise only tools that are actually available (checkFn passes), so an ACP
+    // client is not told about a tool that will fail at invocation for a missing
+    // env var -- upfront honesty over a spurious tool-not-available later.
+    const available = h.pi.tools.list().filter(t => !t.checkFn || t.checkFn(t) !== false)
+    return available.map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema, requiresEnv: t.requiresEnv || [] }))
 }
 export async function dispatchWithEvents({ name, args, send, sessionId = null }) {
     const h = await bootHost()

package/src/agent/acptoapi-bridge.js

@@ -1,4 +1,5 @@
 import { logger } from '../observability/log.js'
+import { parseTextToolCalls } from './tool_call_text.js'
 
 const log = logger('acptoapi')
 
@@ -9,7 +10,12 @@ const log = logger('acptoapi')
 // our AbortController be the single source of truth for the overall deadline
 // (default 240s, override via FREDDIE_LLM_TIMEOUT_MS). Use setGlobalDispatcher
 // once rather than a per-request Agent so we don't leak a dispatcher per call.
-const ACPTOAPI_TIMEOUT_MS = Number(process.env.FREDDIE_LLM_TIMEOUT_MS) || 240000
+// Browser-safe env read: this module evaluates in a plain browser context where
+// `process` is undefined (no node shim yet), so a bare process.env throws
+// "process is not defined" and aborts the whole bundle import. envVal() reads
+// live (picks up a late-installed shim) and never throws.
+const envVal = (k) => { try { return (typeof process !== 'undefined' && process.env) ? process.env[k] : undefined } catch { return undefined } }
+const ACPTOAPI_TIMEOUT_MS = Number(envVal('FREDDIE_LLM_TIMEOUT_MS')) || 240000
 let _dispatcherSet = false
 async function ensureLongTimeoutDispatcher() {
     if (_dispatcherSet) return
@@ -29,20 +35,25 @@ async function ensureLongTimeoutDispatcher() {
 }
 
 export function getAcptoapiUrl() {
-    return process.env.FREDDIE_LLM_URL || 'http://127.0.0.1:4800/v1'
+    return envVal('FREDDIE_LLM_URL') || 'http://127.0.0.1:4800/v1'
 }
 
 export function getAcptoapiModel() {
-    return process.env.FREDDIE_LLM_MODEL || 'claude/haiku'
+    return envVal('FREDDIE_LLM_MODEL') || 'claude/haiku'
 }
 
-export async function callLLM({ messages, tools = [], model } = {}) {
+export async function callLLM({ messages, tools = [], model, tool_choice, cwd = null } = {}) {
     const base = getAcptoapiUrl()
     const useModel = model || getAcptoapiModel()
     const hasTools = Array.isArray(tools) && tools.length > 0
     const adaptedMessages = messages.map(adaptMessage)
-    if (hasTools) {
-        const cwd = process.cwd()
+    // The coder-agent working-directory note is OPT-IN via an explicit `cwd` param.
+    // It used to be injected on every tool-bearing call, which polluted NON-coder
+    // agents' prompts with "use your built-in tools (Bash, Read, Write)" -- tool
+    // hallucination bait plus a filesystem-path leak for hosts (like a contact-facing
+    // chat agent) whose toolset has no such tools. runTurn already composes its own
+    // cwd note when a caller passes cwd; direct callLLM users opt in the same way.
+    if (hasTools && cwd) {
         const sysIdx = adaptedMessages.findIndex(m => m.role === 'system')
         const cwdNote = `\nWorking directory: ${cwd}\nUse your built-in tools (Bash, Read, Write) to explore files in this directory when needed.`
         if (sysIdx >= 0) adaptedMessages[sysIdx] = { ...adaptedMessages[sysIdx], content: (adaptedMessages[sysIdx].content || '') + cwdNote }
@@ -55,9 +66,11 @@ export async function callLLM({ messages, tools = [], model } = {}) {
         max_tokens: 4096,
     }
     if (hasTools) body.tools = tools.map(adaptTool)
+    // Forward a forced tool_choice (e.g. 'required') so a caller can compel a tool
+    // call on a turn. Only when tools are present; absent -> the model chooses.
+    if (hasTools && tool_choice) body.tool_choice = tool_choice
     const headers = { 'content-type': 'application/json', authorization: 'Bearer none' }
-    const cwd = process.cwd()
-    if (Array.isArray(tools) && tools.length) headers['x-cwd'] = cwd
+    if (hasTools && cwd) headers['x-cwd'] = cwd
     // Rely on AbortController timeout. acptoapi v1+ ships CORS + Private
     // Network Access headers so cross-origin loopback (gh-pages → localhost)
     // succeeds when acptoapi is running. The earlier preemptive loopback
@@ -78,7 +91,12 @@ export async function callLLM({ messages, tools = [], model } = {}) {
         const text = await res.text()
         throw new Error(`acptoapi ${res.status}: ${text.slice(0, 400)}`)
     }
-    const json = await res.json()
+    let json
+    try {
+        json = await res.json()
+    } catch (e) {
+        throw new Error(`acptoapi ${res.status}: invalid JSON response: ${String(e)}`)
+    }
     log.info('completed', { model: useModel, usage: json.usage })
     return adaptResponse(json)
 }
@@ -116,6 +134,12 @@ function adaptResponse(r) {
     const tool_calls = Array.isArray(choice.tool_calls)
         ? choice.tool_calls.map(tc => ({ id: tc.id, name: tc.function?.name, arguments: tryParseJson(tc.function?.arguments) }))
         : []
+    // Recover text-format tool calls (kimi <|tool_call_begin|> / llama
+    // <|python_tag|>) from weak models that don't emit structured tool_calls.
+    if (!tool_calls.length) {
+        const textTC = parseTextToolCalls(content)
+        if (textTC.length) return { content: '', tool_calls: textTC, raw: r }
+    }
     return { content, tool_calls, raw: r }
 }
 

package/src/agent/llm_resolver.js

@@ -1,6 +1,7 @@
 import { getConfigValue } from '../config.js'
 import { MATRIX_FILE } from './model-matrix.js'
 import { callLLM as bridgeCall, isReachable as bridgeReachable } from './acptoapi-bridge.js'
+import { parseTextToolCalls } from './tool_call_text.js'
 import * as sdkNs from 'acptoapi'
 export { matrixUsable } from './model-matrix.js'
 
@@ -42,7 +43,15 @@ function adapt(result) {
     const flat = flattenContent(c.content)
     const openaiTC = Array.isArray(c.tool_calls) ? c.tool_calls.map(tc => ({ id: tc.id, name: tc.function?.name, arguments: tryJson(tc.function?.arguments) })) : []
     const anthropicTC = flat.toolUses.map(t => ({ id: t.id, name: t.name, arguments: t.input || {} }))
-    return { content: flat.text, tool_calls: openaiTC.concat(anthropicTC), raw: result }
+    const tool_calls = openaiTC.concat(anthropicTC)
+    // Weak models may emit tool calls as text (kimi <|tool_call_begin|> / llama
+    // <|python_tag|>) instead of structured tool_calls. Recover them so the loop
+    // iterates; clear the text content since it was the call, not a reply.
+    if (!tool_calls.length) {
+        const textTC = parseTextToolCalls(flat.text)
+        if (textTC.length) return { content: '', tool_calls: textTC, raw: result }
+    }
+    return { content: flat.text, tool_calls, raw: result }
 }
 
 // Names callers can use as model= to select a curated acptoapi chain.

package/src/agent/machine.js

@@ -4,11 +4,12 @@ import { getEnabledToolSchemas } from '../toolsets.js'
 import { logger } from '../observability/log.js'
 import { resolveCallLLM } from './llm_resolver.js'
 import { createPersistentActor } from '../machines/persistent-actor.js'
+import { runStep, clearSteps } from '../machines/step-journal.js'
 import { randomUUID } from 'node:crypto'
 
 const log = logger('agent')
 
-export function createAgentMachine({ provider, model, maxIterations = 90, callLLM, enabledToolsets = ['core'], disabledToolsets = [], events } = {}) {
+export function createAgentMachine({ provider, model, maxIterations = 90, callLLM, enabledToolsets = ['core'], disabledToolsets = [], events, sessionKey, toolCtx = null, tool_choice } = {}) {
     const baseLLM = callLLM || resolveCallLLM({ provider, model })
     const llm = events ? async (input) => {
         const t0 = Date.now()
@@ -34,6 +35,20 @@ export function createAgentMachine({ provider, model, maxIterations = 90, callLL
             error: null,
             provider, model,
             enabledToolsets, disabledToolsets,
+            sessionKey,
+            // Optional tool_choice policy. A FUNCTION receives the iteration index and
+            // returns the tool_choice for that llm call (full caller control). A plain
+            // VALUE (e.g. 'required') applies on ITERATION 0 ONLY, then reverts to the
+            // model's own choice -- a constant 'required' would make the done
+            // transition (which fires only on zero tool_calls) unreachable and exhaust
+            // the iteration budget, so first-call-only is the safe value semantics: it
+            // nudges a weak model into its first tool call without breaking loop
+            // termination. Undefined = model's own choice every call.
+            tool_choice,
+            // Opaque per-turn context handed to every tool handler (author/role/
+            // active-case/store etc.). The agent loop is identity-blind; tools that
+            // need who-is-asking read it from here. Null for a plain turn.
+            toolCtx,
         }),
         states: {
             idle: {
@@ -52,9 +67,13 @@ export function createAgentMachine({ provider, model, maxIterations = 90, callLL
                 invoke: {
                     src: fromPromise(async ({ input }) => {
                         const schemas = await getEnabledToolSchemas(input.enabledToolsets, input.disabledToolsets)
-                        return llm({ messages: input.messages, tools: schemas, model: input.model, provider: input.provider })
+                        // Resolve the per-iteration tool_choice policy (see context note).
+                        const tc = typeof input.tool_choice === 'function'
+                            ? input.tool_choice(input.iterations)
+                            : (input.iterations === 0 ? input.tool_choice : undefined)
+                        return await runStep(input.sessionKey, 'llm:' + input.iterations, () => llm({ messages: input.messages, tools: schemas, model: input.model, provider: input.provider, tool_choice: tc }))
                     }),
-                    input: ({ context }) => ({ messages: context.messages, model: context.model, provider: context.provider, enabledToolsets: context.enabledToolsets, disabledToolsets: context.disabledToolsets }),
+                    input: ({ context }) => ({ messages: context.messages, model: context.model, provider: context.provider, enabledToolsets: context.enabledToolsets, disabledToolsets: context.disabledToolsets, sessionKey: context.sessionKey, iterations: context.iterations, tool_choice: context.tool_choice }),
                     onDone: [
                         { guard: ({ event }) => Array.isArray(event.output?.tool_calls) && event.output.tool_calls.length > 0, target: 'tool_calls', actions: assign({ messages: ({ context, event }) => [...context.messages, { role: 'assistant', content: event.output.content || '', tool_calls: event.output.tool_calls }] }) },
                         { target: 'done', actions: assign({ messages: ({ context, event }) => [...context.messages, { role: 'assistant', content: event.output.content || '' }], lastResult: ({ context, event }) => {
@@ -92,16 +111,21 @@ export function createAgentMachine({ provider, model, maxIterations = 90, callLL
                             const tname = call.name || call.function?.name
                             const targs = call.arguments || call.function?.arguments || {}
                             const tcid = call.id || call.tool_call_id
-                            const pushExtras = r => { if (r?.systemMessage) extras.push({ role: 'system', content: '[hook] ' + r.systemMessage }); if (r?.additionalContext) extras.push({ role: 'system', content: r.additionalContext }) }
-                            const pre = await h.hooks.invoke('preToolCall', { name: tname, args: targs }); pushExtras(pre)
-                            if (pre?.behavior === 'block') { results.push({ tool_call_id: tcid, content: JSON.stringify({ error: 'tool call denied by plugsdk hook', tool: tname, reason: pre.reason || 'denied' }) }); continue }
-                            const res = await h.pi.dispatchTool(tname, (pre && pre.args) || targs)
-                            pushExtras(await h.hooks.invoke('postToolCall', { name: tname, args: targs, result: res }))
-                            results.push({ tool_call_id: tcid, content: res })
+                            const ret = await runStep(input.sessionKey, 'tool:' + input.iterations + ':' + tcid, async () => {
+                                const callExtras = []
+                                const pushExtras = r => { if (r?.systemMessage) callExtras.push({ role: 'system', content: '[hook] ' + r.systemMessage }); if (r?.additionalContext) callExtras.push({ role: 'system', content: r.additionalContext }) }
+                                const pre = await h.hooks.invoke('preToolCall', { name: tname, args: targs }); pushExtras(pre)
+                                if (pre?.behavior === 'block') { return { content: JSON.stringify({ error: 'tool call denied by plugsdk hook', tool: tname, reason: pre.reason || 'denied' }), extras: callExtras } }
+                                const res = await h.pi.dispatchTool(tname, (pre && pre.args) || targs, input.toolCtx || {})
+                                pushExtras(await h.hooks.invoke('postToolCall', { name: tname, args: targs, result: res }))
+                                return { content: res, extras: callExtras }
+                            })
+                            results.push({ tool_call_id: tcid, content: ret.content })
+                            extras.push(...ret.extras)
                         }
                         return { results, extras }
                     }),
-                    input: ({ context }) => ({ messages: context.messages }),
+                    input: ({ context }) => ({ messages: context.messages, sessionKey: context.sessionKey, iterations: context.iterations, toolCtx: context.toolCtx }),
                     onDone: { target: 'prompting', actions: assign({
                         messages: ({ context, event }) => [...context.messages, ...event.output.results.map(r => ({ role: 'tool', tool_call_id: r.tool_call_id, content: r.content })), ...event.output.extras],
                         iterations: ({ context }) => context.iterations + 1,
@@ -173,15 +197,39 @@ function mergeHookExtras(messages, r, tag) {
 }
 
 // Drive a started persistent agent actor to its final state, wiring timeout +
+// Auto-learn: distill a salient fact from a completed turn and memorize it into gm rs-learn.
+// Only fires on substantive, non-error outcomes; dedupes against existing near-identical
+// memories so the store does not fill with restatements. Best-effort — never throws.
+const AUTOLEARN_MIN_LEN = 40 // skip trivial one-liners
+const AUTOLEARN_DEDUPE_COS = 0.92 // a hit this similar means we already know it
+async function autoLearnTurn({ prompt, out }) {
+    try {
+        if (!out || out.error) return
+        const result = (out.result || '').toString().trim()
+        if (result.length < AUTOLEARN_MIN_LEN) return
+        const { memorize, recall, projectNamespace } = await import('../learn/gm-learn.js')
+        const namespace = await projectNamespace()
+        // Concise salient fact: the user's ask + the outcome, capped to keep recall sharp.
+        const fact = `Q: ${(prompt || '').toString().trim().slice(0, 200)}\nA: ${result.slice(0, 600)}`
+        const existing = await recall(fact, { limit: 1, namespace })
+        if (existing.length && existing[0].score >= AUTOLEARN_DEDUPE_COS) return
+        await memorize(fact, { namespace })
+    } catch (_) {}
+}
+
 // session-end hooks + trajectory. Shared by runTurn (fresh) and resumeTurn
 // (rehydrated from a persisted snapshot after a refresh/restart).
-async function driveAgentActor({ pa, h, events, prompt, provider, model, skill, cwd, witnessPath, timeoutMs }) {
+async function driveAgentActor({ pa, h, events, prompt, provider, model, skill, cwd, witnessPath, timeoutMs, sessionKey }) {
     const { actor } = pa
     return await new Promise((resolve, reject) => {
         let sub
         const cleanup = () => { try { sub?.unsubscribe() } catch {} ; pa.flush().catch(() => {}).finally(() => { try { actor.stop() } catch {} }) }
-        const t = setTimeout(() => { cleanup(); reject(new Error('agent turn timeout')) }, timeoutMs)
-        sub = actor.subscribe(snap => { if (snap.status !== 'done') return; clearTimeout(t)
+        let settled = false
+        const t = setTimeout(() => { if (settled) return; settled = true; cleanup(); reject(new Error('agent turn timeout')) }, timeoutMs)
+        // Do not let a pending turn-timeout timer keep the event loop alive or fire
+        // during process teardown after the awaiting caller has already moved on.
+        if (typeof t?.unref === 'function') t.unref()
+        sub = actor.subscribe(snap => { if (snap.status !== 'done') return; if (settled) return; settled = true; clearTimeout(t)
             ;(async () => {
                 const out = snap.output
                 const outbound = await h.hooks.invoke('onMessageOutbound', { content: out?.result || '' })
@@ -189,6 +237,11 @@ async function driveAgentActor({ pa, h, events, prompt, provider, model, skill,
                 await h.hooks.invoke('onSessionEnd', { reason: out?.error ? 'error' : 'ok', iterations: out?.iterations })
                 const errorStack = out?.error ? (events.find(e => e.type === 'llm_call' && !e.ok)?.stack || null) : null
                 await writeTrajectory(out, { prompt, provider, model, skill, cwd, events, errorStack, witnessPath })
+                // Auto-learn: memorize a salient summary of this turn into gm rs-learn so
+                // freddie learns from each substantive turn. Best-effort, deduped, capped.
+                await autoLearnTurn({ prompt, out })
+                // Completed turn leaves no step-journal residue.
+                await clearSteps(sessionKey)
                 // Unsubscribe, flush the final snapshot (persistent-actor clears it on
                 // the done state) + stop the actor — a finished actor should not be
                 // left running with live subscriptions/handles.
@@ -199,37 +252,46 @@ async function driveAgentActor({ pa, h, events, prompt, provider, model, skill,
     })
 }
 
-export async function runTurn({ prompt, messages = [], model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath, sessionKey } = {}) {
+export async function runTurn({ prompt, messages = [], model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath, sessionKey, toolCtx = null, tool_choice } = {}) {
     const events = []; const h = await bootHost()
     await h.hooks.invoke('onSessionStart', { prompt, model, provider, skill, cwd })
     let initMessages = [...messages]; const sysParts = []
     if (cwd) sysParts.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.`)
     if (skill) { const sd = h.pi.skills.get(skill); if (sd?.content) sysParts.push('Skill context:\n' + sd.content) }
+    // Auto-recall on turn entry: surface salient learned memories for this prompt from gm
+    // rs-learn (freddie's primary learning store). Best-effort; never blocks the turn.
+    try {
+        const { autoRecall, projectNamespace } = await import('../learn/gm-learn.js')
+        const hits = await autoRecall(prompt, { limit: 5, namespace: await projectNamespace() })
+        if (hits.length) sysParts.push('Relevant memories (gm rs-learn):\n' + hits.map(h => '- ' + h.text).join('\n'))
+    } catch (_) {}
     if (sysParts.length) initMessages.unshift({ role: 'user', content: sysParts.join('\n\n') })
     const inbound = await h.hooks.invoke('onMessageInbound', { content: prompt })
     if (inbound?.behavior === 'block') { await h.hooks.invoke('onSessionEnd', { reason: 'prompt_blocked' }); return { messages: initMessages, result: null, error: 'prompt blocked by plugsdk hook: ' + (inbound.reason || 'denied'), iterations: 0 } }
     initMessages = mergeHookExtras(initMessages, inbound, 'onMessageInbound')
-    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events })
     // Persist the turn snapshot under kind=agent so an interrupted turn (process
     // refresh mid-tool-call) resumes exactly where it stopped via resumeTurn.
     const key = sessionKey || randomUUID()
+    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events, sessionKey: key, toolCtx, tool_choice })
     const pa = await createPersistentActor(machine, { kind: 'agent', key, input: { messages: initMessages } })
     pa.actor.send({ type: 'SUBMIT', prompt })
-    return await driveAgentActor({ pa, h, events, prompt, provider, model, skill, cwd, witnessPath, timeoutMs })
+    return await driveAgentActor({ pa, h, events, prompt, provider, model, skill, cwd, witnessPath, timeoutMs, sessionKey: key })
 }
 
 // Rehydrate an interrupted turn from its persisted snapshot and drive it to
 // completion. Returns null if no live snapshot exists for the key (already
 // completed or never persisted) — caller falls back to a fresh runTurn.
-export async function resumeTurn({ sessionKey, model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath } = {}) {
+export async function resumeTurn({ sessionKey, model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations = 90, timeoutMs = 30000, cwd, skill, witnessPath, toolCtx = null } = {}) {
     if (!sessionKey) throw new Error('resumeTurn requires sessionKey')
-    const { load } = await import('../machines/snapshot-store.js')
-    if (!(await load('agent', sessionKey))) return null
     const events = []; const h = await bootHost()
-    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events })
+    const machine = createAgentMachine({ model, provider, callLLM, enabledToolsets, disabledToolsets, maxIterations, events, sessionKey, toolCtx })
+    // createPersistentActor.load() already handles a missing/stale snapshot and
+    // leaves pa.resumed=false, so the prior pre-check load() was a redundant
+    // second read that opened a TOCTOU window (a concurrent delete between the two
+    // reads made forget() delete a snapshot we had just confirmed). One read only.
     const pa = await createPersistentActor(machine, { kind: 'agent', key: sessionKey, input: { messages: [] } })
-    if (!pa.resumed) { await pa.forget(); return null }
-    return await driveAgentActor({ pa, h, events, prompt: '', provider, model, skill, cwd, witnessPath, timeoutMs })
+    if (!pa.resumed) return null
+    return await driveAgentActor({ pa, h, events, prompt: '', provider, model, skill, cwd, witnessPath, timeoutMs, sessionKey })
 }
 
 export async function invokeCompactHooks({ trigger = 'auto', messages = [] } = {}) {

package/src/agent/tool_call_text.js

@@ -0,0 +1,68 @@
+// Some fast/weak models emit tool calls as plain TEXT in their own native token
+// format instead of structured OpenAI `tool_calls` (especially when the system
+// prompt is rich). The agent loop only acts on structured tool_calls, so without
+// recovery it stalls after one turn. parseTextToolCalls() extracts both observed
+// formats from a content string and returns OpenAI-shaped {id,name,arguments}[].
+//
+// Formats handled:
+//   - kimi / moonshot section format:
+//       <|tool_calls_section_begin|>
+//         <|tool_call_begin|> functions.<name>:<idx>
+//         <|tool_call_argument_begin|> {json-args}
+//         <|tool_call_end|>
+//       <|tool_calls_section_end|>
+//   - llama python_tag format:
+//       <|python_tag|>name({...})  or  name("query")  or  name(key="value")
+//
+// Returns [] when the content holds no recognizable text tool call.
+
+function randId() {
+    return 'call_' + Math.random().toString(36).slice(2, 10)
+}
+
+function parseKimiSection(content) {
+    if (!content.includes('<|tool_call_begin|>')) return []
+    const re = /<\|tool_call_begin\|>\s*([\s\S]*?)\s*<\|tool_call_argument_begin\|>\s*([\s\S]*?)\s*<\|tool_call_end\|>/g
+    const out = []
+    let m
+    while ((m = re.exec(content)) !== null) {
+        const name = (m[1] || '').replace(/^functions\./, '').replace(/:\d+\s*$/, '').trim()
+        let args
+        try { args = JSON.parse((m[2] || '').trim()) } catch { args = {} }
+        if (name) out.push({ id: randId(), name, arguments: args })
+    }
+    return out
+}
+
+function parsePythonTag(content) {
+    if (!content.includes('<|python_tag|>')) return []
+    const after = content.slice(content.indexOf('<|python_tag|>') + '<|python_tag|>'.length).trim().split('\n')[0]
+    const mc = /^([A-Za-z_][A-Za-z0-9_.]*)\s*\(([\s\S]*?)\)\s*$/.exec(after)
+    if (!mc) return []
+    const name = mc[1].split('.')[0]
+    const inner = mc[2].trim()
+    let args = {}
+    if (/^\{[\s\S]*\}$/.test(inner)) { try { args = JSON.parse(inner) } catch { args = {} } }
+    else if (/^"[\s\S]*"$/.test(inner)) { const s = inner.slice(1, -1); args = { query: s, input: s } }
+    else if (/=/.test(inner)) {
+        const kwRe = /([A-Za-z_][A-Za-z0-9_]*)\s*=\s*("([^"\\]|\\.)*"|'([^'\\]|\\.)*'|[\d.]+|true|false|null)/g
+        let mm
+        while ((mm = kwRe.exec(inner)) !== null) {
+            let v = mm[2]
+            if (/^["']/.test(v)) v = v.slice(1, -1)
+            else if (/^[\d.]+$/.test(v)) v = Number(v)
+            else if (v === 'true') v = true
+            else if (v === 'false') v = false
+            else if (v === 'null') v = null
+            args[mm[1]] = v
+        }
+    } else if (inner) args = { query: inner, input: inner }
+    return name ? [{ id: randId(), name, arguments: args }] : []
+}
+
+export function parseTextToolCalls(content) {
+    if (typeof content !== 'string' || !content) return []
+    const kimi = parseKimiSection(content)
+    if (kimi.length) return kimi
+    return parsePythonTag(content)
+}

package/src/batch.js

@@ -5,7 +5,7 @@ import { getFreddieHome } from './home.js'
 import { randomUUID } from 'node:crypto'
 import { createMachine, assign, fromPromise } from 'xstate'
 import { createPersistentActor } from './machines/persistent-actor.js'
-import { load } from './machines/snapshot-store.js'
+import { runStep, clearSteps } from './machines/step-journal.js'
 
 // Run one prompt and append its result to the batch jsonl file.
 async function runOne({ job, model, callLLM, file }) {
@@ -43,7 +43,7 @@ export function createBatchMachine({ prompts, concurrency, model, callLLM, file
                             .map((p, i) => ({ i, p }))
                             .filter(({ i }) => !context.done.includes(i))
                             .slice(0, context.concurrency)
-                        return await Promise.all(pending.map(job => runOne({ job, model: context.model, callLLM, file: context.file })))
+                        return await Promise.all(pending.map(job => runStep(context.id, 'prompt:' + job.i, () => runOne({ job, model: context.model, callLLM, file: context.file }))))
                     }),
                     input: ({ context }) => ({ context }),
                     onDone: {
@@ -76,10 +76,12 @@ export async function runBatch({ prompts = [], concurrency = 4, model, callLLM,
 // yet in context.done get re-run. Returns null if no live snapshot for the id.
 export async function resumeBatch({ batchId, model, callLLM } = {}) {
     if (!batchId) throw new Error('resumeBatch requires batchId')
-    if (!(await load('batch', batchId))) return null
     const machine = createBatchMachine({ model, callLLM })
+    // One read only: createPersistentActor.load() handles the missing-snapshot
+    // case (pa.resumed=false), so the prior pre-check load() was a redundant read
+    // that opened a TOCTOU window against a concurrent delete.
     const pa = await createPersistentActor(machine, { kind: 'batch', key: batchId, input: { id: batchId, file: '', model, concurrency: 4, prompts: [] } })
-    if (!pa.resumed) { await pa.forget(); return null }
+    if (!pa.resumed) return null
     return await driveBatch(pa)
 }
 
@@ -89,7 +91,7 @@ function driveBatch(pa) {
         const sub = actor.subscribe(snap => {
             if (snap.status !== 'done') return
             const out = snap.output
-            pa.flush().catch(() => {}).finally(() => { try { sub.unsubscribe() } catch {}; try { actor.stop() } catch {}; resolve(out) })
+            pa.flush().catch(() => {}).then(() => clearSteps(out.id)).catch(() => {}).finally(() => { try { sub.unsubscribe() } catch {}; try { actor.stop() } catch {}; resolve(out) })
         })
         actor.subscribe({ error: (e) => { try { sub.unsubscribe() } catch {}; reject(e) } })
     })