Skip to content

feat: emit versioned, content-free schematic:* lifecycle events on pi.events #119

Open

Description

@imkartikeyhpandey

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 /tree or /new leave 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 details shapes 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 in async, runs them in registration order and sends their errors to console.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

Design principles

  1. 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.

  2. 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 wraps pi.events.emit in try/catch, which also covers the stale-runtime throw: pi.events.emit calls assertActive() and throws once the runtime is invalidated by session replacement or reload (the pi.events wrapper and runtime-invalidation code in core/extensions/loader.js are 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 with console.error, which is the listener author's problem, not schematic's.

  3. 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.
  4. 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.

  5. No hidden context growth. Events never add messages, prompt sections or session entries.

  6. One fact, one event. When two primitives meet, only one event reports the fact. For example, readonly blocking handoff is reported as a handoff refusal, not also as a readonly block.

  7. 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 as route and 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 happened

The 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;
}
  • rejected means the spawn failed before a child existed. The tool call throws in this case.
  • invalidated means a reset made the child stale. Today the result reports that as error.

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. rebuilt gives 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";
}
  • allow and sandbox are emitted only for bash.
  • The command text is never emitted.
  • A blocked handoff is reported as schematic:handoff refused with readonly_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.
    • handoffId joins handoff events to the cut and the successor entry.
    • spawnId joins spawn events, child-origin notebook events and child-origin readonly guard events to the spawn tool call.
    • childSessionId lets a consumer that also runs inside the child dedupe against spawn_end.
  • /tree. It drops a staged handoff (abandoned, cause tree) and a pending request (cleared). It then rebuilds the notebook (rebuilt) and restores readonly (schematic:readonly with source branch, if the value changes).
  • /new. It does everything /tree does, with cause new. Live children end as spawn_end with outcome invalidated.
  • 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 own session_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. emit is synchronous, so a listener's code up to its first await runs 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, cancelled and cleared
    • 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 right spawnId.
  • 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, notebook read/index, Model Groups) are emitted at the lifecycle point this issue specifies.
  • All existing tests and render snapshots pass unchanged.
  • docs/architecture.md documents the contract, the guarantees and the best-effort cases, and CHANGELOG.md gets an Added entry.

Open questions for maintainers

  1. 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?
  2. Channels. One channel per family with a discriminator, as proposed here, or one channel per event?
  3. 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.
  4. Readonly guard volume. Should allow and sandbox decisions for bash be emitted, or only blocks?
  5. Exported types. Should the package export the event payload types, so that consumers don't copy them?
  6. Retries (feat(spawn): retry routed model-group spawns from the remaining pool #118). Is spawn_attempt_start plus attempts enough, or should spawn_end list each attempt's route and outcome?
  7. 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 the pi.events wrapper and runtime invalidation in core/extensions/loader.js, are unchanged from 0.99.2 through 1.5.2 (the latest release): emit is a synchronous EventEmitter.emit, and on wraps each listener in an async try/catch that logs with console.error.

Activity

  1. SpiGAndromeda commented on Nov 7, 2026

    @SpiGAndromeda
    Collaborator

    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.

  2. grzegorznowak commented on Nov 7, 2026

    @grzegorznowak
    Collaborator

    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 workflows in 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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

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