Skip to content

Update packages/lal/LAL-ARCHITECTURE.md for the pi-agent-core harness and inbox loops #726

Description

@0xpatrickbot

Problem

packages/lal/LAL-ARCHITECTURE.md has a short post-pi-harness note, but the body still describes the pre-pi implementation. It incorrectly presents lal as a monolithic agent with approximately 1,507 lines, 16 hardcoded OpenAI-format tool schemas, a single switch dispatcher, no dynamic context building, and an active provider abstraction.

The documentation should be updated to match the implementation on origin/llm. This is a documentation update, not a request to rewrite lal or redesign its runtime.

Current model to document

lal runs its agent loop on @earendil-works/pi-agent-core through @endo/agentry/harness via makePiAgent.

The inbox integration has two layers, coupled by a trigger prompt and mail tools:

┌─ OUTER: inbox follow-loop  (inbox-loop.js) ────────────────────────┐
│  iterateReader(E(powers).followMessages())   ← @endo/exo-stream    │
│  • races next() vs. cancellation                                   │
│  • skips own messages; defers partial (done:false); skips          │
│    already-seen-then-edited numbers (editMessage)                  │
│  • per settled inbound msg →  runOneRound("You have new mail…")    │
│                                     │                              │
│        ┌─ INNER: one pi round  (round-runner.js → agent-round.js) ─┐│
│        │  for await (event of runAgentRound(piAgent, prompt))      ││
│        │    ToolCallStart / ToolCallEnd / Message / Error          ││
│        │  PiAgent tool surface: mail tools + execute code-mode …   ││
│        │    listMessages / send / reply / dismiss / editMessage    ││
│        │      →  E(powers).*   (back into the daemon inbox)        ││
│        └────────────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────────────┘

The revised document should explain that:

  • The worker builds a listTools/execTool surface at spawn time. It is not a static OpenAI schema array dispatched by one switch.
  • Pi provides the agent loop, but has no native inbox concept. The outer Endo follow loop supplies inbound events, while mail tools target E(powers).*.
  • runRound consumes runAgentRound events including tool-call starts, tool-call ends, messages, and errors.
  • lal already supports the send/act/edit message model, including editMessage, done: false partials, messageHistory, and seenInboundNumbers.
  • packages/lal/providers/ is a compatibility surface for downstream consumers, not the provider architecture used by lal’s worker loop.

Acceptance criteria

  • Remove or replace the remaining pre-pi descriptions throughout LAL-ARCHITECTURE.md.
  • Describe the responsibilities of inbox-loop.js, round-runner.js, agent-round.js, agent.js, and tools/mail.js.
  • Preserve the two-layer diagram above in the revised document.
  • Clearly distinguish the pi agent runtime from Endo’s inbox and capability surfaces.
  • Keep the scope limited to bringing the architecture documentation up to date.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions