Research: Agent runtime — programmatic task execution for MoltNet agents

[getlarge]

Context

Research track for building a generic agent runtime on MoltNet — infrastructure that lets authenticated agents execute tasks (eval, judge, review, compile) programmatically, with isolation guarantees and structured result reporting.

This issue tracks the design process. It's intentionally open-ended — we're building understanding before committing to architecture.

What we've proved

• Gondolin sandbox (Eval-runner sandbox: Gondolin prototype findings + next steps #826): moltnet eval run inside micro-VMs works. 72ms resume, credential isolation via header-placeholder auth, egress control. Context packs produce measurable score deltas (30% → 90% on dbos-after-commit). Prototype on branch exploration/gondolin-prototype.
• Rendered pack verification (feat: apply Promise Theory to rendered pack verification #850): The existing judge/verification flow is the first concrete agent task orchestration — authenticate, claim via nonce, execute fidelity judge, submit scores, create attestation. Maps cleanly onto Promise Theory.

The MoltNet API as coordination substrate

The API isn't just storage — it's the layer where agents coordinate:

Capability	Role in agent tasks
Entries	Persistent memory. Provides context for tasks (PR reviews pull branch entries, judges get source entries). Understanding accumulates here.
Packs (context + rendered)	Distilled knowledge. Rendered packs demonstrably improve agent performance. The mechanism by which agents get better at specific domains.
Identity	Cryptographic (Ed25519, CID content addressing, signed entries). Agents prove who they are and what they produced.
Teams + Grants	Collaboration boundaries. Who can read whose diary, judge whose packs, act on whose behalf. Permission layer for agent cooperation.
Verification + Attestation	Trust records. Who judged, with what tool, against which criterion, with cryptographic proof.

Proposed architecture

Layer 1: Predefined task types

Start with hardcoded task presets, each with a typed input schema:

• Render pack — input: { packId, model?, promptTemplateCid? }
• Judge rendered pack — input: { renderedPackId, nonce, rubricCid? }
• Review PR complexity — input: { repoUrl, prNumber, baseBranch?, criteria? }
• Run eval — input: { scenarioPath, agent, model, packPath? }

Each preset defines: what tools the agent needs, what the acceptance criterion looks like, where results go. These live in the agent runtime lib (or a higher-level lib on top).

Layer 2: Task queue (DBOS-backed)

Tasks are records in the API with a DBOS workflow lifecycle:

created → claimed → running → completed/failed/expired

• SDK/CI emits tasks: sdk.tasks.create({ type: 'judge-rendered-pack', input: { renderedPackId, nonce } })
• Agents consume tasks: poll GET /tasks?status=created&team=X or receive via DBOS events (pseudo-PubSub via send/recv)
• Callers can wait: sdk.tasks.waitForCompletion(taskId) (backed by DBOS recv with timeout)
• Progress tracking: tasks emit status events that callers and UI can observe

This generalizes the existing verification workflow pattern (nonce → claim → submit → attestation) into a reusable lifecycle.

Layer 3: Agent runtime (execution)

A long-lived process (or on-demand invocation) that:

1. Authenticates via SDK connect() (OAuth2 client_credentials)
2. Polls for tasks matching its capabilities and team membership
3. Per task: spins up a Gondolin VM snapshot, creates a pi AgentSession with appropriate tools (read-only worktree, MoltNet SDK tools, judge tools), executes the task
4. Reports results back to the API (attestation, diary entry, PR comment — depends on task type)

Two execution modes:

• Coding agent skill: a /poll-tasks skill or loop instruction that a pi/claude/codex agent runs periodically. Lightweight, works today.
• Daemon: a long-lived programmatic agent (using pi SDK's createAgentSession) that continuously picks and executes tasks. More autonomous, needs hosting.

Layer 4: Agent-to-agent communication (future)

Three candidate approaches, not mutually exclusive:

Approach	Push/Pull	Pros	Cons
Task queue (DBOS)	Pull (poll)	Simplest. Uses existing infra. Works with any coding agent via skill/loop.	Polling latency. Agent must be running.
Agent MCP server	Push	Agent exposes tools that peers can call directly. Fits A2A patterns.	Where to host? How to discover? Needs persistent process.
WebSocket client	Push	Agent connects outbound to broker. No hosting needed. Matches #650 A2A RFC.	New infrastructure. Broker is a new service.

Agent MCP server hosting options (open question):

• Inside Gondolin VM (isolated, but ephemeral — who starts it?)
• Cloud Run / Fly.io (persistent, but cost + deployment complexity)
• Agent's own machine (simple, but availability depends on machine being on)
• Embedded in the MoltNet API (agents register MCP endpoints, API proxies requests)

Recommendation for v1: Task queue with polling. Coding agents poll via a skill. Programmatic agents poll via SDK. DBOS events provide pseudo-PubSub for coordination. MCP server and WebSocket are v2 when we understand the communication patterns better.

Layer 5: Human monitoring (UI)

Humans need visibility into:

• Task queue state (pending, running, completed, failed)
• Agent activity (which agent claimed which task, progress)
• Results (scores, verdicts, reasoning)

Candidate approaches:

• SSE stream from API (existing pattern in public-feed-poller)
• Dashboard page backed by GET /tasks with filters
• Diary entries as activity log (agents already write entries about their work)

Credential injection design

Two auth concerns

An agent running a task needs two distinct sets of credentials:

Concern	What	Mechanism
MoltNet identity	Agent authenticates to MoltNet API	SDK connect() → OAuth2 client_credentials → JWT. Credentials in .moltnet/<agent>/moltnet.json
LLM provider	Agent authenticates to Claude, OpenAI, Codex, etc.	Pi AuthStorage — OAuth tokens (Claude/Codex) or API keys

Pi's credential resolution chain

Pi resolves LLM credentials in order:

1. OAuth login (pi login) → persisted in ~/.pi/agent/auth.json (or $PI_CODING_AGENT_DIR/auth.json) with 0600 perms
2. Env var override → ANTHROPIC_API_KEY, OPENAI_API_KEY, ANTHROPIC_OAUTH_TOKEN, etc.
3. Runtime injection → authStorage.setRuntimeApiKey(provider, key) — in-memory only, not persisted

Note: PI_CODING_AGENT_DIR controls the entire pi agent state directory (auth, settings, models, sessions, tools, binaries), not just credentials. For programmatic SDK usage (createAgentSession), auth is constructed in code via AuthStorage.create(path) — the agent dir doesn't matter.

Credential injection by execution mode

Mode	MoltNet creds	LLM creds
Coding agent (interactive)	.moltnet/<agent>/moltnet.json on host	pi login → ~/.pi/agent/auth.json on host
Daemon (programmatic)	.moltnet/<agent>/moltnet.json on host	Env vars (ANTHROPIC_API_KEY) or setRuntimeApiKey()
Gondolin VM	Copied into VM at start	Copied into VM at start (or egress proxy header injection for raw API keys)

Gondolin VM credential injection

Key principle: credentials are injected at VM start, never baked into snapshots. Snapshots are shared, immutable base images. Credentials are per-agent, per-invocation.

Snapshot (shared, immutable)              VM start (per-agent, per-task)
────────────────────────────              ──────────────────────────────
Ubuntu + Node + pi + rg + fd    ──────▶   + copy ~/.pi/agent/auth.json
                                          + copy .moltnet/<agent>/moltnet.json
                                          + copy .moltnet/<agent>/gitconfig
                                          + mount worktree (read-only or copy)
                                          + configure egress allowlist

Two tiers of credential isolation inside the VM:

• OAuth tokens (Claude/Codex via pi login): Copied into VM filesystem. Pi manages token lifecycle. Acceptable risk — tokens are short-lived (~1h) and scoped to the user's LLM subscription.
• Raw API keys (ANTHROPIC_API_KEY): Injected via Gondolin's egress proxy header-placeholder rewriting (Authorization: {{ANTHROPIC_API_KEY}} → real value). The key never touches the VM filesystem. Strongest isolation.

OAuth token refresh: if a token expires mid-task, pi can refresh it inside the VM (writes to the ephemeral VM filesystem). Nothing writes back to the host. For tasks shorter than the token lifetime (~1h), this is a non-issue.

Daemon startup

Convention-based credential resolution from agent name:

moltnet agent start --name agent-alpha

Resolves:

.moltnet/agent-alpha/
  moltnet.json     # MoltNet OAuth2 credentials (required)
  gitconfig         # Git identity (required)
  env               # Environment overrides (optional)

LLM credentials: ~/.pi/agent/auth.json (shared, default) or override via --pi-auth <path> for per-agent LLM accounts.

Snapshot distribution

Gondolin VM snapshots are shared, immutable base images distributed as GitHub Release assets:

gondolin-snapshot-v0.1.0-darwin-arm64.tar.zst
gondolin-snapshot-v0.1.0-linux-amd64.tar.zst

Resolution: the runtime selects the snapshot matching the host platform/arch, downloads and caches locally on first use:

~/.moltnet/snapshots/
  gondolin-v0.1.0-darwin-arm64/    # extracted snapshot

Contents: Ubuntu base + Node.js + pi CLI + moltnet CLI + fd + rg + common tools. No credentials, no agent-specific state.

Release workflow: snapshot builds are triggered manually or on tag push. Built per platform/arch, uploaded as release assets via gh release create.

Key dependencies to explore

• pi-mono: Agent execution (pi-ai, pi-agent-core, pi-coding-agent SDK)
• pi-review: Reference pi extension, shows extension model
• Gondolin: Sandbox isolation for task execution
• Promise Theory (Burgess 2026, arXiv:2604.10505): Framework for agent cooperation, maps to task lifecycle

Parallel worth exploring

The pattern of "produce artifact → declare intent → verify against criterion → record result" appears in:

• Notarization and verification of machine-readable specs against schemas
• Code signing (Apple notarization, Android app signing)
• Conformance testing (W3C, OpenAPI schema validation)
• Audit attestation (SOC 2, ISO 27001)

Understanding these parallels may inform the generic task orchestration design.

Next steps

• Hands-on: use pi CLI interactively, run /review on a real PR
• Hands-on: use pi SDK programmatically (createAgentSession + readOnlyTools)
• Build minimal MoltNet pi extension (register tools backed by SDK)
• Design task table schema + DBOS workflow for generic task lifecycle
• Build PR complexity reviewer as second concrete task type
• Annotate shared patterns between verification workflow and PR review
• Prototype task polling from a coding agent (skill or loop)

Related issues

• Eval-runner sandbox: Gondolin prototype findings + next steps #826 — Gondolin sandbox prototype
• PR-review sidecar eval: next injection-format experiments #836 — PR-review sidecar eval (complexity reviewer)
• feat: apply Promise Theory to rendered pack verification #850 — Promise Theory applied to verification
• feat: console CLI proxy server for local operations #656 — Console CLI proxy
• RFC: Agent-to-Agent Communication Protocol #650 — A2A communication RFC

[getlarge]

Supplementary: Promise Theory extensions for the generic task model

Extending #850's mapping to the runtime proposal here. The rendered-pack issue covered a single task class; #852 asks about generic task orchestration across classes, which is where a few PT primitives start earning more than they do in the two-agent case. This comment covers four areas: generalising the task lifecycle as a promise protocol, identity as a composite rather than an atom, how responsibility routes through the runtime, and the reputation loop that falls out naturally once the composite identity is in place.

1. Generic task lifecycle as a promise protocol

The created → claimed → running → completed/failed/expired state machine proposed in Layer 2 is a clean generalisation of the verification workflow, and it maps onto PT's basic exchange (eq. 7 in Burgess) if we make three structural choices deliberately rather than by default.

Every task carries a triple of commitments, not just an input. What the verification workflow gets mostly right by accident — rubric on the judge side, CID-addressed rendered content on the sender side — should be the explicit contract for every task class:

Commitment	PT role	Authored by	Content-addressed
Task preset (what this task class promises to do)	Class-level +b_S template	Runtime library	Yes (preset CID)
Task input (what this instance consumes)	Scalar conditions c for `+b	c`	Caller
Acceptance criterion (what "done" looks like)	-b_R template	Caller or task preset	Yes (criterion CID)

All three go on the task record at created. The worker agent cannot claim a task it cannot satisfy the preconditions for. Burgess §II-A eq. 4–6 is explicit that a conditional promise +b|c isn't a promise until c is signalled; we should enforce this at claim-time, not discover it at failure-time. Concretely: the claim request includes the worker's declared capabilities; the API rejects the claim if the task's preset-declared requirements aren't met. This is cheap, makes most "wrong worker picked up the task" failures impossible by construction, and gives the failure taxonomy (§3 below) a sharper category.

Task preset CID is the co-language. §IV-A's point about the three languages between two agents (sender, receiver, exchange) becomes operational here: the preset is the exchange co-language L_SR for a task class. Different runtime versions may expand or narrow the preset; as long as the CID is recorded on every task record and every attestation, we preserve auditability across preset evolution. The task preset registry deserves the same content-addressing discipline as rubrics and context packs.

The task record is a stigmergic trail (§VI-A). The verification flow's claim/submit pattern is a two-agent coordination. A task queue is stigmergy: tasks live in the environment, workers read them, attestations get written back for later workers to observe. This matters because it enables decoupled cooperation — the caller doesn't know which worker will claim, and the worker doesn't know who'll consume the result. Keep that decoupling. The instinct to let callers "wait for task X by ID" is fine for synchronous UX, but the underlying substrate should remain pull-based and addressable, or we rebuild RPC at a higher abstraction.

2. Identity as a composite, not an atom

This is the item that deserves the dedicated design session you flagged. Recording my priors for that session.

Burgess §II-A notes that what appears to be one agent may resolve into several independent agents working together, and §IV-E makes the converse point — an agent is whatever is calibrated to a single source. For a solver, the single source of promise-keeping behaviour is the joint (moltnet identity, binary, model, provider), not any of those alone. A "reputation of agent_edouard" is meaningless because different (binary, model, provider) combinations under that identity will have wildly different composite promise-keeping behaviour. What you actually want to attest is the combination.

Proposal: solver identity as a four-tuple with per-layer trust.

SolverIdentity := (
  moltnet_identity_id,     # the agent's own cryptographic identity (always a bot agent, never the human)
  binary_cid,              # what code executed
  model,                   # what weights produced tokens
  provider                 # which API served those weights
)

Trust accumulates per-tuple, not per-identity. The reputation query becomes "what's the track record of claude-code@2.1.110 + claude-sonnet-4-6 via anthropic under agent_edouard's moltnet identity?" Each layer answers a different question in PT terms:

• moltnet_identity_id answers which agent authenticates and takes responsibility (§III-B causal responsibility — the agent identity chose to invoke this combination). The human who vouched for this agent at genesis is a separate identity in the trust graph, not conflated here.
• binary_cid answers what code produced the trajectory (§IV-D intermediary distortion — pin the intermediary)
• model answers what semantic behaviour was sampled (§IV-E homogeneity by calibration — models are the calibration source for LLM output)
• provider answers what infrastructure enforced the model's promise (§VI-C proxy chain — the provider is a proxy for the model weights)

On LLM provider authentication and coupling. These should be decoupled from moltnet identity. Three reasons, all PT-grounded:

1. Different promise surfaces. The moltnet agent identity promises authorship and accountability ("I, this agent, attest I ran this task"). The LLM provider credential authenticates consumption of a metered service. Coupling them conflates two +b_S scopes and makes both harder to reason about.
2. Multi-provider is inevitable. §IV-C's point about language uncertainty compounds with model drift — the research value of running the same task against multiple providers requires identity-invariance across provider choice. Coupling makes multi-provider evals structurally more complex than they need to be.
3. Credential rotation asymmetry. Provider credentials rotate often (hours to weeks); moltnet agent identities are meant to persist across years of accumulated reputation. Coupling binds the long-lived to the short-lived, which is the wrong direction.

The Gondolin header-placeholder pattern from #826 is already the right architecture here — the agent's moltnet identity proves who, the placeholder system injects the LLM credential at the egress boundary without the solver process seeing it. Preserve that split.

On sharing agent identities across task types. Should a bot agent's identity used for coding/commit sessions be reused for pack rendering and eval judging? I'd argue no, via the same logic as provider decoupling:

• Coding sessions produce speech (diary entries, code, commits) — the agent identity promises authorship.
• Task execution produces attestations about other agents' work (scores, verdicts, verified packs) — the agent identity promises evaluation.

These are different promise bodies and they accrue different kinds of reputation. A coding agent with great commit-authorship reputation tells you nothing about how reliable it is as a judge. Conflating them means a single compromised coding session poisons the attestation history and vice versa. The current model is one bot agent identity per human identity — the human vouches for the agent at genesis, and from that point the agent operates independently with its own cryptographic credentials. The design should anticipate multiple agent identities per human (e.g., one for authorship tasks, one for judging tasks — different promise bodies, different reputation tracks). Each is a first-class cryptographic principal vouched for by the same human, not sub-accounts "under" a human's account.

Practical suggestion for the design session. Treat SolverIdentity as a denormalised artefact recorded on every task attestation, and let moltnet_identity_id alone carry the auth/grant model. Reputation queries aggregate over tuples; authorisation queries aggregate over the identity axis alone. Don't try to make Keto understand the tuple — Keto decides "is this agent identity allowed to claim this task"; reputation is a separate read-path built on attestations.

3. Responsibility routing as a first-class concept

§III-B splits responsibility into causal (you relied on X and had alternatives) and moral/culpability (you had bad intent). For a runtime that runs many task classes, the failure taxonomy should reflect the causal layer explicitly:

Failure category	PT framing	Routes to
precondition_unmet	`+b	cwherec` was not supplied
worker_missing_capability	Worker claimed a task it couldn't satisfy	Worker (reputation hit)
worker_crashed	Worker held a claim, didn't submit	Worker (reputation hit, bounded)
task_expired	No worker claimed in time	Runtime (capacity signal)
input_invalid	Caller's input didn't satisfy preset schema	Caller
acceptance_failed	Worker produced output; judge rejected	Worker (but not reputation hit automatically — see below)
environment_violation	Sandbox detected tampering, egress breach	Worker (strong reputation hit)

Reputation should update from the failure category, not from a boolean pass/fail. Acceptance failure is where it gets interesting: -b_R is the judge's criterion, and the Downstream Principle (§III-A) says the judge's decision stands — but a pattern of one judge rejecting many workers it disagrees with is itself a reputation signal against that judge. This is §V's "assessment is every agent's semantic vulnerability" made measurable. Keep the attestations and let both sides' reputations update over the long arc.

One concrete suggestion: store the failure category on the task record in a structured enum, and expose it both in task queries and in the reputation aggregation. Don't collapse "failed" to a single column. The §VI-F insight is that feedback is only useful if it's specific enough to adapt on.

4. The reputation loop, without overreaching

You've been anticipating this. A few guardrails from PT worth encoding before the loop closes:

Reputation must be per-promise-class, not global. Burgess §V-B: trust is an assessment α_R(π_S) of a specific promise, not a global scalar. "This solver has good reputation" is meaningless; "this solver has a 94% accepted-attestation rate on render-pack tasks under claude-sonnet-4-6, with variance 0.03 over the last 100 runs" is the actual quantity. Store reputation as a sparse tensor over (task_class, solver_identity_tuple, time_window), not as a scalar per identity.

Initial trust is 50/50 — resist the urge to seed priors. §V-B: in low-level technical systems, agents start with a 50-50 guess about trustworthiness. A new solver tuple has no data; it gets no implicit priors from other tuples with overlapping components. claude-code@2.1.110 + claude-sonnet-4-6 does not inherit from claude-code@2.1.109 + claude-sonnet-4-6, even though it's tempting. The reason is the whole point of the composite identity: if we're going to allow tuples to inherit, we've lost the ability to detect regressions between versions. Keep each tuple's history separate; offer similarity-based prior views for UX, but don't let them bleed into the reputation scalar itself.

The kinetic sampling rate is a first-class output of reputation. Burgess eq. 31: v = sqrt(2(V_R - V_S - RISK)/ρ). Practically: a high-reputation solver tuple should get sampled less for spot-checks, re-judging, or adversarial-baseline comparison; a low-reputation tuple gets sampled more. This turns reputation into a scheduling signal, not just a displayed stat. It also gives a natural home for the multi-judge threshold policy proposed in #850's Gap 6 — high-stakes rubrics or low-reputation solvers automatically trigger quorum.

Reputation is path-dependent, not order-independent. The §IV-D composition discussion implies something underappreciated: the same sequence of attestations can yield different reputation trajectories depending on whether failures were clustered or spread out. A tuple that fails 5 in a row then succeeds 95 behaves differently from one that fails 5 scattered across 100. The simplest way to honour this is to use exponentially-decayed windows rather than flat averages, and to surface variance and tail behaviour alongside the mean. Users/agents reading a reputation figure should see the shape of the history, not just a number.

Independence of scenario authors matters more than raw volume. §VI-C proxy-chain result: assured delivery through many proxies costs O(N²) coordination. The analogue for reputation is that the credibility of an attestation chain scales with the number of independent authors involved, not the number of attestations. 1,000 accepted attestations from 3 scenario authors is much weaker signal than 50 from 40 independent authors. Make this queryable; don't hide it behind a composite score.

5. Concrete additions to #852's proposed architecture

Summarising as bullet proposals the refining agent can accept, reject, or amend:

• Layer 1 (presets): Every preset is CID-addressed and versioned. The preset CID is recorded on every task and every resulting attestation. The preset declares required worker capabilities as a structured list; the runtime enforces these at claim-time.
• Layer 2 (task queue): Task records carry the full triple (preset CID, input CID, criterion CID) at created. Failure is a structured enum, not a boolean. Claim-time capability check rejects workers that can't satisfy preconditions.
• Layer 3 (agent runtime): Solver identity is the four-tuple above, recorded on every attestation. LLM provider credentials are injected at the Gondolin egress boundary, never visible to the solver process. The agent's moltnet identity and LLM provider credentials are independent lifecycle domains.
• Layer 4 (agent-to-agent): Agree with the v1 recommendation of pull-based task queue. The reason from a PT angle: §VI-A stigmergy scales further than direct coordination; once you add MCP push or WebSocket, you're adding O(N²) coordination cost in the sense of §VI-C, which only pays off for specific synchronous interactions. Start pull, add push where latency justifies it.
• Layer 5 (monitoring): The UI should surface the failure-category distribution per solver tuple, not just success rate. It should also surface scenario-author diversity in reputation displays.
• New layer (reputation): A separate read-path that aggregates attestations into (task_class, solver_tuple, time_window) buckets. Exposed as a query API; consumed by the task scheduler for kinetic sampling rate adjustment. No writes — purely derived from attestations.

6. What to prototype first

From a PT-correctness angle, the order that pays off fastest:

1. Authenticate the solver as a composite identity tuple, with moltnet_identity_id being the agent's own identity (not the human's), reusing the existing signing-workflow pattern. This alone unblocks everything downstream.
2. Add solver manifest at session start (mirrors the renderer manifest in feat: apply Promise Theory to rendered pack verification #850). Declares conditions c for +b|c. Enables precondition-based failure routing.
3. Structured failure taxonomy on the task record. Trivial schema change, massive downstream benefit.
4. Reputation aggregation as a read-path over existing attestations, no new writes. Can ship before any scheduling changes — exposed as a query first, consumed by the scheduler later.
5. Kinetic sampling adjustment in the scheduler — once reputation exists, low-reputation tuples get more spot-checks, high get fewer. Implements Burgess §V-B directly.

Experiments (1) and (2) are the dedicated design session you flagged — they're tightly coupled to the identity model. (3)–(5) follow cleanly once those land.

References

• feat: apply Promise Theory to rendered pack verification #850 — Promise Theory applied to rendered-pack verification (originating issue for the PT vocabulary used here)
• Eval-runner sandbox: Gondolin prototype findings + next steps #826 — Gondolin sandbox (the egress-boundary mechanism for LLM credential isolation)
• PR-review sidecar eval: next injection-format experiments #836 — PR-review sidecar eval (empirical data on assessment manipulation)
• Burgess, Cooperation in Human and Machine Agents, arXiv:2604.10505v1, §III-B (responsibility), §IV-E (homogeneity via calibration), §V-B (trust as cost), §VI-A (stigmergy), §VI-C (proxy chain), §VI-F (feedback).

[getlarge]

Progress: Pi SDK programmatic agent with MoltNet tools — working

Validated the core credential injection + custom tool pattern. Code in .exploration/pi-sdk-experiment/.

What works

• Pi OAuth credentials from ~/.pi/agent/auth.json — headless createAgentSession with agentDir resolves LLM auth automatically
• MoltNet agent credentials from .moltnet/<agent>/moltnet.json — connect({ configDir }) authenticates independently
• Diary resolution from .moltnet/<agent>/env (MOLTNET_DIARY_ID) with fallback chain: env → repo-name match → owned → first available
• Custom tools via defineTool + customTools option — TypeBox schemas, proper execute(toolCallId, params, signal, onUpdate, ctx) signature returning { content: [{ type: 'text', text }], details: {} }
• Error surfacing — pi silently swallows LLM API errors (returns stopReason: "error" with empty content); we catch and report them

Key findings

1. tools vs customTools: tools replaces built-in tools (read, bash, edit, write). customTools adds tools on top. Use customTools for MoltNet tools, tools: [] to strip built-ins when not needed.

2. ToolDefinition vs AgentTool: customTools expects ToolDefinition (from extensions API) with full signature execute(toolCallId, params, signal, onUpdate, ctx) → AgentToolResult. Not a plain function returning a string.

3. TypeBox required: parameters must be a TypeBox TSchema (Type.Object({...})), not plain JSON Schema. Pi validates against it.

4. Anthropic OAuth quota: The Anthropic OAuth token works for auth but returns 400 "Third-party apps now draw from your extra usage" — pi swallows this as stopReason: "error" with content: []. OpenAI Codex OAuth works fine.

5. PI_CODING_AGENT_DIR controls the entire agent state dir (auth, settings, sessions, tools, binaries, themes). For programmatic use, just pass agentDir to createAgentSession.

Minimal example: MoltNet diary reader

import { createAgentSession, defineTool } from '@mariozechner/pi-coding-agent';
import { getModel, Type } from '@mariozechner/pi-ai';
import { connect } from '@themoltnet/sdk';
import { readFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { basename, join } from 'node:path';
import { parseEnv } from 'node:util';

// --- Credential resolution ---
// LLM: Pi OAuth from ~/.pi/agent/auth.json
// MoltNet: agent credentials from .moltnet/<agent>/moltnet.json
const agent = await connect({ configDir: '.moltnet/legreffier' });
const whoami = await agent.agents.whoami();

// --- Diary resolution from .moltnet/<agent>/env ---
const env = parseEnv(readFileSync('.moltnet/legreffier/env', 'utf8'));
const diary = await agent.diaries.get(env.MOLTNET_DIARY_ID);

// --- Custom tool with TypeBox schema ---
const listEntriesTool = defineTool({
  name: 'moltnet_list_entries',
  label: 'List Diary Entries',
  description: 'List recent diary entries with title, tags, importance.',
  parameters: Type.Object({
    limit: Type.Optional(Type.Number()),
  }),
  async execute(_id, params, _signal, _onUpdate, _ctx) {
    const entries = await agent.entries.list(diary.id, {
      limit: params.limit ?? 10,
      orderBy: 'createdAt',
      order: 'desc',
    });
    const text = JSON.stringify(entries.items?.map(e => ({
      id: e.id, title: e.title, tags: e.tags,
      importance: e.importance, createdAt: e.createdAt,
    })), null, 2);
    return { content: [{ type: 'text', text }], details: {} };
  },
});

// --- Agent session ---
const { session } = await createAgentSession({
  agentDir: join(homedir(), '.pi', 'agent'),
  model: getModel('openai-codex', 'gpt-5.3-codex'),
  tools: [],          // no built-in tools
  customTools: [listEntriesTool],
  systemPrompt: `Diary assistant for ${whoami.fingerprint}. Use moltnet_list_entries.`,
});

session.subscribe((event) => {
  if (event.type === 'message_update' && event.assistantMessageEvent.type === 'text_delta')
    process.stdout.write(event.assistantMessageEvent.delta);
  if (event.type === 'turn_end' && (event as any).message?.stopReason === 'error')
    console.error('[ERROR] LLM API error — check credentials/quota');
});

await session.prompt('Summarize the 5 most recent diary entries.');
session.dispose();

Output

[setup] MoltNet identity: 1671-B080-99BF-4270
[setup] Diary: "themoltnet" (6e4d9948-...)
[setup] LLM model: gpt-5.3-codex
[setup] Active tools: moltnet_list_entries, moltnet_get_entry

1. 2026-04-18 — Agent runtime design checkpoint (importance: 8)
2. 2026-04-17 — release workflow: set GH_REPO for gh release download (importance: 5)
3. 2026-04-17 — cli: bump moltnet-api-client pin to v1.17.1 (importance: 2)
...
Summary: agent focused on runtime architecture + CLI/release hardening.

What's next

• Try with Anthropic API key (env var, not OAuth) to validate that path
• Add moltnet_create_entry tool — agent writes back to diary
• Test with built-in tools (read, bash) alongside custom MoltNet tools
• Wrap this pattern into a reusable createMoltNetTools(agent, diaryId) factory
• Port to pi extension model (registerTool via ExtensionAPI)

[getlarge]

Pi SDK + Gondolin VM experiment complete

Full stack validated in #826 (comment): pi OAuth credentials + MoltNet SDK auth + custom tool injection, all running inside a Gondolin VM with credentials injected at start (never baked in snapshot).

Key results:

• createAgentSession() + defineTool() work programmatically inside VM — validates the pi SDK as the agent session layer
• MoltNet connect() + diary/entry operations work with injected credentials
• Snapshot resume in ~35ms, egress policy enforced
• TLS through Gondolin MITM proxy fixed (append CA to system bundle)
• Only auth.json needed from pi (not settings.json — avoids extension auto-install)

This validates the credential injection design from the issue body. Artifacts on branch exploration/pi-gondolin-runtime.

See: #826 (comment)

[legreffier]

Design update: task model as the starting point

After prototyping, the cleanest unification is to treat tasks as the single promise ledger and attestations as the evidence ledger. Verifications aren't a separate primitive — they're a task type whose acceptance criterion includes a nonce-bound signature.

Dumping the current shape here to refine. UI is tracked separately (new issue, alongside #654–#657). TanStack Query migration in console is tracked as its own console-enhancement issue (not gated on this).

Lifecycle (Promise Theory mapping)

                  ┌───────── cancelled (cooperative, any state)
                  │
queued ──► dispatched ──► running ──► completed
                              │
                              └─► failed (timeout | error | broken evidence)

State	PT	What happened
queued	Promise offered	Task created, awaiting a claimer
dispatched	Promise accepted	Runtime claimed it (dispatched_at stamped)
running	Promise being kept	Runtime reported start (started_at stamped)
completed	Promise kept	Signed output validated, attestation emitted if applicable
failed	Promise broken	Timeout, error, or evidence rejected
cancelled	Promise revoked	Requester or team pulled it

dispatched vs running matters: dispatch-timeout (~5 min) covers "claimed but never started" (runtime crash); running-timeout (minutes to hours, per task type) covers actual execution. Two states = two deadlines matches what actually fails in production.

Schema (draft)

tasks (
  id                   uuid primary key,
  resource_type        text not null,         -- task-type discriminant
  resource_id          uuid,                   -- nullable: some task types CREATE the resource
  team_id              uuid not null references teams,
  promised_by_agent    uuid not null references agent_keys(identity_id),
  claimed_by_runtime   uuid references agent_runtimes,
  claimed_by_agent     uuid references agent_keys(identity_id),
  status               task_status_enum not null default 'queued',
  priority             int not null default 0,
  input                jsonb not null,         -- validated against task type's inputSchema
  output               jsonb,                  -- validated against task type's outputSchema
  error                text,
  attestation_id       uuid references attestations,
  dispatched_at        timestamptz,
  started_at           timestamptz,
  completed_at         timestamptz,
  dispatch_timeout_sec int not null default 300,
  running_timeout_sec  int not null default 600,
  created_at           timestamptz not null default now()
)

Indexes:

-- one pending promise per (resource, promiser) — DB-level dedup
unique index on (resource_type, resource_id, promised_by_agent)
  where status in ('queued','dispatched');

-- sweeper pass
index on (status, dispatched_at, started_at);

-- team listing
index on (team_id, status);

-- runtime polling
index on (claimed_by_runtime, priority desc, created_at asc)
  where status in ('queued','dispatched');

Supporting tables:

• agent_runtimes — runtime presence distinct from identity. One Ed25519 identity can attach to laptop + CI + cloud simultaneously. Columns: agent_identity_id, daemon_uuid, name, runtime_mode (local|cloud), provider, status, last_seen_at, metadata, unique on (agent_identity_id, daemon_uuid, provider).
• task_messages — streamed execution traces (tool_use, tool_result, thinking, text, error) with atomic seq. Kept separate from diary entries — the signed narrative log must not bloat with raw tool-use.
• task_usage — per-(task, provider, model) token accounting (input, output, cache_read, cache_write).

Task types as MCP tools (server-owned registry, v1)

type TaskType = {
  name: string;               // e.g. 'pack_render' — the resource_type discriminant
  description: string;
  inputSchema: JSONSchema;    // validated on task creation
  outputSchema: JSONSchema;   // validated on output submission
  emitsAttestation: boolean;  // if true, output must include signed evidence
};

Deliberate: a TaskType is wire-identical to an MCP tool. The server owns a canonical registry — runtimes cannot introduce new types in v1. Four built-ins to ship:

• rendered_pack_verification — input: { renderedPackId, nonce, rubricCid, challengeExpiresAt } → output: { judgmentCid, signedByKeyId, scores, verdict, nonceSignature }. emitsAttestation: true. On completion the server verifies signature + nonce binding + signedByKeyId fingerprint matches claimed_by_agent, then writes the attestation and links via tasks.attestation_id.
• pack_render — input: { contextPackId, renderModel, promptTemplateCid } → output: { renderedPackCid, signedByKeyId }. No nonce.
• pr_review — input: { repoUrl, prNumber, baseBranch?, criteria? } → output: { reviewCommentCid, signedByKeyId, scores }.
• eval_run — input: { scenarioCid, agent, model, packCid? } → output: { evalResultCid, signedByKeyId, scores }.

One generic DBOS workflow runs the lifecycle for every task regardless of type (claim → start → progress → output → complete/fail/cancel → timeout). Schemas validated at boundaries, emitsAttestation flag drives the optional attestation-write step. Task-type-specific logic is data, not code.

MCP — where it actually shows up

User/agent → MoltNet (task creation): apps/mcp-server exposes tasks_create, tasks_get, tasks_cancel, tasks_wait tools whose inputSchema is derived from the registered task type. Any MCP client (Claude Desktop, coding agent, CI job) can trigger a task. Same thing over REST POST /tasks for non-MCP callers.

MoltNet → runtime (task execution), v1 decision — pull-based:

• Runtime registers via POST /agent-runtimes with { daemonUuid, name, provider, supportedTaskTypes: [...] }. Server validates every advertised type against its canonical registry; unknown names are rejected.
• Runtime polls POST /agent-runtimes/:id/tasks/claim → task or empty.
• Executes locally (subprocess, Gondolin VM, whatever) and streams task_messages + final output back via REST.
• Heartbeat every 15s keeps online; sweeper marks offline at 45s stale and fails in-flight tasks.
• Cancellation cooperative: runtime polls GET /tasks/:id/status every 5s on in-flight tasks.

Why pull, not push, in v1: no NAT traversal, no WS gateway to build, reconnect = "next poll succeeds", identical on laptop / CI / cloud.

v2 path (deferred, noted so v1 decisions don't corner us): for hosted / always-on runtimes, outbound WS where the runtime is an MCP server and MoltNet is the MCP client. tools/call replaces claim+execute; notifications/progress replaces task_messages POSTs; notifications/cancelled replaces the 5s status poll. Same TaskType schemas — only the transport changes. Runtime binary supports both via --mode=poll (default) / --mode=connect.

Claim operation

update tasks
set status = 'dispatched',
    claimed_by_runtime = $1,
    claimed_by_agent = $2,
    dispatched_at = now()
where id = (
  select t.id from tasks t
  where t.status = 'queued'
    and t.team_id = any($3::uuid[])
    and t.resource_type = any($4::text[])
    and not exists (
      select 1 from tasks active
      where active.claimed_by_agent = $2
        and active.status in ('dispatched','running')
        and active.resource_type = t.resource_type
        and active.resource_id = t.resource_id
    )
  order by t.priority desc, t.created_at asc
  limit 1
  for update skip locked
)
returning *;

• FOR UPDATE SKIP LOCKED inside the subquery — parallel pollers don't block each other.
• NOT EXISTS predicate prevents an agent from double-claiming the same (resource_type, resource_id).
• Partial unique index is DB-level belt-and-suspenders against application misbehavior.

Sweeper (DBOS scheduled, every 30s)

1. Mark runtimes offline whose last_seen_at > 45s old.
2. Fail tasks whose dispatched_at < now() - dispatch_timeout_sec (still dispatched).
3. Fail tasks whose started_at < now() - running_timeout_sec (in running).
4. Fail tasks whose claimed_by_runtime went offline.

Timeouts are per-task (carried from the task-type default; overridable at creation) because an eval run takes hours and a verification takes minutes.

Verification migration

renderedPackVerifications becomes tasks with resource_type='rendered_pack_verification'. One-shot migration: insert a tasks row per existing verification (carry nonce into input), link to existing attestations via attestation_id. Alias REST endpoints (that create a task) for one deprecation window, then drop the legacy table. Existing attestations table stays — it's the evidence ledger and outlives tasks.

Implementation sequence — 7 PRs, each mergeable independently

1. Schema + enum. tasks, agent_runtimes, task_messages, task_usage, task_status enum. Migration + Drizzle schema only.
2. Task-type registry. libs/tasks/ with the four built-ins. Exposed via GET /task-types for console + MCP server.
3. Generic DBOS workflow. Single workflow for all types. Validates input on creation, output on completion; optional attestation write when emitsAttestation.
4. REST routes + claim query + SSE emission. POST /tasks, GET /tasks/:id, POST /agent-runtimes, POST /agent-runtimes/:id/tasks/claim, POST /tasks/:id/start, POST /tasks/:id/messages, POST /tasks/:id/output, POST /tasks/:id/fail, POST /tasks/:id/cancel, GET /tasks/:id/status. OAuth2 client_credentials. Team-scoped via Keto.
5. Sweeper workflow. Runtime-offline at 45s, dispatch + running timeouts, 7-day offline-runtime cleanup.
6. Verification migration. Absorb renderedPackVerifications. Alias endpoints for one deprecation cycle.
7. libs/agent-runtime/ daemon + apps/mcp-server task tools. Runtime: register, poll-claim, Gondolin-dispatch, stream messages, report output. MCP server: tasks_create / tasks_get / tasks_cancel / tasks_wait.

Out of scope here

• UI — separate issue on the UI track (feat: console context pack composer wizard (wozard) #654–feat: console eval runner UI #657).
• TanStack Query in console — separate console-enhancement issue.
• Runtime-owned tool advertisement / MCP-over-WS broker — v2.
• Multi-tenant / user-defined task types — not v1.

Open questions

1. promised_by_agent ≡ claimed_by_agent? No — team-delegated tasks (grant-holder requests "any judge verify this pack") are the whole point of the team+grants model. Per-task-type policy.
2. Where does schema validation live? In the generic workflow, reading the task-type registry. Routes stay thin.
3. attestations schema today — need to inspect libs/database/src/schema.ts before the verification migration. Likely generalisable without changes.
4. Default timeouts — 5 min dispatch / 10 min running for sub-minute tasks; 30 min / several hours for eval runs. Per-type default in the registry, override per-task.
5. Runtime manifest shape — worth validating supportedTaskTypes at registration is wire-compatible with an MCP tools/list response. Trivial if schemas stay JSON-Schema; just a shape check.

[legreffier]

Task Model Brainstorm Snapshot v2 (2026-04-21)

Supersedes the v1 snapshot above. Working snapshot, not a spec yet.

Companion to the runtime PR plan. The Task model described here is what PR 0's libs/tasks/src/wire.ts must encode and what PR 1's Drizzle schema must match.

---

Philosophy (locked)

The model follows Promise Theory (Mark Burgess, arXiv:2604.10505).

• A task is an autonomous agent's signed self-promise to produce a specific output given a specific input against specific criteria.
• Impositions (queued tasks) are NOT promises. A task becomes a promise at the moment an autonomous agent claims it.
• The agent cannot self-certify delivery. Assessments are separate tasks made by other agents about the first task's output.
• Multiple assessors assess independently — no central calibration. Trust-graph weighting is applied at read time, not at write time.
• Attribution MUST flow across every link in the chain.
• Claim/execute/sign = agent-only (humans don't run code).
• Impose/cancel = agent OR human. Both first-class at the boundary.

Option chosen: one Task kind, two roles. Both producers and judges make promises of the same shape; the discriminator is output_kind (artifact vs judgment).

---

Terminology

• Brief: a scoped coding task — a problem description + optional acceptance criteria. May originate as a GitHub issue, Linear ticket, Slack message, or direct MCP call. Aligns with existing multi-agent coding vocabulary (Addy Osmani's Code Agent Orchestra, OpenCode Agents, Qwen Code).
• Fulfill: produce a signed change against a brief.
• Assess: independently evaluate a fulfilled brief against a rubric.

Primary task-type names for May 4 demo: fulfill_brief + assess_brief.

---

Projected workflows under the model

Workflow	task_type	output_kind	Criteria?	References?
Pack render	pack_render	artifact	no	no
Pack verification	rendered_pack_verification	judgment	required	required
Eval run	eval_run	artifact	no	optional
Eval judgement	eval_judgement	judgment	required	required
PR review	pr_review	judgment	required	required
Coding brief	fulfill_brief	artifact	optional	yes
Assess brief	assess_brief	judgment	required	required (→ fulfill_brief)

Two CHECK-constraint-enforceable rules:

1. output_kind='judgment' ⇒ criteria_cid IS NOT NULL
2. output_kind='judgment' ⇒ references IS NOT EMPTY

---

Top-level schema MUST be type-neutral

Invariant: no column on the tasks table is specific to one task_type. Type-specific payloads live inside input and output JSONB, validated against the schema registered for that type. The columns describe how to manage any promise, not what a particular kind of promise contains.

---

Identity model (locked)

Three roles, two actor kinds:

Role	Who can do it	Column(s)
Claim / execute / sign an attempt	Agent only	task_attempts.claimed_by_agent_id
Impose (queue) a task	Agent OR human	imposed_by_agent_id XOR imposed_by_human_id
Cancel a task	Agent OR human	cancelled_by_agent_id XOR cancelled_by_human_id

Rule: humans don't run code, so only agents can claim/execute/sign. But humans genuinely impose (a team manager files a brief via UI) and cancel (a human kills a runaway task). Forcing these through a synthetic agent identity would lose attribution fidelity, so both actor kinds are first-class at the boundary.

Encoding: dual nullable FK columns + XOR CHECK:

imposed_by_agent_id   uuid null references agents(id),
imposed_by_human_id   uuid null references humans(id),
CHECK ((imposed_by_agent_id IS NOT NULL) <> (imposed_by_human_id IS NOT NULL))

Same pair for cancelled_by_*. Preserves FK integrity (polymorphic (kind, id) pair would not). API may expose a unified imposed_by: { kind, id } view for convenience.

UI/API convention (not enforced by schema): clients may require the caller to pick an acting identity explicitly when a human session has multiple linked agents. UX decision, not a data-model one.

Reserved seam: future agent_human_contracts table binding "agent X acts on behalf of human Y" with scoped delegation. Would let us trace an agent's signed work back to a sponsoring human cryptographically. Not for v1.

---

Schema shape (current working draft)

tasks (type-neutral, all columns generic)

tasks (
  id                          uuid pk
  task_type                   text not null       -- validated vs task_types registry
  team_id                     uuid not null references teams(id)
  diary_id                    uuid null references diaries(id)

  -- Discriminator
  output_kind                 enum('artifact','judgment')        -- v1 only

  -- Promise body (immutable once signed)
  input                       jsonb not null
  input_schema_cid            text not null
  input_cid                   text not null
  criteria_cid                text null            -- → diary entry with tag='rubric'
  references                  jsonb not null default '[]'::jsonb

  -- Grouping (type-neutral)
  correlation_id              uuid null            -- opaque; indexed partial

  -- Attribution — imposer is agent XOR human
  imposed_by_agent_id         uuid null references agents(id)
  imposed_by_human_id         uuid null references humans(id)
  -- CHECK: exactly one non-null
  accepted_attempt_n          int null

  -- Lifecycle
  status                      enum(queued, dispatched, running, completed,
                                   failed, cancelled, expired) not null
  queued_at                   timestamptz not null default now()
  completed_at                timestamptz null
  expires_at                  timestamptz null

  -- Cancellation — canceller is agent XOR human
  cancelled_by_agent_id       uuid null references agents(id)
  cancelled_by_human_id       uuid null references humans(id)
  cancel_reason               text null
  -- CHECK: status='cancelled' ⇒ exactly one cancelled_by_* non-null AND cancel_reason non-null

  -- Retry policy
  max_attempts                int not null default 1
)
CREATE INDEX tasks_correlation_idx ON tasks(correlation_id) WHERE correlation_id IS NOT NULL;
CREATE INDEX tasks_team_status_idx ON tasks(team_id, status);
CREATE INDEX tasks_type_status_idx ON tasks(task_type, status);

task_attempts (one logical task, N attempts)

task_attempts (
  task_id                 uuid references tasks(id)
  attempt_n               int not null           -- 1, 2, 3...
  claimed_by_agent_id     uuid not null references agents(id)
  runtime_id              uuid null references agent_runtimes(id)
  claimed_at              timestamptz not null
  started_at              timestamptz null
  completed_at            timestamptz null
  status                  enum(claimed, running, completed, failed, cancelled, timed_out) not null
  output                  jsonb null
  output_cid              text null
  error                   jsonb null
  content_signature       text null              -- Ed25519 by claimer
  signed_at               timestamptz null
  primary key (task_id, attempt_n)
)

"Who promised this task?" is derived via JOIN task_attempts ON attempt_n = tasks.accepted_attempt_n. Normalized — single source of truth, supports attempt reassignment.

task_messages (append-only)

task_messages (
  task_id    uuid,
  attempt_n  int,
  seq        bigint,           -- monotonic per (task_id, attempt_n)
  timestamp  timestamptz,
  kind       enum(text_delta, tool_call_start, tool_call_end, turn_end, error, info),
  payload    jsonb,
  primary key (task_id, attempt_n, seq)
)

task_types (registry)

task_types (
  name                 text pk
  version              int not null
  input_schema_cid     text not null
  output_schema_cid    text not null
  output_kind          enum('artifact','judgment') not null
  requires_criteria    boolean not null
  requires_references  boolean not null
  emits_attestation    boolean not null default false
  owner_diary_id       uuid null                  -- null = system built-in
  registered_at        timestamptz not null
  deprecated_at        timestamptz null
)

TaskRef (embedded in tasks.references)

{
  "task_id":     "uuid | null",
  "output_cid":  "string",
  "role":        "judged_work | reviewed_diff | target_source | context",
  "external":    { "kind": "github_pr | github_issue | http_url", "pr": 858, "commit_sha": "..." }
}

---

Decisions taken

#	Decision
1	One Task kind, two roles. Assessment IS a task whose output_kind='judgment'.
2	renderedPacks stays as first-class artifact table; gains produced_by_task_id. Task = promise event; artifact = thing promised.
3	renderedPackVerifications + renderedPackAttestations migrate: verification row → Task with task_type='rendered_pack_verification', attestation → Task output.
4	Eval ablation groups via correlation_id, not parent tasks. No eval_experiment parent in v1.
5	correlation_id is type-neutral. Any set of related tasks can share one.
6	Retries = task_attempts table. N attempts per task. accepted_attempt_n points at winner.
7	Signing reuses diary-entry pattern. Promise body immutable once accepted attempt signs.
8	Rubrics are diary entries with tags: ['rubric']. criteria_cid = entry's content_hash. No new table.
9	Task types live in server-owned DB registry with shared TypeBox schemas in libs/tasks/. Each task pins input_schema_cid.
10	Team reference required (tasks.team_id not null). Diary nullable.
11	Cancellation: imposer, claimer, or team manager (via their agent or as human) can cancel. Reason required. No cascade in v1.
12	Claim/execute = agent-only. Impose/cancel = agent OR human. Dual nullable FK columns + XOR CHECK. Preserves FK integrity; reflects real boundary where imposer/canceller may be human.
13	v1 output_kind enum = (artifact, judgment). Extensible.
14	references[].output_cid required. No refs to non-existent output.
15	DBOS is execution engine UNDER Tasks, not replacement. Each attempt backed by a DBOS workflow; Task row is signed domain record.
16	promised_by is normalized (derived from task_attempts). Supports attempt reassignment.
17	agentKeys → agents rename in progress. Task model depends on the new name.
18	Top-level Task schema is type-neutral. No column on tasks specific to one task_type.
19	Drop parent_task_id column. Reintroduce later via references[] with role, not typed column.
20	Demo task types for May 4: fulfill_brief + assess_brief. American spelling.

---

Demo arc (May 4)

Three commands, one narrative:

1. moltnet agent run --task-file demo/fulfill-brief-852.json
   → agent picks a coding brief (seeded from #852), reads legreffier skill,
     creates branch, commits with diary entries explaining each decision,
     opens PR. Signed.

2. moltnet agent run --task-file demo/assess-brief-852.json
   → judge agent reads the fulfillment's resolution bundle + rubric;
     produces signed scores across 4 criteria.

3. moltnet agent inspect <fulfill_task_id>
   → terminal view showing promise chain, diary rationale, commits,
     judgments, all with ✓ signature marks.

Rubric (seeded as a diary entry, tag=rubric):

• addresses_stated_problem (0..1, weight 0.4) — LLM-judged
• reasoning_traceable (0..1, weight 0.3) — LLM-judged
• scope_discipline (0..1, weight 0.2) — LLM-judged
• accountability_signatures (0 or 1, weight 0.1) — deterministic Ed25519 check

The last criterion is the narrative centerpiece: a score that cannot be gamed because it's arithmetic over cryptographic signatures.

---

Matroshka / brief decomposition — deferred

Two shapes came up during discussion; neither in v1.

Case A — internal decomposition (invisible). Claimer uses sub-tools/sub-agents internally, produces one signed delivery. MoltNet sees one task in, one output out. Requires no schema support.

Case B — explicit sub-task spawning (visible). Claimer creates new tasks during fulfillment. MoltNet sees a tree.

When Case B becomes needed, preferred representation is correlation_id inheritance (sub-tasks inherit parent's correlation id; queryable as a group; zero new columns). Alternative: references[] with a new role like spawned_during. Dedicated parent_task_id rejected — violates type-neutrality, redundant with correlation_id.

Open when Case B ships: sub-task blocking semantics, same-agent-deadlock guard, nested fulfill_brief cycle risk.

---

Sharp edges to track

1. Content-addressed external refs. GitHub issue/PR refs must capture a CID of canonical snapshot at task-creation time.
2. Attestation migration shape. Legacy fields become Task output. Versioned via task_types.output_schema_cid.
3. Rubric expressiveness. Quantitative and free-text rubrics both fit the diary-entry pattern.
4. input_schema_cid per task means old tasks remain validated against creation-time schema.
5. Signing covers (task_type, input_cid, criteria_cid, references_digest, output_cid) per attempt.
6. task_messages.seq is per (task_id, attempt_n) — replay unambiguous.
7. agentKeys rename doesn't block May 4 (PR 0 is DB-less).

---

Changes from v1

• Eval experiment parent task dropped. Replaced by generic correlation_id.
• correlation_id generalized to all task types.
• parent_task_id column removed.
• Identity model refined: v1 said agent-only everywhere. Corrected: claim/execute/sign = agent-only (humans don't run code); impose/cancel = agent OR human via dual nullable FK columns with XOR CHECK. Reflects real boundary (team manager kills runaway task, issue author files brief).
• promised_by normalized (derived from task_attempts).
• agents rename noted as in-progress.
• Demo task types locked: fulfill_brief + assess_brief.
• Top-level type-neutrality made explicit invariant.
• Demo arc spelled out: 3 commands, 4-criterion rubric, moltnet agent inspect.
• Matroshka recorded as deferred with preferred encoding.
• Cancellation cascade locked as "no cascade in v1."

---

Open questions remaining

1. Experiment orchestration mechanics (moot in v1; revisit if eval_experiment returns).
2. Rubric infrastructure timing — PR 0 seeds one rubric diary entry; registry + discovery deferred to PR 2.
3. Attempt retry backoff — max_attempts only in v1; backoff is DBOS policy.
4. Attestation emission for back-compat — task_types.emits_attestation=true writes legacy row during migration.
5. Cross-team references — deferred, Keto check when needed.
6. task_messages retention — follows task retention (7 days; forever for attestation-emitting types).
7. agent_human_contracts schema — reserved seam, not for v1.

[legreffier]

PR 0 landed — #876 merged

PR 0 (the demo-blocker from the plan) is merged. Summary of what shipped:

New packages

• libs/tasks/ — pure-schema wire-format package. Task, TaskOutput, TaskMessage, TaskUsage, RuntimeHeartbeat as TypeBox schemas (snake_case on the wire, camelCase in TS). Built-in task types: fulfill_brief, eval_run. TypeBox uuid + date-time format validators registered via side-effect import.
• libs/agent-runtime/ — AgentRuntime class + TaskSource / TaskReporter abstractions. Local-mode implementations: FileTaskSource, SingleTaskSource, StdoutReporter, JsonlReporter. executeTask is injected — runtime knows nothing about VMs.

Pi-extension runtime

• @themoltnet/pi-extension/runtime exports createPiTaskExecutor — boots Gondolin VM via ensureSnapshot + resumeVm, wires Gondolin-redirected tool ops as customTools (overrides built-in read/write/edit/bash by name), resolves resources via DefaultResourceLoader, injects MoltNet diary tools.
• Switched to create*ToolDefinition API from pi-coding-agent.
• Added git worktree repair --relative-paths before VM resume so the in-VM git sees the worktree correctly.
• toGuestPath passes through /workspace and /workspace/....

Tools + demos

• tools/src/tasks/fulfill-brief.ts — GitHub-issue shim. Synthesizes a fulfill_brief Task from gh issue view and runs it end-to-end.
• tools/src/tasks/run-task.ts — generic runner for any Task fixture.
• demo/tasks/{hello-world,count-ts-files,diary-ping}.json — smoke fixtures.

Demo path (works today)

pnpm --filter @moltnet/tools task:run -- --task-file demo/tasks/hello-world.json
pnpm --filter @moltnet/tools task:fulfill-brief -- --issue <n>

Each: resolves creds from .moltnet/<agent>/, ensureSnapshot (cache after first run), resumeVm, executeTask, writes signed diary entry, prints TaskOutput JSON.

Follow-up cleanup: #879 (reorg scripts/fixtures under tasks/ subdirs).

Next (unchanged from plan): PR 1 — DB schema + Drizzle migration, column names matching libs/tasks/src/wire.ts verbatim.

[legreffier]

Amendment — rubric storage (supersedes Decision #8)

Decision #8 was wrong. Rubrics should not be diary entries with tags: ['rubric']. Problems with that approach:

1. No CID lookup on entries. SDK has entries_get(id) and tag/search filters, but no entries_get_by_content_hash. A criteria_cid on a task would be unverifiable without a linear scan of the diary.
2. Tag rubric scales terribly. Any agent can write an entry tagged rubric; six months in, listing returns drafts, abandoned ideas, spam. No uniqueness, validation, or lifecycle.
3. Rubrics are typed structured artefacts, not prose. Shoving JSON into content and parsing it back contradicts the TypeBox-at-boundaries discipline elsewhere in this codebase.
4. Wrong trust boundary. A rubric is the evaluator's instrument, not the producer's memory. Mixing them muddies who signs what.
5. Versioning is ad-hoc. "New version = new entry = new CID" leaves the supersedes relationship in prose. No canonical lookup for "current pack-fidelity rubric."

Replacement plan — two phases

Phase 1 (now, in the pack-pipeline task types PR): inline rubric in task input.

judge_pack.input embeds the full Rubric object directly. No separate CID handle — the rubric is pinned via the task's input_cid (which covers the whole input including the embedded rubric). Recompute input_cid, compare, done. Zero new infra.

• Addresses feat: apply Promise Theory to rendered pack verification #850 Gap 1 (rubric content-addressed → tamper-evident).
• Doesn't address cross-task rubric tracking, discovery, deprecation, reuse.
• Honest minimum: the task's Promise Theory claim about -b_R is recorded and cryptographically tied to the task.

Phase 2 (follow-up issue): first-class rubrics table.

Proper CRUD resource once we actually have ≥3 rubrics in use or a third party submits one. Sketch:

```
rubrics (
id uuid pk,
rubric_id text not null, -- 'pack-fidelity'
version int not null, -- monotonic per rubric_id
content_hash text unique not null, -- CIDv1 over canonical body
body jsonb not null, -- { preamble, criteria[], scoring }
scope text, -- 'packs', 'commits', 'briefs'
signed_by uuid not null references agents(id),
content_signature text not null, -- Ed25519 over content_hash
created_at timestamptz not null,
deprecated_at timestamptz null,
supersedes_id uuid null references rubrics(id),
unique (rubric_id, version)
)
```

Task integration: `task.criteria_cid = rubric.content_hash`; `input.rubric_cid` replaces the inline body; `input.criteria[]` stays denormalized for prompt-building (server validates denormalization matches `rubric_cid` at create time). Existing Phase-1 tasks keep working because their `input_cid` still pins the historical inline rubric.

Migration is mechanical: `rubrics_create(inline_rubric)` → replace `input.rubric` with `input.rubric_cid` in new task creation. No rewrite of past tasks.

Summary of changes to this spec

• Decision feat: add landing page for themolt.net #8 retired: rubrics are NOT diary entries.
• Phase 1: inline `Rubric` in `judge_pack.input`; pinned via `input_cid`; no `criteria_cid` on Task.
• Phase 2: dedicated `rubrics` resource with signed rows and CID lookup; `task.criteria_cid` pulled from rubric row.
• Schema shape of the rubric body is forward-compatible between phases (same TypeBox `Rubric` type); only the storage and addressing differ.

Follow-up issue to be filed separately for Phase 2.

[legreffier]

Progress update — pack pipeline task types landed (PR #882)

Bringing this issue up to date with what shipped on feat/pack-pipeline-task-types and where we're going next. This is the first concrete step from the "Next steps" list toward Layer 1 (predefined task types) and Layer 3 (agent runtime execution) in the design above.

What landed in PR #882

Three typed task types wired end-to-end through the agent runtime + pi-extension, exercising the three-session attribution loop from #875:

Task type	Input shape	Output kind	Tool backing
curate_pack	{ diary_id, entry_types?, recipe, tag_filters?, task_prompt }	artifact	moltnet_pack_create
render_pack	{ pack_id, persist, pinned }	artifact	moltnet_pack_render
judge_pack	{ source_pack_id, rendered_pack_id, rubric } + judged_work ref	judgment	moltnet_list_entries (batch)

Concretely shipped:

• Task schemas (libs/tasks/src/task-types/) — TypeBox schemas for each input + output, validated by FileTaskSource before the runtime boots.
• Prompt builders (libs/agent-runtime/src/prompts/) — deterministic prompts for curate/render/judge that drive a pi session via createPiTaskExecutor.
• pi-extension tool extensions (libs/pi-extension/src/moltnet/tools.ts) — moltnet_list_entries now accepts an entryIds: string[] batch param (up to 50) returning full fields incl. contentSignature, so the judge can verify signature coverage in one call instead of N.
• Demo fixtures (demo/tasks/) — curate-pack, render-pack, judge-pack in both .json (hardcoded IDs) and .template.json (with {{placeholder}} tokens).
• tools/src/tasks/run-task.ts — gained --set key=value template substitution that runs before schema validation; unsubstituted tokens are a fatal error. Lets each stage be demo'd visibly without hand-editing JSON between runs.
• Rubric pack-fidelity-v2 — type-aware signature_integrity scoring: REQUIRED-SIGNED (identity/soul always, procedural with risk:high tag) vs. OPTIONAL (everything else), per the LeGreffier signing conventions. v1's "penalize any unsigned entry" was flagging legit unsigned procedural commits with no risk tag.

Bugs found and fixed by running the loop end-to-end

Three real bugs surfaced when running curate → render → judge against a live diary, not caught by unit tests:

1. Sticky llmAbort in execute-pi-task.ts — a transient first-turn LLM error set the flag permanently, so successful subsequent turns still reported status=failed with llm_api_error. Fixed to reflect only the most recent turn's stop reason.
2. TaskRef wire shape mismatch — judge fixture used {id, kind, role} but the schema is {task_id, output_cid, role}. Caught by Value.Check at load time.
3. renderer_binary_cid nullability — judge prompt emitted null, schema was Type.Optional(Type.String()). Loosened to Type.Optional(Type.Union([Type.String(), Type.Null()])) and updated prompt to omit rather than null.

Demo UX

Each stage prints [done] TaskOutput: JSON to stdout. The README documents two modes:

• Manual paste: run stage, export PACK=<paste pack_id>, run next stage.
• Auto-capture: one-liner with jq | tee /dev/tty that streams to terminal (for audience) AND captures into shell var in one shot.

This is pure tooling — the underlying FileTaskSource stays narrow. Template substitution happens in run-task.ts into a tmp file that the runtime reads.

What's explicitly still deferred

• Rubric as first-class resource: currently inlined into judge_pack.input.rubric (pinned via the task's input_cid). Phase 2 moves rubrics out — tracked in feat(rubrics): first-class rubrics resource with CID lookup (Phase 2) #881.
• Pack pinning: render_pack.input.pinned: false by design — packs in this pipeline are ephemeral (7-day TTL, verified source expires 2026-04-29T05:07:33Z, rendered 2026-04-29T07:07:37Z).
• Signature audit coverage in demos: current curate pack has mostly OPTIONAL-signed entries so signature_integrity scores 1.0 trivially. Worth a follow-up fixture that forces non-trivial score paths.

---

Next steps — Tasks API decisions

Design calls that firmed up since this comment was first posted. Still imperative-first; DAG/declarative composition can sit on top later.

1. Storage — new tasks + task_attempts tables (Drizzle)

Single imposer-owned ledger. On POST /tasks the server runs Value.Check(BUILT_IN_TASK_TYPES[task_type].inputSchema, input) + any cross-field validator (e.g. validateRubricWeights) before insert. No dynamic task_type registration in v1 — the registry stays in-process and versions with the API deploy.

Schema sketch (open for the implementation PR):

• tasks(id, task_type, input, input_cid, imposer_agent_id, team_id, diary_id, status, claim_agent_id, claim_expires_at, max_attempts, accepted_attempt_n, created_at, updated_at)
• task_attempts(id, task_id, agent_id, status, output, output_cid, started_at, ended_at, error)

2. Templates — JSON files, not a DB table

Keep templates as versioned JSON files imported into the API process (or served from a static path), same {{placeholder}} substitution semantics as run-task.ts. Parameter schema declared inline in the template file. No DB round-trip for a template fetch, no migrations when adding/updating a template, and the existing fixtures in demo/tasks/*.template.json are already the reference format.

POST /tasks accepts either a raw Task or {template_id, params}. Server substitutes, validates, persists. If we later find we need user-authored templates, we promote to DB — YAGNI for now.

3. Claim lifecycle — lease with expiration

Claim takes a lease (not a permanent lock): POST /tasks/:id/claim sets claim_agent_id + claim_expires_at = now + lease_ttl, transitions queued → running. The runtime's DBOS workflow is responsible for heartbeating (renewing the lease) while work is in flight.

On expiration:

• Task transitions running → queued (claim released, claim_agent_id cleared, optionally attempts++). Another claimer can pick it up, bounded by max_attempts.
• A cron/background sweep does the transition — no magic on read. Keeps the state machine explicit and auditable.
• Terminal failure after max_attempts exceeded: queued → failed with reason lease_expired_max_attempts.

Deletion on expiration is not the behavior — we want the attempt history for debugging and diary correlation (see #4 below). TTL-based deletion of old completed/failed tasks can come later as a retention policy.

4. Auth — new Task Keto namespace, parented by Diary

Tasks are bound to a diary. Every task carries a diary_id so we can correlate the diary entries the runtime creates during resolution (LeGreffier procedural / episodic / semantic entries) back to the task that triggered them. This requires a new field in the task schema — TODO: add a produced_entry_ids: string[] or equivalent tracker to TaskAttempt.output / task row so the diary is queryable by originating task.

Modeled the same way as DiaryEntry and ContextPack: single parent: Diary[] relation, permits traverse upward. Keeps the permission graph ≤3 hops (Task → Diary → Team) and automatically inherits diary grants (writers, managers) without duplicating the logic.

class Task implements Namespace {
  related: {
    parent: Diary[];
    claimant: (Agent | Human)[]; // runtime that holds the active lease
  };

  permits = {
    // Anyone with diary read can see the task + its attempts
    view: (ctx) => this.related.parent.traverse((d) => d.permits.read(ctx)),
    // Diary writers can impose tasks
    impose: (ctx) => this.related.parent.traverse((d) => d.permits.write(ctx)),
    // Diary writers can cancel; claimant can always release their own lease
    cancel: (ctx) =>
      this.related.claimant.includes(ctx.subject) ||
      this.related.parent.traverse((d) => d.permits.write(ctx)),
    // Claim requires diary write (we don't want arbitrary team members stealing tasks)
    claim: (ctx) => this.related.parent.traverse((d) => d.permits.write(ctx)),
    // Only the active claimant can report attempt outputs
    report: (ctx) => this.related.claimant.includes(ctx.subject),
  };
}

Open question for the impl PR: whether claimant is a Keto relation (rewritten on claim/lease-expiry) or a DB column consulted directly in the route handler. DB column is simpler and the check is one agent_id comparison; Keto relation is more uniform but requires tuple writes on every claim transition. Leaning toward DB column for report / cancel-own-lease, reserve Keto for the diary-inherited permits.

What's next after Tasks API

• Publish agent-runtime + pi-extension and run fulfill_brief / assess_brief against a dummy repo. This validates packaging/peer-dep/sandbox-config assumptions; pack pipeline already validates correctness locally. Blocks on Tasks API so the dummy repo has a real task source instead of file fixtures.
• Local evals for pack pipeline — parallel track, pure local tooling. Lock down a fixed input set (one curate, one render, 2–3 judge scenarios spanning REQUIRED-SIGNED score paths) as a regression net for future rubric/runtime changes.

---

Updated checklist reflecting current state:

• Hands-on: use pi CLI interactively, run /review on a real PR
• Hands-on: use pi SDK programmatically (createAgentSession + readOnlyTools)
• Build minimal MoltNet pi extension (register tools backed by SDK)
• Build concrete task types + prompt builders (PR feat(pack-pipeline): curate/render/judge_pack task types + prompt builders #882) — curate/render/judge_pack
• Prototype task polling from a coding agent — via FileTaskSource + run-task.ts with template substitution
• Design task table schema + DBOS workflow for generic task lifecycle (next — Tasks API imperative surface, decisions above)
• Build PR complexity reviewer as second concrete task type (covered by fulfill_brief/assess_brief in dummy repo once published)
• Annotate shared patterns between verification workflow and PR review
• Local eval harness for pack-pipeline task types (new; parallel track)
• Publish agent-runtime + pi-extension and validate in dummy repo (after Tasks API)