@astrosheep/square 0.3.106 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/activity-feed.js +1 -1
- package/dist/artifact-store.d.ts +41 -0
- package/dist/artifact-store.js +272 -0
- package/dist/artifact.d.ts +6 -12
- package/dist/artifact.js +43 -344
- package/dist/attention-presentation.d.ts +13 -7
- package/dist/attention-presentation.js +29 -68
- package/dist/boundary-presentation.d.ts +3 -16
- package/dist/boundary-presentation.js +29 -109
- package/dist/card-presentation.d.ts +1 -0
- package/dist/card-presentation.js +2 -0
- package/dist/catch-decisions.d.ts +2 -2
- package/dist/catch-decisions.js +7 -3
- package/dist/catch-selection.d.ts +8 -0
- package/dist/catch-selection.js +5 -0
- package/dist/claude-delivery.d.ts +14 -12
- package/dist/claude-delivery.js +42 -142
- package/dist/claude-mcp-context.js +2 -2
- package/dist/claude-mod.js +28 -140
- package/dist/claude-transport.d.ts +5 -0
- package/dist/claude-transport.js +34 -0
- package/dist/cli/context.d.ts +2 -2
- package/dist/cli/context.js +7 -10
- package/dist/cli/maintenance-commands.d.ts +0 -4
- package/dist/cli/maintenance-commands.js +2 -29
- package/dist/cli/observation-commands.d.ts +2 -0
- package/dist/cli/observation-commands.js +12 -2
- package/dist/cli/program.js +1 -1
- package/dist/cli/registry.js +4 -3
- package/dist/codex-address.d.ts +2 -2
- package/dist/codex-boundary-state.d.ts +1 -5
- package/dist/codex-boundary-state.js +0 -4
- package/dist/codex-hook.d.ts +7 -10
- package/dist/codex-hook.js +69 -33
- package/dist/codex-queue.d.ts +10 -11
- package/dist/codex-queue.js +32 -34
- package/dist/codex-watch.d.ts +2 -0
- package/dist/codex-watch.js +100 -0
- package/dist/decisions.js +3 -3
- package/dist/delivery-deferral.d.ts +1 -19
- package/dist/delivery-deferral.js +1 -29
- package/dist/delivery-frame.d.ts +7 -0
- package/dist/delivery-frame.js +11 -0
- package/dist/delivery-ledger-sqlite.d.ts +97 -0
- package/dist/delivery-ledger-sqlite.js +496 -0
- package/dist/delivery-ledger.d.ts +196 -0
- package/dist/delivery-ledger.js +268 -0
- package/dist/delivery-lifetime.d.ts +6 -0
- package/dist/delivery-lifetime.js +45 -0
- package/dist/harness-links.js +61 -7
- package/dist/harness.js +12 -17
- package/dist/help.js +3 -6
- package/dist/http-delivery.d.ts +5 -9
- package/dist/http-delivery.js +20 -79
- package/dist/inbox.d.ts +6 -57
- package/dist/inbox.js +24 -380
- package/dist/index.d.ts +7 -4
- package/dist/index.js +5 -2
- package/dist/mcp.d.ts +2 -1
- package/dist/mcp.js +40 -70
- package/dist/message.d.ts +7 -0
- package/dist/message.js +23 -0
- package/dist/model.d.ts +15 -91
- package/dist/model.js +2 -140
- package/dist/neutral.d.ts +72 -0
- package/dist/neutral.js +27 -0
- package/dist/notifications.d.ts +24 -26
- package/dist/notifications.js +39 -143
- package/dist/operation-control.d.ts +4 -0
- package/dist/operation-control.js +20 -0
- package/dist/operation-presentation.d.ts +1 -2
- package/dist/operation-presentation.js +1 -7
- package/dist/owner.d.ts +2 -2
- package/dist/owner.js +1 -1
- package/dist/packages/agent-delivery/src/claude-native.d.ts +2 -0
- package/dist/packages/agent-delivery/src/claude-native.js +5 -0
- package/dist/packages/agent-delivery/src/codex-boundary.d.ts +11 -6
- package/dist/packages/agent-delivery/src/codex-boundary.js +31 -40
- package/dist/packages/agent-delivery/src/codex-hook.d.ts +17 -12
- package/dist/packages/agent-delivery/src/codex-hook.js +26 -39
- package/dist/packages/agent-delivery/src/codex.d.ts +3 -0
- package/dist/packages/agent-delivery/src/codex.js +41 -4
- package/dist/packages/agent-delivery/src/index.d.ts +3 -1
- package/dist/packages/agent-delivery/src/index.js +1 -1
- package/dist/packages/agent-delivery/src/paseo.js +11 -2
- package/dist/packages/agent-delivery/src/types.d.ts +1 -0
- package/dist/paseo-delivery.d.ts +5 -5
- package/dist/paseo-delivery.js +19 -99
- package/dist/paseo.d.ts +1 -1
- package/dist/paseo.js +1 -1
- package/dist/plugins/opencode/index.d.ts +5 -3
- package/dist/plugins/opencode/index.js +99 -21
- package/dist/plugins/opencode-shared/delivery.d.ts +23 -0
- package/dist/plugins/opencode-shared/delivery.js +109 -0
- package/dist/plugins/opencode-v1/index.d.ts +28 -0
- package/dist/plugins/opencode-v1/index.js +41 -0
- package/dist/plugins/opencode-v1/runtime.d.ts +56 -0
- package/dist/plugins/opencode-v1/runtime.js +152 -0
- package/dist/plugins/opencode-v1/transport.d.ts +13 -0
- package/dist/plugins/opencode-v1/transport.js +50 -0
- package/dist/plugins/paseo/shared/card-presentation.d.ts +10 -0
- package/dist/plugins/paseo/shared/card-presentation.js +7 -0
- package/dist/ports.d.ts +33 -214
- package/dist/presentation.d.ts +5 -5
- package/dist/presentation.js +1 -0
- package/dist/runtime.js +2 -2
- package/dist/search.js +1 -1
- package/dist/session-lifecycle.d.ts +8 -7
- package/dist/session-lifecycle.js +40 -42
- package/dist/sqlite-framing.d.ts +8 -0
- package/dist/sqlite-framing.js +31 -0
- package/dist/sqlite-square.d.ts +16 -26
- package/dist/sqlite-square.js +199 -262
- package/dist/sqlite-values.d.ts +21 -0
- package/dist/sqlite-values.js +78 -0
- package/dist/square-api.d.ts +1 -1
- package/dist/square-api.js +5 -8
- package/dist/square-core.d.ts +0 -1
- package/dist/square-domain.d.ts +12 -10
- package/dist/square-domain.js +105 -223
- package/dist/square-facade.d.ts +25 -76
- package/dist/square-location.d.ts +6 -1
- package/dist/square-location.js +1 -1
- package/dist/square-post.d.ts +53 -0
- package/dist/square-post.js +4 -0
- package/dist/square-posting.d.ts +13 -0
- package/dist/square-posting.js +174 -0
- package/dist/square-producer-sqlite.d.ts +11 -0
- package/dist/square-producer-sqlite.js +210 -0
- package/dist/square-receive.d.ts +2 -3
- package/dist/square-sqlite.d.ts +33 -42
- package/dist/square-sqlite.js +236 -768
- package/dist/square-tools.d.ts +8 -0
- package/dist/square-tools.js +39 -0
- package/dist/square-values.d.ts +27 -0
- package/dist/square-values.js +90 -0
- package/dist/views.d.ts +6 -6
- package/dist/views.js +14 -9
- package/dist/wake-sink.d.ts +4 -11
- package/dist/wake-sink.js +8 -32
- package/dist/wake-transports.d.ts +4 -0
- package/dist/wake-transports.js +11 -0
- package/examples/symmetric-domains.mjs +29 -249
- package/guides/change-waits.md +13 -53
- package/guides/claude-native.md +19 -172
- package/guides/codex-delivery.md +55 -78
- package/guides/delivery-primitives.md +48 -207
- package/guides/operation-cancellation.md +2 -5
- package/guides/participant-ownership.md +25 -89
- package/guides/pi-native-delivery.md +19 -56
- package/guides/pi-tools.md +6 -8
- package/guides/row-runtime-delivery-evidence.md +2 -0
- package/guides/row-storage-design.md +19 -44
- package/guides/square-api.md +113 -538
- package/package.json +8 -8
- package/plugins/claude/.claude-plugin/plugin.json +1 -1
- package/plugins/claude/hooks/hooks.json +1 -1
- package/plugins/claude/{hooks/register.js → mods/square.js} +4 -7
- package/plugins/claude/types.d.ts +1 -1
- package/plugins/codex/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/hooks/hooks.json +11 -23
- package/plugins/opencode/index.ts +91 -23
- package/plugins/opencode-shared/delivery.ts +91 -0
- package/plugins/opencode-v1/index.ts +36 -0
- package/plugins/opencode-v1/runtime.ts +134 -0
- package/plugins/opencode-v1/transport.ts +41 -0
- package/plugins/paseo/OVERVIEW.md +5 -5
- package/plugins/paseo/README.md +7 -6
- package/plugins/paseo/client/markdown.tsx +5 -5
- package/plugins/paseo/client/square-message.tsx +28 -24
- package/plugins/paseo/client/transform.ts +8 -5
- package/plugins/paseo/shared/card-presentation.ts +16 -0
- package/plugins/paseo/shared/message.ts +6 -11
- package/plugins/pi/square-pi.js +167 -451
- package/dist/channel.d.ts +0 -74
- package/dist/channel.js +0 -92
- package/dist/claude-delivery-status.d.ts +0 -13
- package/dist/claude-delivery-status.js +0 -46
- package/dist/cmd/notify-once.d.ts +0 -2
- package/dist/cmd/notify-once.js +0 -29
- package/dist/delivery-attempts.d.ts +0 -52
- package/dist/delivery-attempts.js +0 -73
- package/dist/delivery-effects.d.ts +0 -139
- package/dist/delivery-effects.js +0 -163
- package/dist/delivery-health.d.ts +0 -51
- package/dist/delivery-health.js +0 -173
- package/dist/delivery-operations.d.ts +0 -9
- package/dist/delivery-operations.js +0 -168
- package/dist/delivery-primitives.d.ts +0 -5
- package/dist/delivery-primitives.js +0 -3
- package/dist/delivery.d.ts +0 -45
- package/dist/delivery.js +0 -106
- package/dist/plugins/opencode/delivery.d.ts +0 -19
- package/dist/plugins/opencode/delivery.js +0 -238
- package/dist/presentation-operations.d.ts +0 -18
- package/dist/presentation-operations.js +0 -86
- package/dist/square-index.d.ts +0 -16
- package/dist/square-index.js +0 -106
- package/dist/square-legacy-framing.d.ts +0 -11
- package/dist/square-legacy-framing.js +0 -64
- package/dist/square-migration-host-ledger.d.ts +0 -26
- package/dist/square-migration-host-ledger.js +0 -169
- package/dist/square-migration.d.ts +0 -30
- package/dist/square-migration.js +0 -599
- package/guides/migration.md +0 -156
- package/plugins/opencode/delivery.ts +0 -211
package/guides/change-waits.md
CHANGED
|
@@ -1,57 +1,17 @@
|
|
|
1
1
|
# Waiting for changes
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Filesystem notifications are hints, not activity delivery or receipts. Artifact revision observation
|
|
4
|
+
and reconciliation let catch and stream reconsider changes even if a filesystem event is missed;
|
|
5
|
+
subscribers retain independent cancellation and deadlines. Throttling waits for its eligibility time.
|
|
6
|
+
There is no discovery index and no daemon or per-message timer.
|
|
5
7
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
even when notifications are missing. Missing directories, unsupported watches, watcher failures
|
|
11
|
-
and directory replacement retain that fallback. Latency is not a hard guarantee: a missed hint
|
|
12
|
-
may wait for reconciliation, scheduling and lock contention.
|
|
13
|
-
- Conversation revision controls the pending-content cache. Delivery revision separately invalidates
|
|
14
|
-
eligibility, including delivery evidence, cancellation and deferral writes. Projections resolve
|
|
15
|
-
current typed seats and selected bodies in one coherent artifact read; they never grant authority
|
|
16
|
-
from an index entry or a cached eligibility decision. No sidecar, broker or second delivery store
|
|
17
|
-
is introduced. An unreadable candidate cannot authorize cached content.
|
|
18
|
-
- Each active session pending observer subscribes before selecting current candidates and facts,
|
|
19
|
-
including when no seat is yet discoverable. Index publication can wake discovery without an
|
|
20
|
-
artifact write. A failed injection waits for substantive change; its own failed evidence write
|
|
21
|
-
does not cause a retry loop.
|
|
22
|
-
- Deferral create/renew/release and opportunistic pruning change delivery revision, not conversation
|
|
23
|
-
activity. Release rechecks eligibility without a new message. Expiry needs no synthetic write:
|
|
24
|
-
the observer includes the earliest relevant matching live deferral expiry in its existing wait
|
|
25
|
-
deadline, alongside catch-lease expiry/staleness. Overlapping leases remain OR; an early expiry
|
|
26
|
-
rechecks the remaining live leases. Renewal changes that deadline without self-triggered delivery.
|
|
27
|
-
- There is no new daemon or detached per-message timer. A one-shot producer skips deferred work and
|
|
28
|
-
returns promptly. An existing active delivery observer will reconsider release/expiry; absent an
|
|
29
|
-
observer, pending work waits for the next normal delivery opportunity. A lease does not create a
|
|
30
|
-
process that was not already running.
|
|
31
|
-
- Blocking catch waits for conversation revision or its heartbeat/quiet deadline. An active catch keeps
|
|
32
|
-
its single lease alive and pauses quiet expiry. Core catch and streams use the same storage change
|
|
33
|
-
detector. Throttling waits for its eligibility time.
|
|
34
|
-
- Deferrals are independent of catch filters, presentation claims, full-delivery seen receipts,
|
|
35
|
-
clipped previews and session-local cancellation. Sharing storage detection does not share session
|
|
36
|
-
delivery state. Cancellation never creates a receipt or removes archive history. A deferral cannot
|
|
37
|
-
recall a send already past its final freshness check.
|
|
8
|
+
ACK and export ownership serialize with insertion in producer storage; exact future ACK prevents a
|
|
9
|
+
matching late insertion from bypassing it, but cannot recall an already owned export. Cancellation
|
|
10
|
+
does not erase history or imply that activity was read. Proactive delivery suppression belongs in the
|
|
11
|
+
host delivery ledger; see [delivery-primitives.md](delivery-primitives.md).
|
|
38
12
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
npm test
|
|
45
|
-
npm run test:cli-process
|
|
46
|
-
node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode poll200
|
|
47
|
-
node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 100 --mode events
|
|
48
|
-
node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session
|
|
49
|
-
node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
The benchmark creates disposable synthetic history. Process-local sharing does not deduplicate
|
|
53
|
-
monitors across processes. Timings measure committed-write-to-projection latency, not native
|
|
54
|
-
message landing, and discovery deadlines are probe bounds rather than an SLA. Historical benchmark
|
|
55
|
-
evidence may describe older HostLedger implementations; it is not current custody authority.
|
|
56
|
-
A long-running extension must reload upgraded code before using the new artifact format; this
|
|
57
|
-
delivery does not install or restart one.
|
|
13
|
+
At the next normal privileged posting opportunity, already-posted eligible keys can be dispatched
|
|
14
|
+
again without reinserting cards or resetting producer state. Ledger attempts exclude accepted, unknown
|
|
15
|
+
and presented work; only never-attempted or known-unsent failed/released work can proceed. No new
|
|
16
|
+
scheduler or Stop watcher is needed. See [square-api.md](square-api.md) for bounded recovery of
|
|
17
|
+
abandoned export ownership.
|
package/guides/claude-native.md
CHANGED
|
@@ -1,174 +1,21 @@
|
|
|
1
1
|
# Claude native inbox
|
|
2
2
|
|
|
3
|
-
Square's Claude plugin is a mod, not a shell-hook injector. Its
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
not
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
`square harness doctor claude` explains installation and these limits.
|
|
23
|
-
`square harness doctor delivery` derives current routes/evidence without sending.
|
|
24
|
-
An absent/broken endpoint is unavailable; it does not consume Square activity.
|
|
25
|
-
|
|
26
|
-
## Native-first routing and policy holds
|
|
27
|
-
|
|
28
|
-
Native delivery is preferred, including under Paseo. CLI and call-local MCP Codex
|
|
29
|
-
joins register the native queue for their thread. Claude and OpenCode receivers
|
|
30
|
-
register their native wake addresses only through their loaded integrations. An
|
|
31
|
-
ordinary reconnect or reattachment cannot replace a current native address with a
|
|
32
|
-
generic Paseo proposal. Addresses belong to the artifact seat generation, not an
|
|
33
|
-
expiring routes table: explicit receiver withdrawal permits fallback, and a new
|
|
34
|
-
seat generation cannot inherit the previous generation's native registration.
|
|
35
|
-
Participant expressions do not publish replacement addresses.
|
|
36
|
-
|
|
37
|
-
This is route preference, not permission to bypass receiver policy. Claude can
|
|
38
|
-
legitimately hold an unsolicited peer message with `no-mode-asserted`, especially
|
|
39
|
-
under `bypassPermissions`. Square neither asserts a made-up permission mode nor
|
|
40
|
-
changes `crossSessionInbound`. After bytes may have been sent, `unknown` remains
|
|
41
|
-
attention-wide and prevents another send through Paseo, even if routes later change.
|
|
42
|
-
|
|
43
|
-
Each native send persists a message ID before writing; the wire `uuid` and
|
|
44
|
-
`msg_id` carry that ID. Square records no native custody telemetry from Paseo:
|
|
45
|
-
official Paseo exposes no delivery-status lifecycle event, so a held message stays
|
|
46
|
-
`unknown` with `native_admission_unconfirmed`. Recording a `held`, `released` or
|
|
47
|
-
`dropped` observation would require a Paseo-provided event; Square does not patch
|
|
48
|
-
Paseo to invent one. Even when such an observation exists, the event ID is
|
|
49
|
-
deduplicated and the native reason and observation time remain diagnostic only.
|
|
50
|
-
Neither a release nor a drop is a queue receipt, proof of consumption or retry
|
|
51
|
-
authorization.
|
|
52
|
-
|
|
53
|
-
`square harness doctor delivery` shows native custody separately from pending
|
|
54
|
-
attention for current seat generations, including after the activity is seen. Paseo
|
|
55
|
-
presents the `peer_message_hold` state in its own timeline. Acceptance means normal
|
|
56
|
-
delivery when the receiver allows it, or a visible reason without bypass/replay when
|
|
57
|
-
policy holds it.
|
|
58
|
-
|
|
59
|
-
## MCP tools and call identity
|
|
60
|
-
|
|
61
|
-
The plugin's `.mcp.json` starts the existing Square MCP server. The mod no longer
|
|
62
|
-
registers an argv wrapper or executes participant CLI commands. MCP and Pi native
|
|
63
|
-
tools share their operation definitions and facade calls in `square-tools.ts`.
|
|
64
|
-
|
|
65
|
-
Before a bundled MCP call, the mod uses the existing `square claude-mod` helper
|
|
66
|
-
to publish `{toolUseId, sessionId, cwd, agentId?}`. It then calls `next(e)` unchanged.
|
|
67
|
-
The server correlates `_meta["claudecode/toolUseId"]` with that association: no
|
|
68
|
-
session, agent, token or other transport field is added to the model's schema or
|
|
69
|
-
arguments. Claude's native **session ID plus child flag** semantics are preserved;
|
|
70
|
-
the child loop's `agentId` is retained for attribution, not substituted as a session ID.
|
|
71
|
-
Calls use the live cwd and session even if the MCP process started earlier.
|
|
72
|
-
|
|
73
|
-
`SQUARE_CLAUDE_MCP_CONTEXT=1` is set only by the bundled MCP configuration. That
|
|
74
|
-
endpoint fails closed if an association is missing or expired; it never silently
|
|
75
|
-
uses the startup parent identity. Generic MCP configurations retain their existing
|
|
76
|
-
identity handling. The hook targets `mcp__plugin_square_square__*`, not unrelated
|
|
77
|
-
servers with similar operation names.
|
|
78
|
-
|
|
79
|
-
The mod owns publication and token-matched removal in `finally`; the server only
|
|
80
|
-
reads. Associations are private, transient transport files under
|
|
81
|
-
`<host-ledger-root>/claude-mcp-calls`, not Square domain state or another artifact.
|
|
82
|
-
Normal completion/errors remove them. If abrupt cancellation, unload or a crash
|
|
83
|
-
prevents cleanup, they expire after ten minutes and the next publication prunes
|
|
84
|
-
them. Expiry gates lookup, not an operation that already captured its context.
|
|
85
|
-
MCP owns operation cancellation and connection shutdown. No second execution
|
|
86
|
-
protocol, resident service or ledger schema migration is introduced.
|
|
87
|
-
|
|
88
|
-
## Membership and lifecycle
|
|
89
|
-
|
|
90
|
-
Participants join explicitly. The mod never discovers or joins a square from its
|
|
91
|
-
filename; `PUBLIC.square` has no special behavior. Existing memberships reconcile
|
|
92
|
-
on startup. Main-conversation tool completion (including failed/aborted tools) and
|
|
93
|
-
conversation start reconcile late memberships: the receiver itself publishes
|
|
94
|
-
routes; the CLI cannot infer mod capability from a socket or session environment.
|
|
95
|
-
This reconciliation injects no activity and does not poll. Its recovery sweep
|
|
96
|
-
only sends previously unsent eligible attention, never unknown/admitted attempts.
|
|
97
|
-
|
|
98
|
-
Initial activation and hot reload use `session.start`. New conversations use
|
|
99
|
-
`classic.SessionStart`: clear reads the new API coordinate; **resume's event
|
|
100
|
-
`session_id` is already the resumed coordinate while `$.session.id()` still reads
|
|
101
|
-
the ending one (observed in 2.1.295)**. The event coordinate is used at that boundary, with
|
|
102
|
-
API cwd/version/socket. Modern `session.end` detaches only its pinned `e.sessionId`
|
|
103
|
-
and captured owner/join generations, within the event budget. Late committed joins
|
|
104
|
-
are discovered at the pinned end timestamp. A process crash can omit end.
|
|
105
|
-
|
|
106
|
-
Host end is not a participant departure: no `done` lands, and membership, listens,
|
|
107
|
-
read horizon and generation remain intact. Catch ownership, deferrals and wake readiness
|
|
108
|
-
are cleared; the participant appears away and keeps accumulating unread audience without
|
|
109
|
-
proactive delivery. Before arming a receiver, start/resume discovers the exact owner's
|
|
110
|
-
standing seats through `seatsOf(owner)` and restores only detached ones with
|
|
111
|
-
`reattach(name, {owner, wakeAddress?})`. The adapter obtains that owner with
|
|
112
|
-
`harnessOwner({channel: 'claude-code', session, agent?})`. One failed seat or location does not block the
|
|
113
|
-
others. New/forked harness owners restore nothing. Neither a voluntary `done` nor a takeover is
|
|
114
|
-
revived; there is no completed-seat recovery path or timeout that turns away into done.
|
|
115
|
-
See [participant-ownership.md](participant-ownership.md).
|
|
116
|
-
|
|
117
|
-
## Body, admission, and presentation
|
|
118
|
-
|
|
119
|
-
The coordinator uses Square's canonical audience projection and bounded body
|
|
120
|
-
preview. Each notification identifies the square, receiving participant and
|
|
121
|
-
activity before its event and body. A clipped preview describes catching that
|
|
122
|
-
activity to read it in full; it never embeds shell commands or tool-call syntax.
|
|
123
|
-
Opaque text correlation resolves through bound memberships and the existing
|
|
124
|
-
attempt ledger, never a path or asserted source from incoming text.
|
|
125
|
-
|
|
126
|
-
Transport is the Node-only leaf published as `@astrosheep/agent-delivery/claude-native`,
|
|
127
|
-
sourced from `packages/agent-delivery/src/claude-native.ts`. Square imports that
|
|
128
|
-
source directly; its root package ships the compiled leaf without loading the
|
|
129
|
-
OpenCode SDK or requiring a separate agent-delivery installation. There is no
|
|
130
|
-
second socket sender. Receipt semantics (`written` is local bytes only, never
|
|
131
|
-
admission), the plain-peer use, and the standalone client API are documented in
|
|
132
|
-
the package `README.md`; the leaf accepts only target/session endpoint, text, and
|
|
133
|
-
bounded deadline/cancellation control.
|
|
134
|
-
|
|
135
|
-
`session.receive` runs before native policy; Square owns this admission gate and
|
|
136
|
-
the presentation writer, not the leaf. `await next(e)` confirms queue admission
|
|
137
|
-
only when the returned text is unchanged. Hold/refuse reject that gate;
|
|
138
|
-
consumed/rewritten results cannot confirm the original. Unknown peer messages
|
|
139
|
-
pass through. Recognized stale/cancelled deliveries can be consumed before queueing.
|
|
140
|
-
No ambiguous send is blindly retried.
|
|
141
|
-
|
|
142
|
-
The sole presentation writer observes **returned stored main user-role text**
|
|
143
|
-
after `session.append.next`. It matches the entire expected payload within
|
|
144
|
-
Claude's idle/busy peer framing. A complete preview records seen + presented;
|
|
145
|
-
a clipped one records clipped only. This means stored in model context, not
|
|
146
|
-
processed or understood. Catch/presentation races are idempotent and revalidated
|
|
147
|
-
immediately before send and inside the observation transaction.
|
|
148
|
-
|
|
149
|
-
## Cancellation and custody
|
|
150
|
-
|
|
151
|
-
Explicit plugin `turn.abort` and terminal `turn.complete(reason:'aborted')`
|
|
152
|
-
suppress the outstanding local batch without recording seen. Ordinary answer,
|
|
153
|
-
refusal, and error completion are not user cancellation. Separate engine-owned
|
|
154
|
-
family state survives hot reload, containing the abort timestamp and frozen
|
|
155
|
-
membership generations. The artifact stores a generation-scoped monotonic activity
|
|
156
|
-
cutoff; replacement generations cannot inherit the old abort.
|
|
157
|
-
|
|
158
|
-
Engine state reads are snapshots of one dispatch. Confirmation therefore uses
|
|
159
|
-
one immediate fresh `clock.after` dispatch to read cancellation, not a repeated
|
|
160
|
-
read in the old dispatch. It is not polling. If reload cancels a pending callback,
|
|
161
|
-
its evidence stays unknown: reload does not replay it. A failed cancel bridge
|
|
162
|
-
can be repaired by the fresh confirmation/reconciliation dispatch from retained
|
|
163
|
-
engine state. If all bridge/state operations are unavailable, Square cannot
|
|
164
|
-
promise a receipt or suppression; it fails boundedly and preserves unrelated
|
|
165
|
-
Claude behavior.
|
|
166
|
-
|
|
167
|
-
**Already queued OR natively held messages cannot be retracted.** Approval may
|
|
168
|
-
release a held message without another receive guard. Append is observational,
|
|
169
|
-
not a veto. Square suppresses local retries and stale evidence but cannot erase
|
|
170
|
-
native custody or promise that remote work will not run. New activity after the
|
|
171
|
-
abort remains eligible. Protocol design and runtime evidence live in the package
|
|
172
|
-
`VALIDATION.md` and the commission artifacts it cites; the repository fixtures
|
|
173
|
-
cover the same coordinator and packaging boundaries without requiring a Claude
|
|
174
|
-
installation.
|
|
3
|
+
Square's Claude plugin is a mod, not a shell-hook injector. Its MCP server uses the mod's call-local
|
|
4
|
+
session association; a missing or expired association fails closed. A session ID or socket alone does
|
|
5
|
+
not establish that the mod is loaded. The supported native path requires macOS Claude Code with the
|
|
6
|
+
mod loaded and approved. Square does not alter inbound policy or bypass a held peer message.
|
|
7
|
+
|
|
8
|
+
The mod attaches and detaches the exact host session in the delivery ledger. Membership remains in
|
|
9
|
+
Square; host end does not land `done`, and start/resume does not restore seats. See
|
|
10
|
+
[participant-ownership.md](participant-ownership.md).
|
|
11
|
+
|
|
12
|
+
The sender dispatches finished ledger cards through the native socket. Native admission settles a
|
|
13
|
+
handoff as accepted, not presented; the stored main user-role text observation settles presentation
|
|
14
|
+
through its handoff reference. This establishes observation at that boundary, not comprehension, and
|
|
15
|
+
cannot promise that a later plugin leaves the card intact. Unknown native custody is not a safe reason
|
|
16
|
+
to replay through another route. A shortened activity card points to catch; Square only folds a receipt
|
|
17
|
+
for a full card into its read state. Direct producer notices retain their full body.
|
|
18
|
+
|
|
19
|
+
`turn.abort` cancels the outstanding ledger batch without asserting it was read. Already queued or
|
|
20
|
+
natively held messages cannot be recalled. The shared transport and its validated limits are documented
|
|
21
|
+
in [agent-delivery's README](../packages/agent-delivery/README.md) and `VALIDATION.md`.
|
package/guides/codex-delivery.md
CHANGED
|
@@ -1,90 +1,67 @@
|
|
|
1
1
|
# Codex delivery
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
app-server capability and its host-owned hook integration.
|
|
3
|
+
Producers post neutral cards to DeliveryLedger; neither default dispatch nor public `postAndDispatch`
|
|
4
|
+
queues Codex input. A native receiver owns both synchronous presentation and idle queue admission.
|
|
5
|
+
It never reads Square artifacts or producer content stores.
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
The shipped hooks for Codex 0.166.0 are synchronous SessionStart, UserPromptSubmit, PreToolUse,
|
|
8
|
+
PostToolUse, Stop, Interrupt and SessionEnd, plus an async Stop command with `timeout: 86400` seconds.
|
|
9
|
+
SessionStart disarms and attaches the exact native session. Active prompt/tool boundaries disarm and
|
|
10
|
+
present eligible cards as event-correct `additionalContext`, using neutral reminder framing and the
|
|
11
|
+
original card text. The output sink must accept the response before presentation evidence is recorded;
|
|
12
|
+
a later suppression does not erase a real output effect. SessionEnd disarms and detaches. None of these
|
|
13
|
+
host lifecycle events restores or detaches Square seats. SessionResume is not a verified native event
|
|
14
|
+
and is not registered. A resume path without a real SessionStart/Stop has no inferred idle authority.
|
|
11
15
|
|
|
12
|
-
|
|
16
|
+
Each synchronous Stop stores a unique token and native turn ID in the existing boundary store. One
|
|
17
|
+
receiver-owned `square codex-watch` command holds a separate private OS-backed lock for its native
|
|
18
|
+
session coordinate and observes the ledger, with a one-second bounded rescan for boundary changes or
|
|
19
|
+
missed notifications. Duplicate async Stop processes exit; the existing watcher follows newer Stop
|
|
20
|
+
tokens. The lock does not prove idle state. Observation never reserves cards while waiting.
|
|
13
21
|
|
|
14
|
-
|
|
22
|
+
Before claiming each card, the watcher reads the hosting endpoint's `thread/read(includeTurns:true)`.
|
|
23
|
+
It requires loaded idle state and the newest live turn to be completed with exactly the captured Stop
|
|
24
|
+
turn ID. Newest-last history ordering is verified for 0.166.0; other versions fail closed until verified.
|
|
25
|
+
After claiming, the receiver repeats that native read, checks the exact epoch again, then checks ledger
|
|
26
|
+
currentness, suppression, cancellation, attachment generation, signal and deadline immediately before
|
|
27
|
+
CLI invocation. Queue always uses the existing hosting endpoint explicitly, without starting a service.
|
|
28
|
+
Missing, malformed, ephemeral, notLoaded, active, interrupted or unreadable history cannot authorize a
|
|
29
|
+
queue. A delayed stale Stop cannot authorize sending merely by arriving after an active callback.
|
|
15
30
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
A new/forked session restores nothing.
|
|
24
|
-
- `PostToolUse` asks Square for current pending activity and returns the existing
|
|
25
|
-
bounded `additionalContext` presentation.
|
|
26
|
-
- `Stop` records queue eligibility and sweeps pending work, but does not itself
|
|
27
|
-
claim that a preview was presented.
|
|
31
|
+
`square codex-interrupt` handles only a native Interrupt payload and cancels the captured attachment's
|
|
32
|
+
pending through-sequence batch, then future cards remain available after a later verified Stop or active
|
|
33
|
+
boundary. Replacement attachments are fenced by generation. Before-effect epoch/suppression/cancel
|
|
34
|
+
failures release their claims where the ledger permits. Attachment rotation already normalizes an
|
|
35
|
+
in-flight ledger attempt to unknown: that custody remains unknown even if the final receiver check
|
|
36
|
+
then proves no queue was launched. The watcher exits on detach, deletion or generation change and
|
|
37
|
+
retains its ledger connection only for already-captured late settlements.
|
|
28
38
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
the internal budget, the hook waits for it and returns the associated context;
|
|
36
|
-
it never abandons settlement that can mark activity seen without returning text.
|
|
37
|
-
After expiry, no sweep starts, and a sweep timeout cannot erase successful pull
|
|
38
|
-
output. Settlement must still finish within Codex's external hook timeout. Hook inbox lookup uses
|
|
39
|
-
an exact owner from `harnessOwner({ channel: 'codex', session })`, not a bare session id. The shared
|
|
40
|
-
boundary store uses Square's caller-selected `SQUARE_CODEX_BOUNDARIES` file,
|
|
41
|
-
defaulting to `~/.square/codex-boundaries.json`; its JSON observations are not
|
|
42
|
-
conversation storage and are not proof of current native execution or consumption.
|
|
43
|
-
Square's format-8 artifact remains authoritative for membership, attachment and delivery evidence.
|
|
44
|
-
Detached members appear away indefinitely and keep accumulating unread audience, but have no
|
|
45
|
-
write or proactive delivery eligibility until same-owner reattachment. Only a host-confirmed
|
|
46
|
-
permanent deletion uses fenced membership-ending cleanup; Codex SessionEnd is not that proof.
|
|
39
|
+
Queue admission is custody, not presentation or model comprehension. Accepted/unknown outbox custody
|
|
40
|
+
has no remaining card content and cannot be automatically replayed. Invoked timeout or ambiguous
|
|
41
|
+
results remain unknown. Native idle reads and external queue are not atomic: a new turn can start after
|
|
42
|
+
the final check and a raced queue may arrive later. Interrupt cannot recall input already admitted by
|
|
43
|
+
Codex, and hook failure/timeout cannot prove that cancellation happened. Native callbacks have no
|
|
44
|
+
cross-incarnation event identity; SessionEnd can fence only the attachment observed when it runs.
|
|
47
45
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
artifact-owned delivery path; no host ledger or new route kind is introduced.
|
|
46
|
+
There is no watcher before the first Stop. Synchronous boundaries can present; otherwise cards wait.
|
|
47
|
+
The async budget is finite 24 hours, not a promise of 24-hour observation. After timeout, crash, host
|
|
48
|
+
termination or missed spawn while idle, cards wait for the next Stop/user/native boundary. There is no
|
|
49
|
+
producer fallback or autonomous crash-idle recovery. During attachment replacement an old watcher
|
|
50
|
+
may briefly retain the coordinate lock while the new Stop's duplicate exits; the next Stop restores
|
|
51
|
+
observation after the old process releases it.
|
|
55
52
|
|
|
56
|
-
|
|
57
|
-
recipient's `CODEX_HOME` (or home default), so later senders use the recipient's
|
|
58
|
-
CLI configuration rather than their own. Only an explicitly configured
|
|
59
|
-
`SQUARE_CODEX_ENDPOINT` adds a remote endpoint. `SQUARE_CODEX_BIN` remains
|
|
60
|
-
Square's executable selection; it is not an environment convention of the
|
|
61
|
-
independent package.
|
|
53
|
+
Reproduce the isolated native smoke from this checkout after a worktree-local build:
|
|
62
54
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
check also catches an end observed while the currentness gate was running.
|
|
68
|
-
It cannot retract a submission already launched or infer a missed end hook.
|
|
69
|
-
Queue success means native admission only; its receipt id is a local attempt
|
|
70
|
-
UUID, not a server message id. The child runs asynchronously and respects the
|
|
71
|
-
send's abort signal/deadline. Timeout, killed child and unexplained post-launch
|
|
72
|
-
failures remain unknown, not a safe reason to resend. A receiver with no tool
|
|
73
|
-
calls waits for Stop; this path is not instantaneous native steer.
|
|
55
|
+
```sh
|
|
56
|
+
env -u SQUARE_HOST_LEDGER_ROOT SQUARE_CODEX_NATIVE_SMOKE=1 \
|
|
57
|
+
node --import ./test/sandbox-env.js test/codex-watch-native.mjs
|
|
58
|
+
```
|
|
74
59
|
|
|
75
|
-
|
|
60
|
+
The probe creates a temporary HOME/CODEX_HOME, installs no plugin, and uses the actual shipped hook
|
|
61
|
+
manifest/CLI with an isolated native app-server and loopback fixture provider. Its JSON evidence names
|
|
62
|
+
the temporary directory. It verifies native Stop startup, idle wake, busy fencing, singleton reuse,
|
|
63
|
+
Interrupt RPC cancellation, real UserPromptSubmit presentation and process-group shutdown. Physical
|
|
64
|
+
TUI Escape-to-Interrupt is not verified; neither are 24-hour operation or every resume path.
|
|
76
65
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
`transport: 'app-server'` is the explicit spelling and the default when omitted;
|
|
80
|
-
it exposes both methods. `transport: 'cli'` exposes queue only and requires the
|
|
81
|
-
host's hook lifecycle source at connection time. There is no automatic fallback
|
|
82
|
-
between transports. The app-server transport never starts a service or calls
|
|
83
|
-
`thread/resume`. This does not replace Square's hook policy or add a new persisted
|
|
84
|
-
Square route kind. A loaded thread's owner remains its existing host, not the
|
|
85
|
-
external sender.
|
|
86
|
-
|
|
87
|
-
Neither path implements a read-receipt roundtrip. Admission and runtime
|
|
88
|
-
observations must not be presented as model comprehension or completion. An
|
|
89
|
-
unknown outcome stays unknown. Installing, restarting or changing a real Codex
|
|
90
|
-
server is outside this integration.
|
|
66
|
+
The shared package documents its transport leaves in [its README](../packages/agent-delivery/README.md).
|
|
67
|
+
See [participant ownership](participant-ownership.md) for host attachment and Square membership.
|