@astrosheep/square 0.3.96 → 0.3.98

package/guides/square-api.md

@@ -197,7 +197,7 @@ shared dispatcher's timeout or retry policy.
 
 ## One set of operations and defaults
 
-Square owns `history`, `status`, `participants`, `snapshot`, `stream`, and recovery observations.
+Square owns `history`, `status`, `participants`, `stream`, and recovery observations.
 A file-backed `stream` follows the path with a fresh artifact read for each page, so atomic file
 replacement is visible even while the resource holds its original connection. Its iterator owns
 its observation lifetime: `return()` interrupts a pending pull; closing a local Square does not close
@@ -211,7 +211,7 @@ their landed directed activities and adds `perception` and the landing route `vi
 (`mention`, `reply`, `attention`, or `bell`). Perception follows the viewer's actual landed audience;
 `via` is absent when no directed route exists. Stream starts at a bounded tail or after an `ActivityId`
 like `act/12`; it never consumes activity.
-Participant owns `express`, `catch`, `listen`, `unlisten`, `ignore`, `listening`, `done`,
+Participant owns `express`, `catch`, `pending`, `ack`, `listen`, `unlisten`, `ignore`, `listening`, `done`,
 `deferDelivery`, `renewDeliveryDeferral`, and `releaseDeliveryDeferral`. History belongs only to
 Square; there is no `Participant.history`.
 
@@ -231,8 +231,8 @@ Square; there is no `Participant.history`.
   ordering, consumption or permissions. A current participant may temporarily defer proactive delivery
   by exact metadata match through the SDK lease API below. Metadata may nest up to 256 levels; the bound is enforced before
   persistence and public reads. Human text uses a concise structured-activity placeholder and never prints
-  metadata JSON. There is no archive metadata filter, query language or index; CLI `--metadata <json>` is the only
-  metadata input flag.
+  metadata JSON. SDK history and pending queries accept exact metadata matches; there is no query
+  language or metadata index. CLI `--metadata <json>` remains an express input flag.
 - Catch returns `{activities, remaining, reason, hint?, observation?}`. Each activity includes
   viewer-relative `perception` and `via`. Reasons are `drained`, `idle`, `capped`, `quorum`,
   `replaced`, or `already-active`. Omitted/zero idle is immediate; positive idle uses the single
@@ -271,6 +271,105 @@ Operations that accept an `OperationControl` use a final argument with `signal`
 `onProgress`. Listener/lifecycle operations take optional observation options before that argument;
 participant selection, seat discovery and host cleanup methods do not take an `OperationControl`.
 
+## Shared history and pending filters
+
+`HistoryQuery` and `PendingOptions` extend the same exported `ActivityQuery`:
+
+```ts
+interface ActivityQuery {
+  at?: readonly ActivityId[];
+  from?: readonly string[];
+  match?: MetadataMatch;
+  search?: { text: string; mode: 'literal' | 'regex' };
+  cursor?: { id: ActivityId; direction: 'before' | 'after' };
+}
+```
+
+- Filters combine with AND. IDs in `at` and senders in `from` each combine with OR; an absent array
+  is unrestricted, while an explicitly empty array matches nothing. `at` is an exact ID selection;
+  only history can expand those IDs with `contextBefore` / `contextAfter`.
+- Sender names use case-insensitive identity matching and need not belong to a joined participant.
+  Direct senders such as `keiyaku-notice` can be queried without inventing membership. A valid but
+  unmatched sender returns no activities, not an unknown-participant error.
+- `match` uses the same nested own-property, exact type-sensitive scalar equalities as deferrals.
+  `search` tests each activity's ID, sender and body independently, case-insensitively. Literal mode
+  treats regex characters as plain text; regex mode uses JavaScript's built-in regular expressions,
+  without a ReDoS timeout. Search text must be nonempty and regex syntax must be valid. History
+  searches says and departures, not joins; pending always selects addressed, unconsumed says.
+- A cursor is an exclusive activity-ID boundary, independent of `limit`: before excludes the anchor
+  and everything newer; after excludes the anchor and everything older. No consumption is involved.
+  Storage applies the shared filters before limiting and uses the same predicates for counts.
+- History keeps its archive-specific `order`, `mention`, `since` and context options. By default it
+  selects the newest page and returns it oldest first; an after cursor selects the oldest following
+  page. `order: 'desc'` reverses the selected page, not which activities belong to it. Numeric limits
+  stay 1–100, default ten; `limit: null` reads all matches. Exact/context history keeps its existing
+  implicit full-window selection with a 100-activity bound unless a numeric limit is supplied.
+- Pending always selects oldest first, including with a before cursor. Its default and maximum page
+  size remain 100, and `remaining` counts matching unconsumed activities beyond that page within
+  the supplied cursor boundary. It has no history context, ordering or audience override.
+
+The SDK accepts only `search` and `cursor`, not the removed `grep` / `fixed` / `before` / `after`
+fields. CLI flags and tool arguments keep those familiar spellings and translate at the adapter
+boundary, e.g. `--fixed text` becomes `search: {text, mode: 'literal'}` and `--after act/12` becomes
+`cursor: {id: 'act/12', direction: 'after'}`. The artifact format and stored activities do not change.
+
+## Pending query and exact acknowledgement
+
+`Participant.pending(options?, control?)` and `Participant.ack(ids, control?)` separate a read-only
+query from explicit consumption. `ChannelEndpoint` from `@astrosheep/square/channel` exposes the
+identical methods by forwarding to its captured Participant; it has no independent inbox or storage.
+
+`Channel.send` / `Square.send` address joined members, including detached members. Attachment gates
+proactive wake, not landing: a detached recipient retains its unread addressed activity without a
+wake and can query/ack it after reattachment. Recipient validation remains all-or-nothing; a missing
+or departed recipient rejects the entire send without landing activity or waking other recipients.
+
+```ts
+import type { ChannelEndpoint, MetadataMatch } from '@astrosheep/square/channel';
+
+async function drain(endpoint: ChannelEndpoint, match: MetadataMatch) {
+  for (;;) {
+    const page = await endpoint.pending({ match });
+    if (page.activities.length === 0) break;
+    // Process the entire page successfully before acknowledging its exact IDs.
+    for (const activity of page.activities) await processNotice(activity);
+    const { consumed } = await endpoint.ack(page.activities.map(activity => activity.id));
+    // consumed may be smaller if another consumer acknowledged some IDs first.
+  }
+}
+```
+
+- `pending(query: PendingOptions = {}, control?)` returns
+  `{activities: readonly PerceivedActivity[], remaining: number}`. It selects only landed,
+  addressed, unconsumed says, oldest first. Body, metadata, delivery information, perception and
+  route use the same public records as catch; bodies are full stored bodies, not clipped previews.
+- Limit defaults to 100 and must be an integer from 1 through 100. The shared filters above are
+  available alongside that limit. Storage applies addressedness, consumption and all supplied
+  filters **before** limiting. `remaining` counts matching unconsumed activities outside the returned
+  page in the same read transaction. It is not the global unread count or a durable cursor.
+- A pending query consumes nothing, changes no read horizon and writes no delivery/presentation
+  evidence. Deferrals, catch leases, cancellation and prior clipped presentation do not hide these
+  explicit reads. Like catch, pending includes historical addressed receipt holes before a rejoin;
+  it is not the proactive delivery eligibility query.
+- `ack(ids: readonly ActivityId[], control?)` returns `{consumed: number}`, the count of newly
+  consumed exact IDs. It validates that **every** supplied ID is addressed to this participant before
+  recording any receipts. Malformed, nonexistent or unaddressed IDs reject the whole batch with
+  `invalid_args` (`reason: 'not_addressed'` for valid but unaddressed IDs). There is no implicit prefix
+  acknowledgement, no match reselection and no requirement for an earlier pending call.
+- Duplicate IDs, repeated acknowledgement and an empty array are idempotent. Existing receipt
+  timestamps remain unchanged. Acknowledgement uses the same sparse receipts as catch/full
+  presentation, so it removes those IDs from pending and ordinary catch, but exact catch remains
+  repeatable. It does **not** assert wake acceptance or presentation and writes no such evidence.
+- Both operations require their captured current owner, generation and attached seat; even an empty
+  query/ack cannot reuse a detached, retired or replaced handle. No storage format change is needed.
+  Cancellation before the receipt transaction prevents consumption; a committed ack is not undone.
+- To drain all matching notices, keep querying and acknowledging pages until an **empty** page.
+  Acknowledging one page exposes the next without a cursor. For read-only pagination instead, pass
+  `cursor: {id: page.activities.at(-1)!.id, direction: 'after'}` with the same filters; earlier pages
+  stay unconsumed. Do not silently stop after the default page or treat a snapshot `remaining: 0`
+  as proof that concurrent producers have stopped. Query and
+  ack are separate operations, not an exclusive claim or an exactly-once external-effect guarantee.
+
 ## Temporary proactive delivery deferral
 
 SDK Participants expose three operations. There are no CLI/MCP/Pi authoring
@@ -307,9 +406,9 @@ try {
   releasing one cannot end another. A captured current owner/join generation is required for every
   mutation. Stale handles retain the ownership refusal; done/takeover/rejoin retire old leases.
 - Lease writes change delivery revision, not conversation history. They do not create a receipt,
-  change audience or unread counts, hide an archive record, or prohibit explicit catch. Catch alone
-  consumes normally; a caught record is not replayed when a deferral ends. The catch lease is a
-  separate, single quiet-wait lease with its existing filters and lifecycle.
+  change audience or unread counts, hide an archive record, or prohibit explicit catch/pending/ack.
+  Catch and ack consume normally; a consumed record is not replayed when a deferral ends. The catch
+  lease is a separate, single quiet-wait lease with its existing filters and lifecycle.
 - Producer/sweep, atomic claims, session/native projections, final pre-send checks and proactive
   presentation all share current-generation unexpired matching. Suppressed items get no seen or
   presented receipt. An active pending observer rechecks on release and the earliest relevant
@@ -339,8 +438,8 @@ or history/status presentation annotations.
 Express captures optional unread context before the attempt: the latest five directed,
 unseen activities after the current join, each preview capped at 400 Unicode characters,
 plus the count outside that preview. It hydrates only that page, not the entire cursor suffix.
-This is a nonconsuming preview even when a short body fits in full; only `catch` or the
-normal full-notification presentation path consumes it. Count and time facts come
+This is a nonconsuming preview even when a short body fits in full; consumption requires `catch`,
+explicit `ack`, or the normal full-notification presentation path. Count and time facts come
 from the committed transaction. Listener and lifecycle observations likewise use their mutation's
 facts, with no postcommit context read. Join uses its mutation's essential facts and treats optional
 entry/history enrichment as best-effort: `observation.enrichmentUnavailable` is explicit and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.96",
+  "version": "0.3.98",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -46,7 +46,6 @@
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22",
     "@types/ws": "^8.18.1",
-    "square-v1": "npm:@astrosheep/square@0.3.70",
     "typescript": "^5.8",
     "ws": "^8.21.3"
   },

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.96",
+  "version": "0.3.98",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.96",
+  "version": "0.3.98",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/codex/hooks/hooks.json

@@ -1,16 +1,16 @@
 {
   "hooks": {
     "SessionStart": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],
     "SessionResume": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],
     "SessionEnd": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 3 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 3, "statusMessage": "Square" }] }
     ],
     "UserPromptSubmit": [
-      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5, "statusMessage": "Square" }] }
     ],
     "PostToolUse": [
       {
@@ -19,7 +19,7 @@
             "type": "command",
             "command": "square codex-hook",
             "timeout": 5,
-            "statusMessage": "square-codex-hook"
+            "statusMessage": "Square"
           }
         ]
       }
@@ -31,7 +31,7 @@
             "type": "command",
             "command": "square codex-hook",
             "timeout": 5,
-            "statusMessage": "square-codex-hook"
+            "statusMessage": "Square"
           }
         ]
       }