Use Pi from Inngest safely in joelclaw. Covers event-driven detached Pi CLI runners, direct pi-ai calls inside step.run, service-account OAuth auth, claim-check files, and when to choose each pattern.
76%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./skills/pi-inngest/SKILL.mdUse this when implementing, reviewing, or debugging joelclaw flows where Inngest orchestrates work and Pi provides model execution, tool execution, or harness-native agent behavior.
This skill is joelclaw-specific. It assumes Inngest and Pi are first-class local infrastructure, not incidental dependencies.
Load this skill when the task mentions:
pi-ai, @earendil-works/pi-ai, or legacy @mariozechner/pi-aipi from an Inngest functionstep.waitForEvent around agent workpi/workflow.* eventspi-aiAlso use it when an Inngest function needs LLM context work and the current path is drifting into ad hoc API keys, polling loops, or mystery subprocesses.
Inngest owns durability. Pi owns agent/model execution.
Do not blur that boundary:
pi-ai is allowed only for bounded model calls where Pi session/harness behavior is not needed.| Use this | When | Avoid when |
|---|---|---|
Direct pi-ai inside step.run | Short deterministic source-context calls, classification, extraction repair, summary/context generation, no Pi tools/session needed | Need Pi tools, skills, extension behavior, session artifacts, long-running agent work, or isolation from the worker process |
| Detached Pi CLI + event result | Need real Pi harness behavior, tool policy, session logs, read/write tools, long-running agent work, or process isolation | Tiny model-only calls where pi-ai would be simpler and faster |
Synchronous pi -p inside one step.run | Tiny smoke/probe only | Production long-running work; this loses the event-driven shape and can wedge a step |
Polling result files with step.sleep | Temporary proof shim only | Production orchestration; prefer step.waitForEvent plus a timeout watchdog |
Bench receipt from 2026-06-20:
pi-ai in step.run: 2/2 ok, ~5.5-6.5s wall, usage surfaced around 368 tokens / ~$0.0077 per call.pi-session/, pi-output.txt, and pi-result.json./Users/joel/.local/state/joelclaw-central/tmp/pi-runner-bench/e36f592d-786a-4c15-ba1d-affb5820bbdf.Takeaway: use direct pi-ai for bounded source-context summarization. Use detached Pi CLI when harness parity, tools, session artifacts, or isolation matter.
joelclaw Central services should use the macOS joelclaw service account for durable machine-owned auth where practical.
Current local facts:
com.joelclaw.central.inngest under user joelclaw.auth.json in Pi's agent dir.PI_CODING_AGENT_DIR; otherwise Pi uses ~/.pi/agent for the current OS user.openai-codex/gpt-5.6-sol.For durable service access:
/Users/joelclaw/.pi/agentpi-ai:PI_CODING_AGENT_DIR=/Users/joelclaw/.pi/agentKeep auth.json owned by joelclaw and mode 0600 or stricter. Never print it.
Verify auth without printing tokens:
sudo -u joelclaw \
PI_CODING_AGENT_DIR=/Users/joelclaw/.pi/agent \
node --input-type=module <<'NODE'
import { AuthStorage, ModelRegistry } from '@earendil-works/pi-coding-agent';
import { getModel } from '@earendil-works/pi-ai';
const provider = 'openai-codex';
const model = getModel(provider, 'gpt-5.6-sol');
const registry = ModelRegistry.create(AuthStorage.create());
const auth = await registry.getApiKeyAndHeaders(model);
console.log(JSON.stringify({
provider,
status: registry.getProviderAuthStatus(provider),
ok: auth.ok,
hasApiKey: Boolean(auth.apiKey),
hasHeaders: Boolean(auth.headers && Object.keys(auth.headers).length),
error: auth.error,
}, null, 2));
NODEExpected safe shape:
{
"provider": "openai-codex",
"status": { "configured": true, "source": "stored" },
"ok": true,
"hasApiKey": true
}Do not rely on Joel's personal ~/.pi/agent/auth.json from a Central service unless the service intentionally runs as Joel. Do not copy auth across accounts casually. If a one-time migration is unavoidable, record it as an explicit operator action, preserve 0600 permissions, and verify via the safe status check above.
Best options, in order:
joelclaw with PI_CODING_AGENT_DIR=/Users/joelclaw/.pi/agent. This is cleanest but requires an interactive browser/device-code flow.openai-codex OAuth credential from Joel's Pi auth store into the joelclaw Pi auth store. This grants the service account Joel's subscription-backed Codex access, so treat it as a privileged operator action./Users/joel permissions make this fucky and fragile.Repo helper:
cd /Users/joel/Code/joelhooks/joelclaw-central
scripts/setup-pi-service-auth.sh --dry-run
sudo scripts/setup-pi-service-auth.sh --apply
sudo scripts/setup-pi-service-auth.sh --testThe helper:
openai-codex OAuth credential;/Users/Shared/joelclaw/bin/pi because Joel's personal global Pi install lives under /Users/joel/.local/share, which the service account should not depend on;PI_CODING_AGENT_DIR=/Users/joelclaw/.pi/agent;AuthStorage/ModelRegistry and the Pi CLI as joelclaw without printing tokens.Utah's sidecar-management skill has the right shape: small dynamic Inngest functions live in a watched workspace, reconnect automatically, and notify the main agent by event. Steal the shape, not the names.
For joelclaw, the equivalent doctrine is:
This pairs naturally with Pi-Inngest: sidecar functions can choose direct pi-ai for small model steps or detached Pi CLI for harness-native work.
pi-ai in step.runUse this for bounded model calls where a Pi session is unnecessary.
Declare package dependencies in the package doing the work. Do not import from a global absolute install path in production code; scratch tests may do that only as a receipt-gathering hack.
import { Inngest } from 'inngest';
import { complete, getModel } from '@earendil-works/pi-ai';
import { AuthStorage, ModelRegistry } from '@earendil-works/pi-coding-agent';
const inngest = new Inngest({ id: 'joelclaw-example' });
async function runPiAiSummary(prompt: string) {
const model = getModel('openai-codex', 'gpt-5.6-sol');
const registry = ModelRegistry.create(AuthStorage.create());
const auth = await registry.getApiKeyAndHeaders(model);
if (!auth.ok || !auth.apiKey) {
throw new Error(auth.error || 'missing openai-codex auth');
}
const result = await complete(
model,
{
systemPrompt: 'Return concise, grounded JSON only.',
messages: [{ role: 'user', content: prompt, timestamp: Date.now() }],
tools: [],
},
{ apiKey: auth.apiKey, headers: auth.headers },
);
const text = result.content
.filter((part) => part.type === 'text')
.map((part) => part.text)
.join('');
return {
text,
usage: result.usage,
stopReason: result.stopReason,
};
}
export const summarize = inngest.createFunction(
{ id: 'summarize-with-pi-ai', retries: 2, triggers: [{ event: 'source/summary.requested' }] },
async ({ event, step }) => {
return await step.run('complete-pi-ai', async () =>
runPiAiSummary(event.data.prompt),
);
},
);step.run idempotent or make output writes idempotent.usage and stopReason in receipts when useful.auth.json; use AuthStorage / ModelRegistry and print only booleans/status.Use this for real Pi harness work.
The shape:
pi/workflow.requested.step.run writes pi-request.json and spawns a detached child/wrapper.pi -p @pi-prompt.md with a filtered environment.pi-result.json and artifacts under a claim-check directory.pi/workflow.result.ready with { workflowId, sourceId, resultPath }.step.waitForEvent to wait for that result.pi-result.json and emits one of:
pi/workflow.context.completedpi/workflow.needs_humanpi/workflow.failedUse explicit event names. For link ingest, prefer:
pi/workflow.requested
pi/workflow.result.ready
pi/workflow.context.completed
pi/workflow.needs_human
pi/workflow.failedThe wait event must match a stable unique ID, usually data.workflowId.
Do not match only sourceId when multiple workflows can run for the same source.
export const piWorkflowCli = inngest.createFunction(
{
id: 'pi-workflow-cli',
retries: 0,
triggers: [{ event: 'pi/workflow.requested' }],
},
async ({ event, step }) => {
const { workflowId, sourceId } = event.data;
await step.run('start-detached-pi-cli', async () => {
const requestPath = await writePiRequestClaimCheck(event.data);
spawnDetachedPiWrapper({ workflowId, sourceId, requestPath });
return { workflowId, sourceId, requestPath };
});
const resultEvent = await step.waitForEvent('wait-for-pi-workflow-result', {
event: 'pi/workflow.result.ready',
timeout: '4m',
match: 'data.workflowId',
});
if (!resultEvent) {
const failure = await step.run('write-timeout-failure', async () =>
writePiWorkflowFailureContext({ workflowId, sourceId, reason: 'timeout' }),
);
await step.sendEvent('emit-pi-workflow-failed', {
name: 'pi/workflow.failed',
data: failure,
});
return failure;
}
const result = await step.run('read-pi-result', async () =>
readJson(resultEvent.data.resultPath),
);
await step.sendEvent('emit-terminal-pi-event', routePiResultToEvent(result));
return result;
},
);spawn, not execFile, for long Pi sessions. execFile(pi) has hung under Node pipe capture on this machine.HOMEUSER / LOGNAMEPATHSHELLPI_CODING_AGENT_DIRINNGEST_EVENT_KEY, webhook secrets, Discord tokens, or broad service env into the pi subprocess.pi/workflow.result.ready; the Pi CLI child should not need it.For link-ingest style context work:
pi \
--model openai-codex/gpt-5.6-sol \
--thinking low \
--no-extensions \
--no-context-files \
--no-skills \
--no-prompt-templates \
--no-themes \
--session-dir "$WORKFLOW_DIR/pi-session" \
--name "Link Ingest Context" \
--tools read \
-p "@$WORKFLOW_DIR/pi-prompt.md"Tighten or expand tools intentionally. Default to read-only for source-context work.
Every Pi-Inngest path needs a terminal event.
pi-ai errors should fail the step or emit a typed failure event with a claim-check receipt.pi/workflow.failed.For Discord-facing flows, keep progress quiet:
Before calling a Pi-Inngest implementation done:
pi-ai smoke if that path is used.step.waitForEvent resumes from pi/workflow.result.ready.Useful local receipts from the link-ingest runner work live in:
/Users/joel/.brain/projects/joelclaw-link-ingest-2026-06-17.svx
/Users/joel/Code/joelhooks/joelclaw-central/.brain/projects/link-ingest-router-2026-06-17.svxUse this skill for reusable implementation doctrine.
Use Brain for live project memory and receipts.
Use repo scripts/tests for executable proofs.
Do not bury operational truth only in chat transcripts. Chat is compost, not storage. 🐀
joelhooks/joelclaw
f5b3a16
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.