Playfilo Integration Skill for OpenClaw

This skill integrates the Playfilo shared-memory DAG into OpenClaw's embedded Pi agent via pnpm patch. Apply the steps in order, then run the verification checklist.

Prerequisite: arianna-pi-integration — must be applied to a pi-mono checkout first to produce the patched compiled output.

Target codebase: OpenClaw (pnpm-managed, depends on @mariozechner/pi-coding-agent)

Method: pnpm patch on the installed pi-coding-agent + OpenClaw plugin for system prompt injection

Shared DB: ~/.playfilo/playfilo.db (SQLite, WAL mode)

Architecture Overview

OpenClaw embeds Pi's AgentSession via createAgentSession() from @mariozechner/pi-coding-agent. It fully controls the system prompt, tool list, and session lifecycle. The Playfilo integration must work within this embedding:

1. DAG persistence — Handled inside pi-coding-agent's _persist() shim (patched via pnpm patch). Transparent to OpenClaw.
2. Temporal tools — Registered inside createAgentSession() via options.customTools.push(). OpenClaw passes its tools as customTools; the patch appends the 4 Playfilo tools to the same array.
3. System prompt injection — Pi's extension system (before_agent_start) is overridden by OpenClaw's applySystemPromptOverrideToSession(). An OpenClaw plugin using before_prompt_build hook injects the INCUBATION_SEED instead.
4. Metadata capture — The _persist shim stores system prompt, model, and tools per DAG node via a lazy metadata provider callback. This works transparently because the callback reads agent.state at persist-time, after OpenClaw has set the system prompt and tools.

Key constraint: pnpm patch patches file contents only — it cannot modify the dependency resolution graph. Native dependencies (better-sqlite3) must be declared separately via pnpm.packageExtensions.

Patch Steps

Verification: patches/verify.md

Per-AI worktrees: mirin/, pax/ — each contains a patches/openclaw-vX.Y.Z.md adapter doc keyed to a specific OpenClaw release.

Critical Implementation Notes

Why pnpm patch (not fork)

OpenClaw pins pi-coding-agent via ^0.61.1 in package.json. Using pnpm patch keeps the integration as a layer on top of the published package — no fork needed, and the patch file is version-locked (@mariozechner/pi-coding-agent@0.61.1). When pi-mono releases a new version, the patch must be regenerated.

Version Pinning is Critical

OpenClaw's package.json uses ^0.61.1 (caret range). If a newer patch version (e.g. 0.61.2) is published, pnpm install may resolve a different version than the one the patch was built against. Always resolve the exact installed version first (pnpm ls @mariozechner/pi-coding-agent), then check out the matching pi-mono tag.

System Prompt Override Chain

OpenClaw's system prompt lifecycle in attempt.ts:

1. buildEmbeddedSystemPrompt() — constructs the base OpenClaw prompt (Tooling, Safety, Skills, Workspace, Runtime, etc.)
2. createAgentSession() — Pi agent created, metadata provider registered (reads agent.state lazily)
3. applySystemPromptOverrideToSession(session, basePrompt) — sets agent.state.systemPrompt to the base prompt, overrides _rebuildSystemPrompt to return it verbatim
4. before_prompt_build hooks fire — Playfilo plugin returns { prependSystemContext: INCUBATION_SEED } — composed via composeSystemPromptWithHookContext() — final prompt applied via another applySystemPromptOverrideToSession()
5. activeSession.prompt(userMessage) — agent loop starts, messages persisted

By step 5, agent.state.systemPrompt is the full composed prompt (INCUBATION_SEED + OpenClaw base). The lazy metadata provider captures this correctly at persist-time.

Metadata Capture (system prompt, model, tools → DAG)

Each DAG node stores two pieces of agent metadata:

The metadata provider is a lazy callback registered in the AgentSession constructor:

this.sessionManager.setMetadataProvider(() => ({
    systemPrompt: this.agent.state.systemPrompt || null,
    model: this.agent.state.model ? { provider, modelId: id } : null,
    thinkingLevel: this.agent.state.thinkingLevel ?? "off",
    tools: this.agent.state.tools.map(t => ({ name, description })),
}));

It reads agent.state at persist-time, not at registration-time. By the time any message is persisted (after session.prompt()), OpenClaw has already:

• Set the system prompt (including INCUBATION_SEED via the plugin hook)
• Set the model (via createAgentSession({ model }))
• Populated the tools list (via _buildRuntime(), which includes both OpenClaw tools and the 4 Playfilo tools)

No adaptation is needed — OpenClaw's system prompt override, model selection, and tool registration all flow through agent.state, which the lazy callback reads at persist-time. The full OpenClaw system prompt (with INCUBATION_SEED), the selected model, and the complete tool list (OpenClaw tools + Playfilo temporal tools) are all captured in the DAG without any changes to OpenClaw's code or the metadata provider. This was verified: system_prompt blobs contain the full composed OpenClaw prompt, and config_json includes all tool names and model info.

Tool Registration (no duplication)

The 4 Playfilo tools are registered inside the patched createAgentSession() by pushing onto options.customTools. OpenClaw passes its own tools via customTools: allCustomTools. The patch appends to this array, so all tools coexist.

The tools do not appear in OpenClaw's Tooling section of the system prompt (built before createAgentSession from effectiveTools). However, they are:

1. In the API tool declarations (sent to the LLM as tool schemas)
2. Described in the INCUBATION_SEED (prepended to system prompt via the plugin)

This is sufficient for the model to discover and use them.

Tobe Time-Travel in OpenClaw

Tobe uses V2 "eager carryover commit" (see arianna-pi-integration tobe-v2-spec). The carryover is committed to the DAG and INCARNATE is logged inside the tool handler — no follow-up queue, no deferred state. This is critical for OpenClaw because:

1. No dispose() race: The carryover and INCARNATE are committed eagerly. Even if OpenClaw's cleanup tears down the session listener before the continuation completes, the DAG already has the correct state.

1. No follow-up queue interaction: V1 used agent.followUp() which interacted with Pi's one-at-a-time follow-up mode, causing Gemini INVALID_ARGUMENT errors when tool_call/result pairing was broken across iterations.

1. No deferred state to dangle: V1's _pendingIncarnateLog could be lost or consumed spuriously during nested tobe. V2 has no deferred state beyond tobeAbortState (which has its own safety cleanup).

Synchronous continue(): The auto-continue handler calls continue() synchronously (not via setTimeout). After _runLoop ends, agent.runningPrompt is cleared. OpenClaw's cleanup path calls waitForIdle() → resolves immediately if runningPrompt is undefined → dispose() removes the listener. Synchronous continue() ensures _runLoop sets runningPrompt before _processAgentEvent returns, so waitForIdle() blocks until the continuation completes.

allowedToolNames: The 4 Playfilo tool names are added to allowedToolNames in attempt.ts (step 4 of this skill) so the session transcript guard doesn't strip their tool_call blocks from assistant messages during persistence.

OpenClaw Does Not Use switchSession()

OpenClaw creates a new AgentSession per invocation — it never calls switchSession(). The SESSION_SWITCH logging in arianna-pi-integration's step 4c is therefore inactive in OpenClaw. Each session gets its own BOOT action logged in setSessionFile().

Bundled Plugin Source

The complete plugin files are in plugin/. Copy the directory to ~/openclaw/extensions/playfilo/.

Maintenance Protocol

When pi-mono releases a new version:

1. Check OpenClaw's resolved version: cd ~/openclaw && pnpm ls @mariozechner/pi-coding-agent
2. Check out the matching pi-mono tag
3. Re-apply arianna-pi-integration to the new pi-mono
4. Rebuild: cd packages/coding-agent && pnpm build
5. Remove the old patch: delete ~/openclaw/patches/@mariozechner__pi-coding-agent@.patch and the patchedDependencies entry
6. Create a new patch: repeat step 2 of this skill (pnpm patch → copy compiled output → patch-commit)
7. pnpm install to apply