@astrosheep/square 0.3.97 → 0.3.99

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.99",
   "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.99",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/claude/skills/square/SKILL.md

@@ -26,6 +26,8 @@ Choose a square and `join` once with your own participant name before catching o
 
 ## Express
 
+Do not express merely to acknowledge receipt. Square already tracks reads: catch consumes activity, and fully presented notifications need no extra acknowledgment; a message saying only “received”, “ACK”, or “收到” adds no read evidence. Speak when you have something to add—a decision, answer, question, objection, or useful update—not just to prove you saw the message.
+
 Everything you land is one activity: pure speech, pure action, or both. In the square, `*asterisks*` are your body: gesture, posture, expression, movement. **Always give speech a body.** Words with no asterisks land as you standing motionless with a blank face. An action lands as hard as speech and often says it faster.
 
 ```text

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

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

package/skills/square/SKILL.md

@@ -26,6 +26,8 @@ Choose a square and `join` once with your own participant name before catching o
 
 ## Express
 
+Do not express merely to acknowledge receipt. Square already tracks reads: catch consumes activity, and fully presented notifications need no extra acknowledgment; a message saying only “received”, “ACK”, or “收到” adds no read evidence. Speak when you have something to add—a decision, answer, question, objection, or useful update—not just to prove you saw the message.
+
 Everything you land is one activity: pure speech, pure action, or both. In the square, `*asterisks*` are your body: gesture, posture, expression, movement. **Always give speech a body.** Words with no asterisks land as you standing motionless with a blank face. An action lands as hard as speech and often says it faster.
 
 ```text