@astrosheep/square 0.3.97 → 0.3.98

package/dist/activity-query.d.ts

@@ -0,0 +1,4 @@
+import type { ActivityFilter } from './ports.js';
+import type { ActivityQuery } from './square-facade.js';
+/** Both public read paths compile the same filters; neither resolves senders through membership. */
+export declare function activityQueryFilter(query: ActivityQuery, extraFields?: readonly string[]): ActivityFilter;

package/dist/activity-query.js

@@ -0,0 +1,51 @@
+import { SquareError, validateName } from './model.js';
+import { parseActivityId } from './square-core.js';
+import { validateMetadataMatch } from './delivery-deferral.js';
+import { compileSearchPattern } from './search.js';
+/** Both public read paths compile the same filters; neither resolves senders through membership. */
+export function activityQueryFilter(query, extraFields = []) {
+    const fail = (message) => { throw new SquareError('invalid_args', message); };
+    const fields = ['at', 'from', 'match', 'search', 'cursor', 'limit', ...extraFields];
+    if (typeof query !== 'object' || query === null || Array.isArray(query))
+        fail('Activity query must be an object.');
+    for (const field of Object.keys(query))
+        if (!fields.includes(field))
+            fail(`Unknown activity query field: ${field}`);
+    const indexes = query.at === undefined ? undefined : !Array.isArray(query.at) ? fail('Query at must be an array of activity IDs.')
+        : Array.from(query.at, id => {
+            const index = parseActivityId(id);
+            return index === undefined ? fail(`Invalid activity id: ${id}`) : index;
+        });
+    const actors = query.from === undefined ? undefined : !Array.isArray(query.from) ? fail('Query from must be an array of sender names.')
+        : Array.from(query.from, name => {
+            if (typeof name !== 'string')
+                fail('Query from must contain sender names.');
+            validateName(name);
+            return name;
+        });
+    const metadataMatch = query.match === undefined ? undefined : validateMetadataMatch(query.match);
+    let afterIndex, beforeIndex;
+    if (query.cursor !== undefined) {
+        const cursor = query.cursor;
+        if (typeof cursor !== 'object' || cursor === null || Array.isArray(cursor)
+            || !['before', 'after'].includes(cursor.direction) || Object.keys(cursor).some(key => !['id', 'direction'].includes(key)))
+            fail('Query cursor requires an activity ID and before/after direction.');
+        const index = parseActivityId(cursor.id);
+        if (index === undefined)
+            fail(`Invalid activity id: ${cursor.id}`);
+        if (cursor.direction === 'after')
+            afterIndex = index;
+        else
+            beforeIndex = index;
+    }
+    let search = query.search;
+    if (search !== undefined) {
+        if (typeof search !== 'object' || search === null || Array.isArray(search)
+            || typeof search.text !== 'string' || search.text === '' || !['literal', 'regex'].includes(search.mode)
+            || Object.keys(search).some(key => !['text', 'mode'].includes(key)))
+            fail('Query search requires non-empty text and literal/regex mode.');
+        compileSearchPattern(search.text, search.mode === 'literal');
+        search = { text: search.text, mode: search.mode };
+    }
+    return { indexes, actors, metadataMatch, search, afterIndex, beforeIndex };
+}

package/dist/channel.d.ts

@@ -2,7 +2,7 @@ import { type HarnessSessionChannel } from './participant-identity.js';
 import type { SquareResourceOwner, WakeTransportPort } from './ports.js';
 import type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, Participant, WakeAddress, PendingOptions, PendingResult, AckResult } from './square-facade.js';
 export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
-export type { ActivityDelivery, ActivityMetadata, ChannelTruncate, PerceivedActivity, PendingOptions, PendingResult, AckResult } from './square-facade.js';
+export type { ActivityDelivery, ActivityMetadata, ActivityQuery, ActivitySearch, ActivityCursor, ChannelTruncate, PerceivedActivity, PendingOptions, PendingResult, AckResult } from './square-facade.js';
 export type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, WakeAddress, SquareResourceOwner, WakeTransportPort, HarnessSessionChannel };
 export interface ResolvedHarnessSession {
     readonly channel: HarnessSessionChannel;

package/dist/cli/observation-commands.js

@@ -375,8 +375,11 @@ function parseHistory(argv, context) {
     if (before !== undefined && after !== undefined)
         fail('--before and --after cannot be combined.');
     return {
-        query: { limit, from: participants, since, after, before, at: at.length === 0 ? undefined : at,
-            contextBefore: beforeContext, contextAfter: afterContext, mention, grep, fixed, order },
+        query: { limit, from: participants.length === 0 ? undefined : participants, since,
+            cursor: after !== undefined ? { id: after, direction: 'after' } : before === undefined ? undefined : { id: before, direction: 'before' },
+            at: at.length === 0 ? undefined : at,
+            contextBefore: beforeContext, contextAfter: afterContext, mention, order,
+            search: grep !== undefined ? { text: grep, mode: 'regex' } : fixed === undefined ? undefined : { text: fixed, mode: 'literal' } },
         noTruncate, format,
         continuationArgs: historyContinuationArgs(argv),
     };

package/dist/operation-presentation.js

@@ -155,10 +155,8 @@ function historyQueryArgs(query) {
         args.push('-A', String(query.contextAfter));
     if (query.mention !== undefined)
         args.push('--mention', query.mention);
-    if (query.grep !== undefined)
-        args.push('--grep', query.grep);
-    if (query.fixed !== undefined)
-        args.push('--fixed', query.fixed);
+    if (query.search !== undefined)
+        args.push(query.search.mode === 'regex' ? '--grep' : '--fixed', query.search.text);
     if (query.order !== undefined)
         args.push('--order', query.order);
     return args;
@@ -169,10 +167,10 @@ export function renderHistoryResult(squarePath, data, options = {}) {
         return undefined;
     const query = options.query ?? {};
     const noTruncate = options.noTruncate === true;
-    const pattern = query.grep ?? query.fixed;
-    const output = pattern === undefined || pattern === ''
+    const search = query.search;
+    const output = search === undefined
         ? renderHistoryProjection(projection, projection.visibleActivities, noTruncate, squarePath)
-        : renderGrepActivitiesView(projection.visibleActivities, projection.totalMatches, noTruncate, squarePath, pattern, query.fixed !== undefined, () => 'full');
+        : renderGrepActivitiesView(projection.visibleActivities, projection.totalMatches, noTruncate, squarePath, search.text, search.mode === 'literal', () => 'full');
     const next = projection.continuation;
     const base = options.continuationArgs ?? historyQueryArgs(query);
     const continuation = next === undefined ? '' : `\n\n${historyContinuationCommand(squarePath, [...base, `--${next.direction}`, next.cursor, '--limit', String(next.limit)])}`;

package/dist/ports.d.ts

@@ -1,6 +1,7 @@
 import type { Act, ActivityId, Owner, HardCap, Seat, StoredAct, WakeAddress, WakeRoute, WatchLease } from './model.js';
 import type { AttemptOutcome } from './delivery-attempts.js';
 import type { MetadataMatch, DeliveryDeferralFact } from './delivery-deferral.js';
+import type { ActivitySearch } from './square-facade.js';
 export type ActivityIndex = number;
 export interface SquareHeader {
     readonly revision: number;
@@ -49,6 +50,9 @@ export interface ActivityFilter {
     readonly actors?: readonly string[];
     readonly actorMatch?: 'identity' | 'exact';
     readonly afterAt?: number;
+    /** Shared query predicates, applied before paging or counting. */
+    readonly metadataMatch?: MetadataMatch;
+    readonly search?: ActivitySearch;
 }
 export interface IndexPage {
     readonly edge: 'oldest' | 'newest';
@@ -58,13 +62,8 @@ export interface FactPage<T> {
     readonly items: readonly T[];
     readonly hasMore: boolean;
 }
-export interface DirectedFilter {
-    readonly afterIndex?: number;
-    readonly beforeIndex?: number;
-    readonly throughIndex?: number;
+export interface DirectedFilter extends Omit<ActivityFilter, 'actors' | 'actorMatch'> {
     readonly unseenOnly?: true;
-    /** Exact own-property scalar equalities, applied before paging or counting. */
-    readonly metadataMatch?: MetadataMatch;
     readonly senders?: readonly string[];
     readonly attentionOnly?: true;
 }

package/dist/search.js

@@ -1,7 +1,6 @@
-// Shared activity-body search semantics for filtering and presentation.
-// Regex mode intentionally uses JavaScript's built-in engine: patterns come from
-// the local CLI user and are not treated as a hostile multi-tenant input. Use
-// --fixed for literal text; do not claim regex mode has ReDoS protection.
+// Shared case-insensitive search semantics for storage filtering and presentation.
+// Regex mode intentionally uses JavaScript's built-in engine, without a ReDoS
+// timeout. Callers should use literal mode for plain text and avoid untrusted regexes.
 import { SquareError } from './model.js';
 export function compileSearchPattern(pattern, fixed) {
     if (fixed)
@@ -11,7 +10,7 @@ export function compileSearchPattern(pattern, fixed) {
     }
     catch (err) {
         const detail = err instanceof Error ? err.message.replace(/^Invalid regular expression:\s*/i, '') : 'invalid expression';
-        throw new SquareError('invalid_args', `Invalid --grep regex: ${detail}`);
+        throw new SquareError('invalid_args', `Invalid search regex: ${detail}`);
     }
 }
 function compactWhitespace(text) {

package/dist/sqlite-square.js

@@ -1,6 +1,7 @@
 import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 import { assertCurrentSeat } from './square-domain.js';
 import { canonicalPath } from './canonical-path.js';
+import { activityQueryFilter } from './activity-query.js';
 import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
 import { squareLocation } from './square-location.js';
 import crypto from 'node:crypto';
@@ -346,14 +347,13 @@ export class SqliteSquare {
         }
         async pending(options = {}, control) {
             checkControl(control);
-            const limit = options.limit ?? 100;
+            const limit = options.limit === undefined ? 100 : options.limit;
             if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
                 throw new SquareError('invalid_args', 'Pending limit must be a positive integer no greater than 100.');
-            const match = options.match === undefined ? undefined : validateMetadataMatch(options.match);
-            const square = this.owner;
+            const { actors, ...query } = activityQueryFilter(options), square = this.owner;
             return (await square.artifact.read(facts => {
                 assertCurrentSeat(facts, asSeatRef(this.seat));
-                const filter = { unseenOnly: true, ...(match === undefined ? {} : { metadataMatch: match }) };
+                const filter = { ...query, senders: actors, unseenOnly: true };
                 const heads = facts.directed(this.name, filter, { edge: 'oldest', limit });
                 const activities = facts.activities(heads.items.map(head => head.index))
                     .map(activity => toPerceivedActivity(facts, activity, this.name));
@@ -566,10 +566,8 @@ export class SqliteSquare {
     async history(query = {}, control) {
         if (query.limit !== undefined && query.limit !== null && (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > HISTORY_MAX_LIMIT))
             throw new SquareError('invalid_args', `History limit must be a positive integer no greater than ${HISTORY_MAX_LIMIT}`);
-        if (query.grep !== undefined && query.fixed !== undefined)
-            throw new SquareError('invalid_args', 'History cannot combine regular-expression and literal search');
-        if (query.grep === '' || query.fixed === '')
-            throw new SquareError('invalid_args', 'History search requires non-empty text');
+        if (query.order !== undefined && query.order !== 'asc' && query.order !== 'desc')
+            throw new SquareError('invalid_args', 'History order must be asc or desc.');
         if (query.since !== undefined && !Number.isFinite(query.since))
             throw new SquareError('invalid_args', 'History timestamp must be finite');
         for (const count of [query.contextBefore, query.contextAfter])

package/dist/square-facade.d.ts

@@ -86,8 +86,23 @@ export interface CatchOptions extends ObservationOptions {
     readonly limit?: number;
     readonly replace?: boolean;
 }
-export interface PendingOptions {
+export interface ActivitySearch {
+    readonly text: string;
+    readonly mode: 'literal' | 'regex';
+}
+export interface ActivityCursor {
+    readonly id: ActivityId;
+    readonly direction: 'before' | 'after';
+}
+/** Shared filters; absent arrays are unrestricted, empty arrays match nothing. */
+export interface ActivityQuery {
+    readonly at?: readonly ActivityId[];
+    readonly from?: readonly string[];
     readonly match?: MetadataMatch;
+    readonly search?: ActivitySearch;
+    readonly cursor?: ActivityCursor;
+}
+export interface PendingOptions extends ActivityQuery {
     /** Oldest first; defaults to 100, maximum 100. */
     readonly limit?: number;
 }
@@ -140,18 +155,12 @@ export interface OperationFailureDetail {
 export interface OperationError extends Error {
     readonly operation?: OperationFailureDetail;
 }
-export interface HistoryQuery extends ObservationOptions {
+export interface HistoryQuery extends ActivityQuery, ObservationOptions {
     /** Ten by default; null explicitly reads the full archive. */
     readonly limit?: number | null;
     readonly order?: 'asc' | 'desc';
-    readonly before?: ActivityId;
-    readonly after?: ActivityId;
-    readonly grep?: string;
-    readonly fixed?: string;
-    readonly from?: readonly string[];
     readonly mention?: string;
     readonly since?: number;
-    readonly at?: readonly ActivityId[];
     readonly contextBefore?: number;
     readonly contextAfter?: number;
 }

package/dist/square-sqlite.js

@@ -5,6 +5,8 @@ import { deriveLanding, landingFacts } from './square-domain.js';
 import { claimAttempt, prepareAttempt, settleAttempt } from './delivery-attempts.js';
 import { legacyRowFramingIssue, legacyActivitySchema } from './square-legacy-framing.js';
 import { receive, recordConsumed } from './receive.js';
+import { formatActivityId } from './square-core.js';
+import { compileSearchPattern } from './search.js';
 export function emptyRuntimeState(nextActIndex = 0) {
     return { nextActIndex, observations: {}, leases: {} };
 }
@@ -506,6 +508,30 @@ function activitySelection(filter, alias = 'a') {
             add(`${alias}.${column} IN (SELECT value FROM json_each(?))`, encode(values));
         }
     }
+    if (filter.metadataMatch !== undefined) {
+        // Walk literal object keys, never JSON-path strings or array indexes.
+        terms.push(`NOT EXISTS (
+            SELECT 1 FROM json_each(?) field WHERE NOT EXISTS (
+                WITH RECURSIVE walk(value,type,depth) AS (
+                    SELECT json_extract(${alias}.payload_json,'$.metadata'),json_type(${alias}.payload_json,'$.metadata'),0
+                    UNION ALL
+                    SELECT child.value,child.type,walk.depth+1
+                    FROM walk JOIN json_each(CASE WHEN walk.type='object' THEN walk.value ELSE '{}' END) child
+                      ON child.key=json_extract(field.value,'$.path['||walk.depth||']')
+                    WHERE walk.depth<json_array_length(field.value,'$.path')
+                )
+                SELECT 1 FROM walk WHERE depth=json_array_length(field.value,'$.path')
+                  AND (type=json_type(field.value,'$.equals')
+                    OR type IN ('integer','real') AND json_type(field.value,'$.equals') IN ('integer','real'))
+                  AND value IS json_extract(field.value,'$.equals')
+            )
+        )`);
+        args.push(encode(filter.metadataMatch.fields));
+    }
+    if (filter.search !== undefined) {
+        terms.push(`square_search(?,?,${alias}.act_index,${alias}.actor_json,json_extract(${alias}.payload_json,'$.body'))=1`);
+        args.push(filter.search.mode, filter.search.text);
+    }
     return { sql: terms.length ? terms.join(' AND ') : '1', args };
 }
 function pageRows(rows, page, decode) {
@@ -525,12 +551,28 @@ export function createSqliteDriver(db) {
     const all = (sql, args = []) => db.prepare(sql).all(...args);
     const one = (sql, args = []) => db.prepare(sql).get(...args);
     const run = (sql, args = []) => Number(db.prepare(sql).run(...args).changes);
+    let searchRegistered = false;
+    function selectActivity(filter) {
+        if (filter.search !== undefined && !searchRegistered) {
+            const patterns = new Map();
+            db.function('square_search', { deterministic: true }, (mode, text, index, actor, body) => {
+                const key = encode([mode, text]);
+                let pattern = patterns.get(key);
+                if (pattern === undefined) {
+                    pattern = compileSearchPattern(string(text), mode === 'literal');
+                    patterns.set(key, pattern);
+                }
+                return Number([formatActivityId(integer(index)), decoded(actor, true), body === null ? '' : string(body)]
+                    .some(field => pattern.test(field)));
+            });
+            searchRegistered = true;
+        }
+        return activitySelection(filter);
+    }
     const owner = (requested) => read.participant(requested)?.name ?? requested;
     const attentionRows = (condition, args) => all(`SELECT t.*,p.name_json FROM attention t JOIN participants p ON p.name_key_json=t.listener_key_json WHERE ${condition} ORDER BY t.since_index`, args).map(attention);
     function directedSelection(recipient, filter) {
-        const p = read.participant(recipient), base = activitySelection({
-            afterIndex: filter.afterIndex, beforeIndex: filter.beforeIndex, throughIndex: filter.throughIndex, actors: filter.senders
-        });
+        const p = read.participant(recipient), base = selectActivity({ ...filter, actors: filter.senders });
         base.sql += ' AND d.recipient_key_json=?';
         base.args.push(p ? key(p.name) : '');
         if (filter.unseenOnly) {
@@ -539,27 +581,6 @@ export function createSqliteDriver(db) {
         }
         if (filter.attentionOnly)
             base.sql += " AND d.route IN ('mention','reply','bell')";
-        if (filter.metadataMatch !== undefined) {
-            // Walk object keys rather than JSON-path strings: dots, quotes and array-like
-            // keys are literal, and arrays must never act as metadata objects.
-            base.sql += ` AND NOT EXISTS (
-                SELECT 1 FROM json_each(?) field WHERE NOT EXISTS (
-                    WITH RECURSIVE walk(value,type,depth) AS (
-                        SELECT json_extract(a.payload_json,'$.metadata'),json_type(a.payload_json,'$.metadata'),0
-                        UNION ALL
-                        SELECT child.value,child.type,walk.depth+1
-                        FROM walk JOIN json_each(CASE WHEN walk.type='object' THEN walk.value ELSE '{}' END) child
-                          ON child.key=json_extract(field.value,'$.path['||walk.depth||']')
-                        WHERE walk.depth<json_array_length(field.value,'$.path')
-                    )
-                    SELECT 1 FROM walk WHERE depth=json_array_length(field.value,'$.path')
-                      AND (type=json_type(field.value,'$.equals')
-                        OR type IN ('integer','real') AND json_type(field.value,'$.equals') IN ('integer','real'))
-                      AND value IS json_extract(field.value,'$.equals')
-                )
-            )`;
-            base.args.push(encode(filter.metadataMatch.fields));
-        }
         return base;
     }
     function directedHead(row, recipient) {
@@ -625,7 +646,7 @@ export function createSqliteDriver(db) {
             return r ? activity(r) : undefined;
         },
         activityHeads(filter, page) {
-            const s = activitySelection(filter), limit = pageLimit(page);
+            const s = selectActivity(filter), limit = pageLimit(page);
             return pageRows(all(`SELECT a.act_index,a.at,a.kind,a.actor_json,a.actor_key_json,a.reach,a.reply_index FROM activities a WHERE ${s.sql} ORDER BY a.act_index ${page.edge === 'newest' ? 'DESC' : 'ASC'} LIMIT ?`, [...s.args, limit]), page, head);
         },
         activities(indexes) {
@@ -633,7 +654,7 @@ export function createSqliteDriver(db) {
             return immutable(all('SELECT * FROM activities WHERE act_index IN (SELECT value FROM json_each(?)) ORDER BY act_index', [encode(indexes)]).map(activity));
         },
         activityCount(filter) {
-            const s = activitySelection(filter);
+            const s = selectActivity(filter);
             return integer(one(`SELECT COUNT(*) AS n FROM activities a WHERE ${s.sql}`, s.args).n);
         },
         contextIndexes(centers, before, after) {

package/dist/square-tools.js

@@ -28,6 +28,16 @@ export function squareToolsEnabled(env = process.env) {
     throw new SquareError('invalid_args', 'Invalid SQUARE_TOOLS: expected 0, 1, true, false, or none.');
 }
 export const SQUARE_TOOL_INSTRUCTIONS = 'Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.';
+function historyToolQuery({ grep, fixed, before, after, ...query }) {
+    if (grep !== undefined && fixed !== undefined)
+        throw new SquareError('invalid_args', 'Use grep or fixed, not both.');
+    if (before !== undefined && after !== undefined)
+        throw new SquareError('invalid_args', 'Use before or after, not both.');
+    return { ...query,
+        search: grep !== undefined ? { text: grep, mode: 'regex' } : fixed === undefined ? undefined : { text: fixed, mode: 'literal' },
+        cursor: after !== undefined ? { id: after, direction: 'after' } : before === undefined ? undefined : { id: before, direction: 'before' },
+    };
+}
 const target = z.string().describe('The participant to turn toward or away from.');
 export const SQUARE_TOOLS = [
     tool('join', 'Step into the square under your name. Do this once before you speak or catch. You arrive seeing what was said most recently.', {
@@ -65,7 +75,7 @@ export const SQUARE_TOOLS = [
         fixed: z.string().optional().describe('Only activities containing this exact text.'),
         from: stringArray.optional().describe('Only what these participants said.'),
         mention: z.string().optional().describe('Only what was addressed to this participant.'),
-    }, (square, args, control) => square.history({ ...args, observe: true }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: args }))),
+    }, (square, args, control) => square.history({ ...historyToolQuery(args), observe: true }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: historyToolQuery(args) }))),
     tool('attention', 'Turn toward someone or away from them, from now on. Listen: hear everything they say, even to others. Unlisten: stop listening without clearing an ignore; mentions and replies still reach you unless ignored. Ignore: hear nothing from them but bells. What was already said stays as it was.', {
         as: participant, action: z.enum(['listen', 'unlisten', 'ignore']).describe('"listen", "unlisten" or "ignore". Listening again ends an ignore.'), target,
     }, async (square, { as, action, target }, control, identity) => {

package/dist/views.d.ts

@@ -9,7 +9,7 @@ export declare const NON_READ: readonly ["join", "done", "say", "listen", "ignor
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function toPerceivedActivity(facts: SquareRead, stored: StoredAct, viewer: string): PerceivedActivity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
-/** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
+/** History adds archive context and ordering to the shared storage-side query predicates. */
 export declare function selectHistory(facts: SquareRead, query: HistoryQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
     continuation?: HistoryContinuation | undefined;
     activities: StoredAct[];

package/dist/views.js

@@ -3,7 +3,7 @@ import { compareParticipantActivity, coreParticipants, resolveKnownName, unreadA
 import { SquareError, nameKey } from './model.js';
 import { inSquareCount } from './runtime.js';
 import { perceiveActivity } from './perception-projection.js';
-import { compileSearchPattern } from './search.js';
+import { activityQueryFilter } from './activity-query.js';
 const PAGE_SIZE = 100;
 export const HISTORY_DEFAULT_LIMIT = 10;
 export const HISTORY_MAX_LIMIT = 100;
@@ -34,30 +34,26 @@ export function parseRequiredActivityId(id) {
         throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
     return index;
 }
-/** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
+/** History adds archive context and ordering to the shared storage-side query predicates. */
 export function selectHistory(facts, query, limit, kinds, presentation = true) {
-    if (query.before !== undefined && query.after !== undefined)
-        throw new SquareError('invalid_args', 'History cannot combine before and after cursors');
-    const afterIndex = query.after === undefined ? undefined : parseRequiredActivityId(query.after);
-    const beforeIndex = query.before === undefined ? undefined : parseRequiredActivityId(query.before);
-    const actors = (query.from ?? []).map((name) => resolveKnownName(facts, name));
+    const shared = activityQueryFilter(query, ['observe', 'order', 'mention', 'since', 'contextBefore', 'contextAfter']);
+    const { afterIndex } = shared;
     const recipient = query.mention == null ? undefined : resolveKnownName(facts, query.mention);
-    const pattern = query.grep ?? query.fixed;
-    const search = pattern === undefined || pattern === '' ? undefined : compileSearchPattern(pattern, query.grep === undefined);
     if (limit !== null && (!Number.isSafeInteger(limit) || limit < 1))
         throw new SquareError('invalid_args', 'History limit must be a positive integer');
     const filter = {
-        ...(actors.length === 0 ? {} : { actors }), afterIndex, beforeIndex, afterAt: query.since,
-        ...(query.at?.length ? { indexes: facts.contextIndexes(query.at.map(parseRequiredActivityId), query.contextBefore ?? 0, query.contextAfter ?? 0) } : {}),
-        kinds: search === undefined ? kinds : ['say', 'done'],
+        ...shared, afterAt: query.since,
+        ...(shared.indexes === undefined ? {} : { indexes: facts.contextIndexes(shared.indexes, query.contextBefore ?? 0, query.contextAfter ?? 0) }),
+        kinds: query.search === undefined ? kinds : ['say', 'done'],
     };
     let selected, totalMatches, publicBefore = false, publicAfter = false;
-    if (recipient === undefined && search === undefined && limit !== null && limit <= PAGE_SIZE) {
+    if (recipient === undefined && limit !== null && limit <= PAGE_SIZE) {
         selected = facts.activityHeads(filter, { edge: afterIndex === undefined ? 'newest' : 'oldest', limit }).items;
         totalMatches = facts.activityCount(filter);
         if (presentation) {
             const publicHeads = selected.filter((head) => ARCHIVE.has(head.kind));
-            const publicFilter = { ...filter, kinds: [...ARCHIVE] };
+            const publicFilter = { ...filter, kinds: filter.kinds === undefined
+                    ? [...ARCHIVE] : filter.kinds.filter(kind => ARCHIVE.has(kind)) };
             publicBefore = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, beforeIndex: publicHeads[0].index }) > 0;
             publicAfter = publicHeads.length > 0 && facts.activityCount({ ...publicFilter, afterIndex: publicHeads.at(-1).index }) > 0;
         }
@@ -69,13 +65,10 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
         while (true) {
             const source = recipient === undefined
                 ? facts.activityHeads({ ...filter, afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE })
-                : facts.directed(recipient, { afterIndex: cursor, beforeIndex }, { edge: 'oldest', limit: PAGE_SIZE });
+                : facts.directed(recipient, { ...filter, senders: filter.actors, afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
             const heads = recipient === undefined ? source.items : source.items.length === 0 ? []
                 : facts.activityHeads({ ...filter, indexes: source.items.map((head) => head.index).filter((index) => filter.indexes === undefined || filter.indexes.includes(index)) }, { edge: 'oldest', limit: PAGE_SIZE }).items;
-            const matches = search === undefined ? undefined : new Set(facts.activities(heads.map((head) => head.index)).filter((act) => [formatActivityId(act.index), act.actor ?? '', 'body' in act ? act.body ?? '' : ''].some((field) => search.test(field))).map((act) => act.index));
             for (const head of heads) {
-                if (matches !== undefined && !matches.has(head.index))
-                    continue;
                 totalMatches++;
                 if (presentation && ARCHIVE.has(head.kind)) {
                     firstPublic = Math.min(firstPublic, head.index);

package/guides/receive-primitive.md

@@ -81,8 +81,8 @@ primitive entrypoints without constructing Square.
 
 Square uses these functions for production landing, catch and `markSeen` (including explicit
 `Participant.ack`) against its existing activity, audience and receipt tables. `Participant.pending`
-uses the same addressed/unconsumed relation without writing receipts; optional metadata matching
-is applied by storage before the page limit. Numeric activity indexes stay
+uses the same addressed/unconsumed relation without writing receipts; its shared exact-ID, sender,
+metadata, search and cursor filters are applied by storage before the page limit. Numeric activity indexes stay
 internal keys; the primitive does not know Square IDs. Square retains validation,
 limits, filtering, perception, ownership, leases, hints and error mapping. The
 empty-catch read probe does not hydrate or acquire a writer; a nonempty probe is

package/guides/square-api.md

@@ -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,48 @@ 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
@@ -297,15 +339,14 @@ async function drain(endpoint: ChannelEndpoint, match: MetadataMatch) {
 }
 ```
 
-- `pending({match?, limit?} = {}, control?)` returns
+- `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 optional `MetadataMatch`
-  uses exactly the nested own-property scalar equality semantics described below (AND across fields).
-  Storage applies addressedness, consumption and metadata matching **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.
+- 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;
@@ -323,8 +364,10 @@ async function drain(endpoint: ChannelEndpoint, match: MetadataMatch) {
   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. Do not silently stop after the default
-  page or treat a snapshot `remaining: 0` as proof that concurrent producers have stopped. Query and
+  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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.97",
+  "version": "0.3.98",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.97",
+  "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.97",
+  "version": "0.3.98",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"