Repository navigation
Description
Summary
pi-schematic emits nothing on pi's inter-extension bus today. Another extension that wants to know what schematic did has to rebuild it from tool calls, tool results, session entries and notification text.
This issue proposes a public, versioned set of fire-and-forget events, one family per primitive:
- handoff
- required handoff requests and watchdog nudges
- spawn
- notebook
- readonly mode
- Model Groups and prompt frontmatter
The events say what happened, not what was said. They carry only counts, sizes, ids, closed enums and durations. They never carry instructions, context, prompts, notebook page names or bodies, topic text, child output, shell commands, error messages or paths.
This issue defines the contract and the behaviour only. How and where to emit is left to the implementing PR.
Motivation
- Some outcomes are not visible from outside.
- A handoff call only stages the request. The cut is written at the end of the turn, and the handoff completes or fails later, at the next turn or when the run settles. No tool event reports that outcome.
- Refusals, declined turns, cuts that pi did not persist, and staged handoffs dropped by
/treeor/newleave nothing on the branch at all, or only a failure message whose text a consumer would have to match.
- Spawn failures before a child exists throw. "No model configured", constraint validation, route resolution and session-creation failures produce no
details. - Readonly, the notebook and the watchdog are mostly invisible.
- A readonly block becomes a tool error with display text.
- A sandboxed bash command looks like any other bash call.
- Notebook truncation and rejections show up only in result text.
- Watchdog nudges go into the model's context and nowhere else.
- Consumers depend on internals. Analytics, fleet dashboards and session explorers parse tool arguments, result text and
detailsshapes today. Any refactor can break them, and tool arguments are the most sensitive data on the path. - Code in this repo needs the same signals. The workflow stack (feat(workflow): rebind runs across new sessions and handoffs #110) adds its own handoff settlement watch so it can rebind runs across handoffs. It should get those signals from a direct internal callback at the same emit points, not from
pi.events: pi's bus wraps listeners inasync, runs them in registration order and sends their errors toconsole.error, which corrupts the TUI. The public events and the internal callback report the same facts from one place.
The repo already has one durable contract: a handoff cut is a compaction entry whose details.handoffId is set, and the successor message carries the same id. These events reuse that id so they can be joined to the persisted entries.
Relation to open work
- An extension model for pi-schematic #135 (extension model). These events follow An extension model for pi-schematic #135's content-free payload model for public "after" events (its question 4). They are emitted from one helper on the same core lifecycle paths, after schematic's own reactions to that moment have run (for example after the handoff settles, not at the start of settling). If a schematic-owned dispatcher lands, the helper moves behind it and emits after the last listener, and this public contract doesn't change. Until then, delivery goes directly through
pi.eventsand keeps pi's error handling (each failing listener is logged separately). An extension model for pi-schematic #135's policy of collecting observer errors applies only once its dispatcher exists. The internal couplings An extension model for pi-schematic #135 names (the order between handoff refusal and readonly block ontool_call, and handoff finalization clearing the notebook topic) are not part of this issue. - Proposal: spawn_telemetry — lazy, on-demand tool-usage surfacing for spawned agents #34 (spawn_telemetry). That proposal shows the orchestrating model what a child did, through a query tool. This one gives other extensions lifecycle facts and never enters the model's context.
spawnIdhere equals the spawntoolCallIdthat Proposal: spawn_telemetry — lazy, on-demand tool-usage surfacing for spawned agents #34 uses as its key. - fix(spawn)!: report child usage and return failures as error results #92 and feat(usage): add one spend ledger and attribute live child spend #104 (spawn usage, spend ledger). Spend has one source: the spawn result's
usage, and the ledger once feat(usage): add one spend ledger and attribute live child spend #104 lands. No event here carries token or cost totals. - feat(spawn): retry routed model-group spawns from the remaining pool #118 (retry a routed spawn from the remaining pool). One spawn can then create several child sessions, so spawn has separate attempt and invocation events.
- chore(deps)!: require Pi 1.2.0 and make the LF contract single-source #103 (Pi 1.0.4). The best-effort cases below depend on how pi's event bus behaves on the host this targets.
- Readonly toggled on during a spawn does not restrict the running child #65, bug: notebook topic does not follow the session branch (pages do) #68, Readonly prompt-template toggle stays queued when its input starts no run, and a later run consumes it #73. These are known readonly and topic behaviours. The events report what schematic actually did, so they also help diagnose these issues.
Design principles
-
Content-free by construction. Payloads hold only these:
- numbers
- booleans
- closed enums
- opaque ids (UUIDs, tool-call ids, session ids)
- model provider/id and Model Group names. These are operator configuration and are already public in
details.route.
Error messages are never emitted.
-
Fire-and-forget. Emitting never throws, never awaits a listener, and never changes agent behaviour, ordering, results or notifications. All emits go through one
emitPublic(channel, payload)helper that wrapspi.events.emitintry/catch, which also covers the stale-runtime throw:pi.events.emitcallsassertActive()and throws once the runtime is invalidated by session replacement or reload (thepi.eventswrapper and runtime-invalidation code incore/extensions/loader.jsare unchanged from pi 0.99.2 through 1.5.2). pi's bus already isolates listener errors. In pi 1.4.0 it still reports them withconsole.error, which is the listener author's problem, not schematic's. -
Versioned. Every payload carries
v: 1.- Adding an optional field keeps
v: 1. - Removing or renaming a field, or changing what an enum value means, needs
v: 2.
- Adding an optional field keeps
-
One terminal event per lifecycle. Every lifecycle that has a start event ends in exactly one terminal event, which carries its duration. The only exceptions are listed under Best-effort cases.
-
No hidden context growth. Events never add messages, prompt sections or session entries.
-
One fact, one event. When two primitives meet, only one event reports the fact. For example, readonly blocking
handoffis reported as a handoff refusal, not also as a readonly block. -
Immutable payloads. pi's bus gives every listener the same object, so payloads are built fresh for each emit and
Object.freezed, nested objects such asrouteand arrays included. A listener can't change what a later listener sees.
Common fields
Every payload has these fields:
interface SchematicEventBase {
v: 1;
ts: number; // epoch ms at emit
sessionId: string | null; // the emitting (parent) session; null if unavailable
}These fields appear wherever they apply:
origin?: "parent" | "child"; // set by events that a child's tools can cause
spawnId?: string | null; // the spawn toolCallId, when origin is "child"
readonly: boolean; // readonly posture when the event happenedThe TypeScript below is only a precise way to write the payload shapes. It is not an implementation.
1. Handoff: schematic:handoff
One channel, discriminated by phase.
| Phase | Meaning | Terminal |
|---|---|---|
refused |
Blocked before the tool ran; nothing was staged | yes |
rejected |
The tool ran and rejected the request; nothing was staged | yes |
staged |
The request was accepted; opens the lifecycle | no |
completed |
The cut and the successor are on the branch | yes |
failed |
No usable cut | yes |
abandoned |
A staged handoff was dropped by /tree or /new |
yes |
interface HandoffEvent extends SchematicEventBase {
phase: "refused" | "rejected" | "staged" | "completed" | "failed" | "abandoned";
toolCallId: string;
handoffId: string | null; // set from "staged" on; equals the cut's details.handoffId
trigger: "model" | "requested"; // "requested" when a required handoff request was pending
instructionSource: "human" | "model"; // "human" when a /handoff direction supplied the instruction
readonly: boolean;
refuseReason?: "not_alone" | "extra_call" | "failed_in_run" | "readonly_blocked";
rejectReason?: "already_staged" | "empty_instruction" | "usage_unavailable" | "below_threshold";
// staged and rejected
contextTokens?: number | null;
contextPercent?: number | null;
enforcementAttempts?: number; // attempts counted so far on the pending request
// staged
instructionBytes?: number; // length only
contextBytes?: number; // length only
discardRequested?: number;
notebookPages?: number;
topicSet?: boolean;
// completed
successorRan?: boolean; // false when the run ended before the successor turn
pagesKept?: number;
pagesDiscarded?: number;
discardNotPersisted?: number; // pages the cut meant to discard but that survived
// failed
failReason?: "aborted" | "turn_failed" | "result_missing" | "no_boundary" | "not_persisted" | "successor_not_persisted";
contextCut?: boolean; // true only for successor_not_persisted
requestStillPending?: boolean; // a required handoff request survives the failure
// abandoned
abandonCause?: "tree" | "new";
// terminal phases after "staged"
durationMs?: number;
}2. Required handoff requests and watchdog nudges
schematic:handoff_request
This covers the lifecycle of a required handoff, from /handoff or from a readonly topic boundary being promoted. It opens with requested or promoted and ends in exactly one of fulfilled, cancelled or cleared.
interface HandoffRequestEvent extends SchematicEventBase {
action: "requested" | "promoted" | "fulfilled" | "cancelled" | "cleared";
source: "command" | "topic_boundary";
instructionSource: "human" | "model"; // /handoff with a direction → human
eligible: boolean; // context was eligible for a handoff at this moment
enforcementAttempts: number;
maxAttempts: number;
readonly: boolean;
handoffId?: string; // fulfilled: the handoff that completed it
clearCause?: "tree" | "new"; // cleared
durationMs?: number; // fulfilled, cancelled and cleared
}cancelled means the enforcement budget ran out. cleared means /tree or /new dropped the request.
schematic:watchdog
Emitted once for each context nudge that schematic sends to the model.
interface WatchdogNudgeEvent extends SchematicEventBase {
kind: "default" | "topic_boundary" | "requested_handoff";
handoffRequiredNow: boolean; // this nudge counts toward enforcement
eligible: boolean;
contextPercent: number | null;
topicSet: boolean;
readonly: boolean;
}3. Spawn
An invocation is one spawn tool call. An attempt is one child session. There is exactly one attempt per invocation until #118 lands.
schematic:spawn_attempt_start
Emitted once per child session, after it becomes the live child.
type SpawnRoute =
| { status: "inherited" }
| { status: "routed"; group: string; provider: string; modelId: string }
| { status: "unknown-fallback"; requestedGroup: string; provider: string; modelId: string };
// the same shape as the existing details.route
interface SpawnAttemptStartEvent extends SchematicEventBase {
spawnId: string; // the spawn toolCallId
attempt: number; // 1-based
childSessionId: string | null;
route: SpawnRoute;
thinkingRequested: string;
thinkingEffective: string; // after capability clamping
constraintKeys: string[]; // registry names only, e.g. ["modalities"]
promptBytes: number; // length only
toolCount: number;
notebookPages: number; // pages listed to the child
readonly: boolean;
liveChildren: number; // parallel siblings, this one included
}schematic:spawn_end
Emitted exactly once per invocation.
interface SpawnEndEvent extends SchematicEventBase {
spawnId: string;
attempts: number; // 0 when it failed before any child existed
childSessionId: string | null; // the last attempt's child
outcome: "success" | "aborted" | "error" | "invalidated" | "rejected";
errorKind?:
| "no_model" | "constraint_invalid" | "route" | "session_create" // rejected
| "child_error" | "no_output" | "prompt" | "cleanup" | "unknown"; // error
routeErrorReason?: "empty" | "no-usable-models" | "missing-modality" | "constraint-unsatisfied";
route?: SpawnRoute; // the last attempt's route, once resolved
thinkingEffective?: string;
statsUnavailable?: boolean; // the result could not report the child's usage
resultBytes?: number; // length of the child's answer before limiting
truncated?: boolean;
durationMs: number;
}rejectedmeans the spawn failed before a child existed. The tool call throws in this case.invalidatedmeans a reset made the child stale. Today the result reports that aserror.
4. Notebook: schematic:notebook
This family covers the notebook tools, the active topic and branch rebuilds. It is emitted for tools called by the parent and by children, and origin says which.
interface NotebookEvent extends SchematicEventBase {
op: "write" | "read" | "index" | "topic_set" | "rebuilt";
origin: "parent" | "child";
spawnId: string | null;
pageHash?: string; // optional, never the page name (see Open questions)
// write
outcome?: "stored" | "rejected";
rejectReason?: "first_line_too_long" | "empty_after_truncation" | "invalidated";
overwrite?: boolean; // the page existed before
inputBytes?: number;
storedBytes?: number;
storedLines?: number;
clipped?: boolean; // the stored body was truncated
// read
found?: boolean;
bytes?: number;
readClipped?: boolean; // the page read was clipped at write time
// topic_set
topicSource?: "human" | "agent";
topicOutcome?: "set" | "unchanged" | "changed" | "refused";
boundary?: boolean; // the change opened a topic boundary
// rebuilt (after /tree or a handoff cut)
rebuildCause?: "tree" | "handoff";
// all ops
pageCount: number; // pages after the op
epoch: number; // the notebook discard epoch
}- Pages discarded by a handoff are reported in the handoff event only.
rebuiltgives the resulting page count. - Topic text and page names are never emitted.
5. Readonly mode
schematic:readonly
Emitted when the readonly posture changes, and when it is restored from the branch.
interface ReadonlyChangeEvent extends SchematicEventBase {
enabled: boolean;
previous: boolean;
source: "command" | "shortcut" | "flag" | "frontmatter" | "branch";
pendingHandoffRequest: boolean; // a required handoff was pending at the change
}branch covers rehydration on resume and /tree. An event is emitted only when the value changes, or at session start when it starts enabled.
schematic:readonly_guard
Emitted for each tool call that readonly blocks, and for each bash command it guards. That covers calls from children too, and origin says which.
interface ReadonlyGuardEvent extends SchematicEventBase {
tool: "write" | "edit" | "powershell" | "bash";
origin: "parent" | "child";
spawnId: string | null;
decision: "block" | "sandbox" | "allow";
enforcement: "os_sandbox" | "classifier_only"; // os_sandbox when sandbox-exec or bwrap is in use
sandbox?: "sandbox-exec" | "bwrap";
blockKind?: "tool" | "classifier" | "shell_launch" | "invalid_input";
}allowandsandboxare emitted only for bash.- The command text is never emitted.
- A blocked
handoffis reported asschematic:handoffrefusedwithreadonly_blocked(principle 6).
6. Model Groups and prompt frontmatter
schematic:model_groups_loaded
Emitted at session start, after Model Groups load and validation.
interface ModelGroupsLoadedEvent extends SchematicEventBase {
groupCount: number;
projectScopeEnabled: boolean;
unavailableCount: number;
overrideCount: number;
emptyModalityCount: number;
staleModalityOverrideCount: number;
loadIssueCount: number;
}schematic:model_groups_changed
Emitted when /model-groups saves a change.
interface ModelGroupsChangedEvent extends SchematicEventBase {
scope: "global" | "project"; // the scope after the change
change: "created" | "updated" | "renamed" | "moved" | "deleted";
fromScope?: "global" | "project"; // moved
memberCount?: number; // the group's members after the change
groupCount: number; // effective groups after the change
}schematic:frontmatter
Emitted when a skill or prompt's frontmatter is applied or refused. Spawn routing is reported only by the spawn events.
interface FrontmatterEvent extends SchematicEventBase {
kind: "skill" | "prompt";
fields: Array<"model" | "model-group" | "thinking" | "readonly">;
outcome: "applied" | "blocked_streaming" | "selection_failed" | "invalid" | "ignored_headless";
route?: {
status: "routed" | "explicit-model" | "error";
group?: string;
provider?: string;
modelId?: string;
thinking?: string;
};
routeErrorReason?: "empty" | "no-usable-models" | "missing-modality" | "constraint-unsatisfied" | "set_model_failed";
}The skill or prompt name is not emitted, because it is user-authored.
Lifecycle guarantees
- Joins.
handoffIdjoins handoff events to the cut and the successor entry.spawnIdjoins spawn events, child-origin notebook events and child-origin readonly guard events to the spawn tool call.childSessionIdlets a consumer that also runs inside the child dedupe againstspawn_end.
/tree. It drops a staged handoff (abandoned, causetree) and a pending request (cleared). It then rebuilds the notebook (rebuilt) and restores readonly (schematic:readonlywith sourcebranch, if the value changes)./new. It does everything/treedoes, with causenew. Live children end asspawn_endwith outcomeinvalidated.- Children. Children cannot spawn or hand off, so the depth is always 1. Events caused by a child's notebook and readonly guard are emitted by the parent's schematic, on the parent's bus.
Best-effort cases
- Stale runtime. An event emitted after its session was replaced may be dropped if pi rejects it. A consumer should treat an unmatched start event (
staged,requested/promoted,spawn_attempt_start) as abandoned when it sees its ownsession_start. - Process exit. If the process exits mid-lifecycle, no terminal event is emitted.
- Slow listeners. A slow listener must not delay schematic. Listeners must be cheap and defer I/O.
emitis synchronous, so a listener's code up to its firstawaitruns inside schematic's call.
Backward compatibility
The change is purely additive. Tool names, parameter schemas, result text, details shapes, renderers, prompt sections, session entries, notifications and compaction summaries do not change. Rendered output stays byte-identical. With no listeners, the overhead is negligible, and there are no new dependencies.
Acceptance criteria
- Every lifecycle above produces its start event and exactly one terminal event:
- a handoff in each phase and reason
- a required request ending in each of
fulfilled,cancelledandcleared - a spawn in each outcome, including failures before a child exists (
attempts: 0)
- Each refusal, rejection and failure reason listed above can be produced and is reported with its code.
- Child notebook and readonly guard events carry
origin: "child"and the rightspawnId. - Readonly blocking a handoff produces only the handoff event.
- Privacy guard. Plant unique sentinel strings in every user-content input: instruction, context, page names and bodies, topic, spawn prompt, child output, bash commands, skill and prompt names. No sentinel appears in any payload.
- A listener that throws, an emit that throws, and a listener that tries to change the payload all leave tool results, state, notifications and other listeners' payloads unchanged.
- Where An extension model for pi-schematic #135 maps a matching internal event, the public event is emitted on the same core path after that moment's internal reactions, so moving the emits behind a dispatcher later doesn't change payloads or ordering. Events with no internal counterpart (for example
staged, notebookread/index, Model Groups) are emitted at the lifecycle point this issue specifies. - All existing tests and render snapshots pass unchanged.
docs/architecture.mddocuments the contract, the guarantees and the best-effort cases, andCHANGELOG.mdgets an Added entry.
Open questions for maintainers
- Phasing. Should handoff and spawn land first as v1, with the other families as follow-ups that keep
v: 1? Or should all families land at once? - Channels. One channel per family with a discriminator, as proposed here, or one channel per event?
- Page identity. Should notebook events carry
pageHash? Options:- An unsalted hash allows cross-session joins, but a guessable name can be recovered.
- A per-session salt prevents that, but removes cross-session joins.
- No hash at all.
- Readonly guard volume. Should
allowandsandboxdecisions for bash be emitted, or only blocks? - Exported types. Should the package export the event payload types, so that consumers don't copy them?
- Retries (feat(spawn): retry routed model-group spawns from the remaining pool #118). Is
spawn_attempt_startplusattemptsenough, or shouldspawn_endlist each attempt's route and outcome? - Host version. Should this target Pi 1.0.4 (chore(deps)!: require Pi 1.2.0 and make the LF contract single-source #103)? pi's
core/event-bus.js, and thepi.eventswrapper and runtime invalidation incore/extensions/loader.js, are unchanged from 0.99.2 through 1.5.2 (the latest release):emitis a synchronousEventEmitter.emit, andonwraps each listener in an asynctry/catchthat logs withconsole.error.
Activity
SpiGAndromeda commentedon Nov 7, 2026
Before we settle the event contract here, we'd like to agree on an extension model for schematic in general: #135.
This issue might end up as one part of that model. #135 proposes a dispatcher owned by schematic, where events carry process data by reference and listeners, schematic's own primitives included, may change it. The read-only lifecycle events proposed here could be a notification layer next to that dispatcher, or listeners on it (question 4 in #135). The channel layout, the phasing and what the payloads may carry depend on that answer, so we'd like to pause this issue until #135 is settled. It isn't replaced.
Your input in #135 is welcome, especially on how the lifecycle events here fit the model.
grzegorznowak commentedon Nov 7, 2026
Thanks @imkartikeyhpandey , I think this is good next step indeed, and it addresses some of the problems already in front of us.
As much as I appreciate the architectural soundness of #135 I think #119 is the more concrete step we can take in anticipation of having
workflowsin their final shape and form built - as that would most probably also affect the general design of the system.(and then we might circle back to #135 ofc)