Design: runtime package boundary

[tnez]

Parent: #103

Context

The runtime package effort needs a crisp boundary before implementation starts.

The motivating product story is that a user should be able to install @tnezdev/agentic, initialize a workspace, add a runtime, and run the workspace:

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

At the same time, core Agentic should remain runtime-agnostic. It should not become the model loop, terminal UI, scheduler, daemon, deployment system, or session store.

Goal

Write the design boundary for runtime packages: what core owns, what runtime packages own, how the CLI discovers/delegates to them, and what minimum shared types/config are required.

Questions to settle

1. What is the minimal runtime package manifest shape?
2. What commands does core implement directly versus delegate?
3. What is the config shape for installed/enabled runtimes?
4. How does agentic runtime add local resolve to @tnezdev/agentic-runtime-local?
5. What package manager behavior is acceptable for install (bun, npm, pnpm) in the first slice?
6. Should runtime commands be capability-based rather than assuming every runtime supports start, stop, deploy, etc.?
7. What shared RuntimeContext does a runtime package receive?
8. How does the local runtime see personas, workflows, skills, artifacts, memory, and config?
9. Where do lightweight invocation records fit, if at all?
10. What explicit non-goals keep core from becoming a harness?

Expected design stance

Start from these assumptions unless the design discovers a reason to change them:

• Public runtime names are targets like local and later cloudflare.
• Pi is the implementation detail for the local runtime, not the public runtime name.
• Core owns CLI front door, workspace conventions, primitive APIs, and runtime package discovery/delegation.
• Runtime packages own harness/platform integration.
• Core does not own harness sessions.
• Runtime invocation metadata is allowed; a full session primitive is not part of the first slice.

Deliverable

A design note, issue comment, or checked-in artifact that future implementation issues can point to.

The deliverable should include at least:

• Proposed runtime package manifest/interface.
• Proposed agentic runtime ... command behavior.
• Proposed runtime config shape.
• Core/runtime responsibility table.
• Explicit non-goals.
• Open questions deferred to local runtime implementation.

Non-goals

• Do not implement the runtime CLI here.
• Do not create the local runtime package here.
• Do not design Cloudflare deeply here.
• Do not add a session primitive here.

Acceptance

• A future implementer can read the boundary and know the first code PRs to make.
• The design preserves the promise from Runtime packages: make Agentic workspaces runnable #103: Agentic core remains runtime-agnostic while the CLI becomes the runtime package front door.

[tnez]

Proposed boundary v0

This is a concrete proposal for the first implementation pass. It is intentionally smaller than a general plugin system and intentionally does not make core Agentic a harness.

Summary

Agentic core should expose a runtime package seam, not a runtime implementation.

Core owns the CLI front door, workspace conventions, primitive APIs, config resolution, runtime package discovery, and command delegation. Runtime packages own harness/platform integration. External harnesses own sessions, transcripts, model loops, tool execution, compaction, and provider/runtime-specific behavior.

The first public runtime target is local, implemented by @tnezdev/agentic-runtime-local. The local runtime may use Pi under the hood, but pi is not the public runtime name.

Package model

Target monorepo shape:

package.json                    # private workspace root
packages/
  agentic/                      # @tnezdev/agentic
  agentic-runtime-local/        # @tnezdev/agentic-runtime-local
examples/
  second-brain/

Published packages:

@tnezdev/agentic
@tnezdev/agentic-runtime-local

Future package:

@tnezdev/agentic-runtime-cloudflare

Core should export runtime types from a stable path such as:

import type { AgenticRuntimePackage } from "@tnezdev/agentic/runtime";

@tnezdev/agentic must not depend on @tnezdev/agentic-runtime-local or Pi.

Runtime package manifest

Runtime packages should export a small manifest object. Exact naming can change during implementation, but the shape should stay close to this:

export interface AgenticRuntimePackage {
  kind: "agentic-runtime";
  api_version: 1;
  name: string; // "local"
  package_name: string; // "@tnezdev/agentic-runtime-local"
  description?: string;
  capabilities: RuntimeCapability[];
  commands: RuntimeCommandMap;
}

export type RuntimeCapability =
  | "init"
  | "run"
  | "status"
  | "dev"
  | "deploy"
  | "interactive"
  | "json-events"
  | "harness-sessions";

export interface RuntimeCommandMap {
  init?: RuntimeCommandHandler<RuntimeInitArgs>;
  run?: RuntimeCommandHandler<RuntimeRunArgs>;
  status?: RuntimeCommandHandler<RuntimeStatusArgs>;
  dev?: RuntimeCommandHandler<RuntimeDevArgs>;
  deploy?: RuntimeCommandHandler<RuntimeDeployArgs>;
}

export type RuntimeCommandHandler<TArgs> = (
  ctx: RuntimeContext,
  args: TArgs,
) => Promise<RuntimeCommandResult | void>;

export interface RuntimeCommandResult {
  summary?: string;
  data?: unknown;
}

Runtimes should implement only the commands that make sense. Core should not assume every runtime supports start, stop, deploy, or daemon semantics.

Runtime context

Core passes a RuntimeContext to delegated commands. It should contain enough to operate the Agentic workspace without giving runtime packages ownership of core internals.

Candidate shape:

export interface RuntimeContext {
  cwd: string;
  workspace_root: string;
  runtime_name: string;
  runtime_package: string;
  json: boolean;
  env: Record<string, string | undefined>;
  config: AgenticConfig;
  runtime_config: Record<string, unknown>;
  agentic: AgenticRuntimeBindings;
}

export interface AgenticRuntimeBindings {
  personas: PersonaAdapter;
  skills: Source;
  workflows: WorkflowAdapter;
  artifacts: ArtifactAdapter;
  memory?: unknown;
}

The exact adapter types should follow the existing core interfaces. If memory does not yet have a formal adapter interface, do not invent a large one just for runtime work. Pass only what the first local runtime needs.

Config shape

Workspace config should record runtime targets in .agentic/config.toml.

Proposed initial shape:

[runtime]
default = "local"

[runtime.local]
package = "@tnezdev/agentic-runtime-local"

Core owns runtime.default, the target name, and the package key used for discovery.

All other keys under [runtime.<name>] are runtime-owned and should be passed through as opaque runtime_config.

Example future local runtime config:

[runtime]
default = "local"

[runtime.local]
package = "@tnezdev/agentic-runtime-local"
harness = "pi"

Core should not interpret harness = "pi" beyond passing it through.

Runtime name resolution

Core should have a tiny built-in alias map for official runtime targets:

const OFFICIAL_RUNTIME_PACKAGES = {
  local: "@tnezdev/agentic-runtime-local",
  cloudflare: "@tnezdev/agentic-runtime-cloudflare",
} as const;

For the first slice, only local needs to be usable. cloudflare can appear in design/docs as a future target but should not behave as implemented.

Future third-party package support can be designed later. Do not block the first local runtime on a generic marketplace/plugin registry.

CLI command behavior

Core implements the runtime namespace and handles command parsing, common output, package resolution, manifest validation, and delegation.

Candidate command surface:

agentic runtime list
agentic runtime add <name>
agentic runtime init [name]
agentic runtime run [target]
agentic runtime status [name]

agentic runtime list:

Shows installed/configured runtimes and known official aliases. It should clearly distinguish installed/configured/available.

agentic runtime add local:

Resolves local to @tnezdev/agentic-runtime-local, ensures the package is present or tells the user how to install it, and records the runtime config. The exact package-manager behavior belongs to #107. A safe first implementation may print the install command when automatic install is ambiguous.

agentic runtime init local:

Loads the configured runtime package and delegates to commands.init. If no name is provided and one default runtime exists, use it. If multiple exist and no default is configured, require a name.

agentic runtime run <target>:

Loads the default runtime and delegates to commands.run, passing target as a runtime-owned string. Core should not try to interpret target names beyond common flags.

agentic runtime status local:

Delegates to commands.status if implemented. If the runtime lacks status, core should return a clear unsupported-command error.

Core/runtime responsibility table

Area	Core @tnezdev/agentic	Runtime package
CLI namespace	Owns agentic runtime ... parsing	Implements delegated command handlers
Package aliases	Owns official alias map	Declares manifest name/package
Package install/discovery	Owns resolution and manifest validation	Exports manifest
Config	Owns common [runtime] keys	Owns opaque [runtime.<name>] keys
Workspace primitives	Owns APIs/adapters/sources	Uses them through RuntimeContext
Harness sessions	References only, if needed	Owns mapping to harness session refs
Model loop/tool execution	Does not own	Runtime/harness owns
Scheduling/hosting	Does not own in first slice	Runtime/platform owns when applicable
Artifacts	Owns artifact primitive	Runtime can create/write/read artifacts through core API
Workflow graphs/runs	Owns graph/runtime state machine	Runtime may choose how to invoke/apply it
Output formatting	Core handles common human/JSON wrapper	Runtime returns structured result

Invocation records and sessions

Do not add a full Session primitive in this design.

If the local runtime needs durable traceability, add or design a lightweight RuntimeInvocation record under #109. It should record that a runtime command happened and optionally link to a harness-owned session reference.

Illustrative shape:

interface RuntimeInvocation {
  id: string;
  runtime: string;
  target?: string;
  status: "running" | "completed" | "failed";
  started_at: string;
  ended_at?: string;
  workflow_run_id?: string;
  artifact_ids?: string[];
  harness_ref?: {
    provider: string;
    id: string;
    uri?: string;
  };
}

A Pi session tree is a harness_ref, not an Agentic session.

First implementation sequence

Recommended PR order:

1. Chore: migrate Agentic to packages/ monorepo layout #104: pure monorepo migration. No runtime behavior.
2. CLI: add runtime command namespace #106: add runtime CLI namespace with helpful placeholder behavior.
3. CLI: support runtime package install, discovery, and delegation #107: implement package discovery/delegation.
4. Runtime local: create @tnezdev/agentic-runtime-local package #108: add @tnezdev/agentic-runtime-local skeleton.
5. Runtime local: run one second-brain workflow locally #111: make one second-brain target runnable through local runtime.
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 for invocation records and Pi integration.
7. Docs: make second-brain example runnable with the local runtime #112: update docs once the command path is real.

Non-goals

• No runtime implementation in core.
• No Pi dependency in core.
• No Cloudflare implementation in the first slice.
• No daemon/service mode.
• No scheduler.
• No generic plugin marketplace.
• No full Session primitive.
• No transcript storage in Agentic core.
• No model/provider abstraction in Agentic core.
• No tool execution loop in Agentic core.

Deferred to local runtime work

These should be answered in #108, #110, or #111 rather than in the core boundary:

• Whether local uses Pi SDK, RPC, print/JSON mode, a Pi extension, or generated Pi skills/templates.
• How Agentic workflows become Pi-runnable targets.
• Whether agentic runtime run <target> starts a fresh Pi run or can continue a previous harness session.
• How Pi session identifiers are surfaced to users.
• What durable output the first second-brain run should produce.

Recommendation

Accept this as the v0 boundary unless implementation uncovers a simpler seam. Start with #104 as a pure monorepo migration, then return to #106/#107 for the runtime CLI surface.

[tnez]

Boundary v0 is captured in the design comment and was used to complete the monorepo migration in #104 / #113. Treat this as accepted enough to proceed to #106. Reopen only if implementation uncovers a simpler or conflicting runtime seam.