Runtime packages: make Agentic workspaces runnable

[tnez]

Why this exists

The examples/second-brain work exposed a product-story gap in Agentic.

Agentic has a coherent set of primitives: personas, skills, workflows, artifacts, memory, dispatch vocabulary, and workspace conventions. But when explaining the second-brain example, the natural user question is still:

How do I actually run this thing?

Historically we have been careful that @tnezdev/agentic does not ship a low-level agent harness. That boundary still feels right. But the project needs a better answer than "bring your own harness" if the public examples are going to feel real.

This umbrella tracks the path toward runtime packages: Agentic remains runtime-agnostic at core, while the CLI becomes the stable front door for installing and delegating to runtime packages.

North-star DX

The story we want to make true:

bun add @tnezdev/agentic
agentic init --example second-brain

agentic runtime add local
agentic runtime init local
agentic runtime run <target>

A user should be able to install Agentic, initialize a workspace, choose where it runs, and then run a meaningful target from that workspace.

Product direction

• @tnezdev/agentic remains the core package and CLI entry point.
• Runtime packages are separate packages in the same monorepo.
• The first runtime package is @tnezdev/agentic-runtime-local.
• The public runtime name is local, not pi.
• The local runtime may use the Pi agent harness / Pi SDK under the hood.
• A later Cloudflare runtime should be possible, but it is not the first implementation slice.
• The second-brain example is the proving ground: it should become runnable, not just illustrative.

Intended monorepo shape

Target direction:

package.json                    # private workspace root
packages/
  agentic/                      # @tnezdev/agentic
  agentic-runtime-local/        # @tnezdev/agentic-runtime-local
  agentic-runtime-cloudflare/   # later, design-only for now
examples/
  second-brain/

The core package should move into packages/agentic before runtime packages become real first-class packages.

Boundary decisions to preserve

These are the important decisions from the initial design conversation. Future work should preserve them unless a later design issue explicitly changes them.

• Core Agentic is still not a low-level harness.
• Core Agentic should not own model loops, tool execution, provider switching, terminal UI, compaction, or conversation trees.
• Runtime packages own harness/platform integration.
• local is a runtime target; Pi is an implementation detail of that target.
• Do not introduce a full Agentic session primitive as part of the first runtime slice.
• Pi already owns harness sessions/session trees. Agentic may record lightweight runtime invocation metadata with a harness reference.
• Dispatch can remain the vocabulary seam without forcing core to own transport, scheduling, or hosting.
• Cloudflare should be informed by the local runtime learnings, not designed first in the abstract.

Runtime vocabulary

Useful distinctions for future design work:

• WorkflowRun: state/history for an Agentic workflow graph.
• RuntimeInvocation: one call into a runtime package, such as agentic runtime run inbox-review.
• HarnessSession: the external harness' session/conversation object, such as a Pi session tree.
• Artifact: durable Agentic output produced by work.

The likely first persistent record is RuntimeInvocation, not Session.

Relationship to existing issues

This issue is related to, but distinct from:

• Roadmap: second-brain example from private dogfood #100: second-brain example from private dogfood. That issue is about the example shape/content. This umbrella is about making Agentic workspaces runnable.
• Roadmap: external artifact storage and cross-environment sync #99: external artifact storage and cross-environment sync. Runtime work may increase pressure on artifact portability, but this umbrella should not implement external artifact storage.
• Design: v0.2 composition object (informed by task_next LIFO observation) #16: Scope/composition object. Runtime packages may consume scope-like context, but this umbrella should not collapse runtime execution into Scope.

Starter issue map

The first pass of sub-issues is intentionally small and ordered around learning. Add more sub-issues here as the roadmap sharpens.

• Design: runtime package boundary #105
• Chore: migrate Agentic to packages/ monorepo layout #104
• CLI: add runtime command namespace #106
• CLI: support runtime package install, discovery, and delegation #107
• Runtime: define lightweight invocation records without adding sessions #109
• Runtime local: create @tnezdev/agentic-runtime-local package #108
• Runtime local: run one second-brain workflow locally #111
• Runtime local: evaluate and integrate Pi SDK as the local harness #110
• Docs: make second-brain example runnable with the local runtime #112

Suggested order:

1. Design: runtime package boundary #105 first, to settle the runtime package boundary.
2. Chore: migrate Agentic to packages/ monorepo layout #104 second, as a pure monorepo move with no runtime feature work.
3. CLI: add runtime command namespace #106 and CLI: support runtime package install, discovery, and delegation #107 to expose the CLI front door and delegation mechanism.
4. Runtime local: create @tnezdev/agentic-runtime-local package #108 to create the first runtime package.
5. Runtime local: run one second-brain workflow locally #111 to prove the second-brain runnability story.
6. Runtime: define lightweight invocation records without adding sessions #109 and Runtime local: evaluate and integrate Pi SDK as the local harness #110 as needed to support durable run records and Pi-backed local execution.
7. Docs: make second-brain example runnable with the local runtime #112 once the runnable path is real enough to document honestly.

Non-goals for the first slice

• No daemon/service mode.
• No scheduler.
• No Cloudflare implementation.
• No generic hosting abstraction in core.
• No full session primitive.
• No transcript storage in Agentic core.
• No runtime-owned identity/auth model in core.
• No external artifact storage implementation.

Future-self notes

If you are picking this up in a future session:

1. Start by reading this issue, then Roadmap: second-brain example from private dogfood #100.
2. Keep the first implementation path boring: pure monorepo move, then CLI namespace, then local runtime package skeleton.
3. Do not mix the monorepo migration with runtime feature work.
4. Use the second-brain example as the acceptance test for the product story.
5. Be suspicious of designs that make core Agentic responsible for harness sessions, scheduling, or long-running process supervision.
6. Let the local runtime teach us the adapter shape before opening the Cloudflare implementation lane.

Close criteria

This umbrella can close when:

• @tnezdev/agentic lives as a core package in a monorepo.
• @tnezdev/agentic-runtime-local exists as a first-class package.
• The core CLI can add/init/run the local runtime through the public agentic runtime ... surface.
• examples/second-brain documents and demonstrates a real local runtime path.
• Any remaining Cloudflare work is captured in a separate design/roadmap issue.