Repository navigation
An extension model for pi-schematic #135
Replies: 3 comments
|
This is the model applied to the current code: per primitive, what stays in the core path, which events it dispatches, and which existing code moves onto them as a listener. Every event below has a listener in the code today. Moments that become events once a listener appears: event-candidates.md. Roles: changes (writes a mutable field of the event), vetoes (blocks the process), reacts (updates its own state or the UI). All events are internal. flowchart LR
subgraph core [Core paths]
HS[handoff settlement]
HR[handoff request lifecycle]
WN[watchdog nudge]
SB[spawn child build]
NT[notebook topic set]
NW[notebook write]
RC[readonly toggle, frontmatter, rehydrate]
TC[pi tool_call]
end
subgraph events [Events]
E1([handoff.settling])
E2([handoff.requested])
E3([handoff.request.ended])
E4([watchdog.nudge])
E5([spawn.tools])
E6([spawn.prompt])
E10([notebook.topic.changed])
E7([notebook.saved])
E8([readonly.changed])
E9([tool.call])
end
subgraph owners [Listeners, by owning module]
RO[readonly]
NB[notebook]
HO[handoff]
WD[watchdog]
MG[model groups]
UI[TUI indicators]
end
HS --> E1
HR --> E2
HR --> E3
WN --> E4
SB --> E5
SB --> E6
NT --> E10
NW --> E7
RC --> E8
TC --> E9
E1 --> NB
E1 --> RO
E2 --> RO
E2 --> HO
E3 --> WD
E3 --> RO
E4 --> RO
E5 --> RO
E6 --> RO
E6 --> NB
E6 --> MG
E10 --> RO
E7 --> UI
E8 --> HO
E8 --> UI
E9 --> HO
E9 --> RO
Handoff
Stays core: call admission and refusals per message ( stateDiagram-v2
[*] --> Requested: /handoff or readonly boundary promotion
note right of Requested: handoff.requested
Requested --> Staged: handoff tool call
[*] --> Staged: handoff tool call without a request
Requested --> [*]: budget exhausted or /tree, /new
Staged --> Submitted: turn_end writes the cut drafts
Staged --> Failed: turn declined or aborted, or no cut
Submitted --> Completed: cut and successor on the branch
Submitted --> LostSuccessor: cut on the branch, successor missing
Submitted --> Failed: cut not persisted
Staged --> [*]: /tree or /new
Submitted --> [*]: /tree or /new
note right of Completed: handoff.settling, and a pending request ends with handoff.request.ended
note right of LostSuccessor: handoff.settling, and a pending request ends with handoff.request.ended
Completed --> [*]
LostSuccessor --> [*]
Failed --> Requested: a pending request stays open unless its budget is exhausted
Failed --> [*]: no pending request
Handoff request and watchdog
Stays core: the band throttle, the 30k-token eligibility floor, the delivery mark Spawn
Stays core: parameter and constraint validation, routing ( Notebook
Stays core: the write path in Readonly
Stays core: the readonly flag, its nudge flag and its flowchart TD
A[pi tool_call: toolName, input] --> B{band 1, handoff:<br>refuse this handoff call?}
B -- refused --> X[call blocked, batch terminated]
B -- no --> C{band 2, readonly:<br>block write, edit, powershell,<br>or handoff without a request?}
C -- blocked --> Y[call blocked]
C -- no --> D{band 3, readonly bash guard:<br>allow, block or sandbox}
D -- block --> Y
D -- sandbox --> R[input.command rewritten in place]
D -- allow --> S
R --> S[dispatch ends unblocked;<br>for a sandboxed call, core records its call id]
S --> E[pi runs the tool with the same input object]
Model groups and frontmatterNo events. Route resolution, member selection, the thinking clamp, the config store with its corrupt-file backup, the Session wiringThe extension factory in Contract rules the mapping depends onThe pi host behaviour and the concurrency hazards behind these rules: constraints.md.
Order of moves
|
|
hey @SpiGAndromeda ! The proposal is sound and the architecture is generally well thought out, but it builds a mechanism to solve a problem that doesn't exist yet — or isn't even on the cards. The workflow mechanism, once built, will most probably become the source and centre of the orbit of any future architecture, should we decide to go for more abstraction. So I'd wait for that architecture to take shape, and only then circle back to this design to see whether it still fits going forward. The idea of a more powerful own-event bus is a genuinely nice touch, but it would add a secondary event bus to the project — on top of pi's own — without a clear problem it needs to solve. The two current defects you cite are real but narrow: the registration-order race between readonly blocking and handoff refusal on So I'd put the question back: did you mean to loosen the coupling between the components, or to make schematic more extensible for future consumers — or a combination of both? The answer changes the shape of the mechanism materially. An internal, private mediator is a very different thing from a public extension platform, and the latter is the part I'd hold off on until we have a named consumer and its requirements in front of us. |
|
Thanks @SpiGAndromeda, and @grzegorznowak for the framing question. I think it decides how these two fit together, so here's my take from the #119 side. Split the two goals grzegorz names:
Question 7 (pi versions). I compared every release from 0.99.2 to 1.5.2 (latest). Proposed order:
That way #119 isn't blocked, and this design stays ready for when the internal couplings or a named consumer call for it. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
pi-schematic has no extension points. Another extension can't react to what schematic does, and it can't adjust it. Our own primitives have the same problem from the inside: they reach into each other's state directly. Readonly mode blocks the
handofftool from its owntool_callhandler, and handoff finalization clears the active notebook topic itself.#119 proposes versioned, read-only lifecycle events on pi's event bus. Before we fix a contract like that, we want to agree on how schematic is extended in general, so that read-only events, events that change behaviour, and our own internal coupling all follow one model.
The first comment maps this model onto the current code: what stays core, which events exist, and which code attaches to them.
The pattern
An event carries the data of a process by reference. Listeners may change it. The emitting path keeps using the same object after dispatch and doesn't check whether anything changed. That is deliberate: the event's contract says what a listener may change, and the code is written so that every allowed change is safe. There are no runtime guards on event data.
Schematic dogfoods the API: its own primitives use the same events an outside extension would. Readonly blocking a handoff would then be a readonly listener on a handoff event, not a check inside handoff code.
This needs a clear split between core process paths, which own the data and emit events, and side paths, which listen and either change the data or only react. Symfony's EventDispatcher is a familiar example of this pattern.
sequenceDiagram participant Core as Core path (e.g. handoff staging) participant D as Schematic dispatcher participant L as Listeners (schematic's own primitives and other extensions) Note over D,L: session_start D->>L: dispatcher, via a one-time handshake on pi.events L->>D: register(listener, priority) Note over Core,L: later, during a run Core->>D: dispatch(event) loop each listener, highest priority first D->>L: the same event object L-->>D: may change it end D-->>Core: returns Note over Core: continues with the same event objectWhy
pi.eventsalone doesn't fitpi's inter-extension bus (
core/event-bus.jsin pi 0.99.2) is a notification channel, not a dispatcher for events that listeners change.pi.events(pi 0.99.2)awaitconsole.error; the emitter never sees thememitis a synchronousEventEmitter.emitand returns nothing; listeners run inside an async wrapperemitthrows after session replacement or reloadsession_startProposed model
/new, resume, reload), so each runtime gets a new dispatcher. Each module registers its own listeners fromindex.ts, not from the state, so core state doesn't import its consumers.area.moment(for examplehandoff.settling). An event is added only when a real listener moves onto it.tool.callpasses the tool input by reference, because the readonly sandbox rewrites the bash command in place.tool.call, so the order between modules never depends on registration order. Registration order only breaks ties within a band.session_start, schematic emits its dispatcher on the pi bus. By then every extension is loaded. Listeners register on the dispatcher, and the bus isn't used for delivery./newor resume there is a new runtime and a new bus. After a reload the bus stays, but pi drops the old runtime's subscriptions. Extensions register again on the nextsession_start.Phasing
handoff.settling, a sync event dispatched when a handoff settles, with the notebook topic clear and the readonly nudge arm as listeners owned by their modules.readonly.changed, handoff request end, handoff request and staging, the watchdog nudge, andtool.calllast.Open questions
causewhen wrapping". Within those rules, does a listener error propagate into the core path (it fails like schematic's own code would), or is the listener isolated, its failure reported and the dispatch continued? If several listeners fail in one dispatch, are their failures reported together? Is the choice per event?tool_callandcontexthooks already show tool arguments and messages to any extension.session_starthandshake on the pi bus the right way for an extension to get the dispatcher, or is there a better one?Related: #119, #25, #110, #103, #133.
All reactions