@astrosheep/square 0.3.85 → 0.3.87

package/dist/cli/context.js

@@ -2,6 +2,7 @@ import os from 'node:os';
 import { commandUsageHint } from '../help.js';
 import { parseParticipantList, validateName } from '../model.js';
 import { Square, squareClock } from '../square-api.js';
+import { harnessSessionSources } from '../participant-identity.js';
 export async function readStdin() {
     try {
         let content = '';
@@ -139,7 +140,30 @@ export function defaultContext(command, squarePath, name) {
     return { command, cwd: process.cwd(), env: { ...process.env }, squarePath, name, homeDir: os.homedir() };
 }
 export function squareInput(context) {
-    return { cwd: context.cwd, env: context.env, path: context.squarePath, participant: context.name };
+    const { body, wakeAddress } = commandIdentity(context.env);
+    return { cwd: context.cwd, env: context.env, path: context.squarePath, participant: context.name,
+        ...(body === undefined ? {} : { body }), ...(wakeAddress === undefined ? {} : { wakeAddress }) };
+}
+function commandIdentity(env) {
+    const coordinates = harnessSessionSources.flatMap(({ variable, channel, provider }) => {
+        const session = env[variable]?.trim();
+        return session === undefined || session === '' ? [] : [{ channel, session, native: provider !== undefined }];
+    });
+    const native = coordinates.filter((coordinate) => coordinate.native);
+    if (native.length > 1)
+        throw new Error('Multiple harness execution coordinates are present; select one explicit body.');
+    const paseo = coordinates.find((coordinate) => coordinate.channel === 'paseo');
+    // A child marker without a reliable agent id must never inherit the parent or Paseo identity.
+    if (env.CLAUDE_CODE_CHILD_SESSION === '1')
+        return {};
+    const selected = native[0] ?? paseo;
+    if (selected === undefined)
+        return {};
+    const body = { channel: selected.channel, session: selected.session };
+    const wakeAddress = selected.channel === 'codex'
+        ? { kind: 'codex-queue', address: { threadId: selected.session } }
+        : paseo === undefined ? undefined : { kind: 'paseo', address: { agentId: paseo.session } };
+    return { body, ...(wakeAddress === undefined ? {} : { wakeAddress }) };
 }
 /** Adapter lifetime only; each callback uses the actual public resource API. */
 export async function withSquare(context, run, control) {

package/dist/cli/express-presentation.d.ts

@@ -3,9 +3,11 @@ import type { OperationControl, ExpressOptions } from '../square-facade.js';
 export { renderExpression } from '../operation-presentation.js';
 export interface ActivityOptions extends Omit<ExpressOptions, 'reply'> {
     readonly reply?: string;
+    readonly metadataJson?: string;
+    readonly bodyProvided?: boolean;
 }
 export declare function saveActivityDraft(squarePath: string, name: string, body: string, now?: number): string;
 /** Retry choices are transport syntax, never a second admission decision. */
 export declare function activityRetryCommand(squarePath: string, name: string, opts: ActivityOptions, force?: boolean): string;
 /** Body adaptation, terminal IO and drafts only; Participant owns every attempt and wait. */
-export declare function executeExpression(open: (control?: OperationControl) => Promise<Square>, squarePath: string, requestedName: string | undefined, rawInput: string, opts: ActivityOptions): Promise<void>;
+export declare function executeExpression(open: (control?: OperationControl) => Promise<Square>, squarePath: string, requestedName: string | undefined, rawInput: string | undefined, opts: ActivityOptions): Promise<void>;

package/dist/cli/express-presentation.js

@@ -8,7 +8,7 @@ import { renderExpression } from '../operation-presentation.js';
 import { formatDuration } from '../time.js';
 export { renderExpression } from '../operation-presentation.js';
 export function saveActivityDraft(squarePath, name, body, now = Date.now()) {
-    const draftDir = path.join(path.dirname(squarePath), 'drafts');
+    const draftDir = path.join(/^[A-Za-z][A-Za-z0-9+.-]*:/.test(squarePath) ? process.cwd() : path.dirname(squarePath), 'drafts');
     fs.mkdirSync(draftDir, { recursive: true });
     const hash = crypto.createHash('sha256').update(body).digest('hex').slice(0, 8);
     const stamp = new Date(now).toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[:.]/g, '-');
@@ -37,7 +37,9 @@ export function activityRetryCommand(squarePath, name, opts, force = opts.force
     const reach = (opts.reach === 'bell' ? ' --bell' : '')
         + (opts.mentions ?? []).map((target) => ` --mention ${quoteShell(target)}`).join('')
         + (opts.noMention === true ? ' --no-mention' : '');
-    return `${participantCommandPrefix(squarePath, name)} express${force ? ' --force' : ''}${opts.noWait ? ' --no-wait' : ''}${reach}${replyArgument(opts.reply)} -`;
+    const metadata = opts.metadataJson === undefined ? '' : ` --metadata ${quoteShell(opts.metadataJson)}`;
+    const body = opts.bodyProvided === false ? '' : ' -';
+    return `${participantCommandPrefix(squarePath, name)} express${force ? ' --force' : ''}${opts.noWait ? ' --no-wait' : ''}${reach}${metadata}${replyArgument(opts.reply)}${body}`;
 }
 /** Body adaptation, terminal IO and drafts only; Participant owns every attempt and wait. */
 export async function executeExpression(open, squarePath, requestedName, rawInput, opts) {
@@ -54,8 +56,9 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
         const participant = await square.participant(requestedName);
         name = participant.name;
         attempted = true;
-        const outcome = await participant.express(rawInput.replace(/\r\n/g, '\n').trim(), {
-            ...opts, reply: opts.reply, observe: true,
+        const { metadataJson: _metadataJson, bodyProvided: _bodyProvided, ...expressOptions } = opts;
+        const outcome = await participant.express(rawInput === undefined ? undefined : rawInput.replace(/\r\n/g, '\n').trim(), {
+            ...expressOptions, reply: opts.reply, observe: true,
         }, {
             signal: controller.signal,
             onProgress(progress) {
@@ -75,7 +78,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
         const detail = error?.operation;
         name = detail?.participant ?? name ?? 'participant';
         // This MUST precede recovery: even an unreadable artifact cannot eat the raw body.
-        const draftPath = saveActivityDraft(squarePath, name, rawInput);
+        const draftPath = saveActivityDraft(squarePath, name, rawInput ?? '');
         if (square === undefined)
             square = await open().catch(() => undefined);
         const fresh = await square?.recovery(name).catch(() => undefined);
@@ -85,6 +88,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
             && detail?.expressEffect !== 'landed' && detail?.expressEffect !== 'unknown'
             && (!attempted || detail?.expressEffect === 'unsent' || (isSquareError(error) && error.facts?.activityUnsent === true));
         const retryCommand = activityRetryCommand(squarePath, name, opts);
+        const retryInput = opts.bodyProvided === false ? retryCommand : `${retryCommand} < ${quoteShell(draftPath)}`;
         const exitCode = (code) => { process.exitCode = controller.signal.aborted ? 130 : code; };
         if (!confirmedUnsent) {
             process.stderr.write(renderActivityUncertain({ ...output, landedId: landedId ?? detail?.landedId,
@@ -94,8 +98,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
         }
         if (isSquareError(error)) {
             if (error.code === 'behind' && fresh?.activitySummaries !== undefined) {
-                process.stdout.write(renderActivityBlocked({ ...output, retryCommand,
-                    forceCommand: activityRetryCommand(squarePath, name, opts, true),
+                process.stdout.write(renderActivityBlocked({ ...output, retryCommand: retryInput,
                     activitySummaries: fresh.activitySummaries.map((summary) => ({ ...summary, previews: [...summary.previews] })),
                 }));
                 exitCode(1);
@@ -109,7 +112,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
                 return;
             }
             if (error.code === 'held' || error.code === 'throttled') {
-                process.stdout.write(renderExpressNoWait({ ...output, reason: error.code, retryCommand,
+                process.stdout.write(renderExpressNoWait({ ...output, reason: error.code, retryCommand: retryInput,
                     delayMs: error.facts?.retryAfterMs ?? 1, holder: error.facts?.holder, holdReason: error.facts?.holdReason,
                 }));
                 exitCode(1);
@@ -118,7 +121,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
             if (error.code === 'bell_quota') {
                 process.stdout.write(withPathOutput(squarePath, [
                     '✕ the bell stays quiet for now', `  · you can ring it again in ${formatDuration(error.facts?.retryAfterMs ?? 1)}`,
-                    `· draft kept: ${draftPath}`, '  · retry when the bell is ready:', `${retryCommand} < ${quoteShell(draftPath)}`,
+                    `· draft kept: ${draftPath}`, '  · retry when the bell is ready:', retryInput,
                 ].join('\n'), output));
                 exitCode(1);
                 return;
@@ -144,7 +147,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
             if (repair) {
                 lines.push(participantsRecoveryCommand(squarePath), reason === 'bell_mention_conflict'
                     ? '  · ring the bell without explicit mentions:'
-                    : '  · retry without explicit recipients:', `${activityRetryCommand(squarePath, name, { ...opts, mentions: [] })} < ${quoteShell(draftPath)}`);
+                    : '  · retry without explicit recipients:', `${activityRetryCommand(squarePath, name, { ...opts, mentions: [] })}${opts.bodyProvided === false ? '' : ` < ${quoteShell(draftPath)}`}`);
             }
             else if (error.code === 'invalid_args' || error.code === 'invalid_name') {
                 if (opts.mentions?.length)
@@ -155,10 +158,10 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
         }
         if (reason === 'invalid_reply') {
             const withoutReply = { ...opts, reply: undefined };
-            lines.push(`${commandPrefix(squarePath)} history --limit 10`, '  · choose a valid --reply from history, or send without a reply using this repair:', `${activityRetryCommand(squarePath, name, withoutReply)} < ${quoteShell(draftPath)}`);
+            lines.push(`${commandPrefix(squarePath)} history --limit 10`, '  · choose a valid --reply from history, or send without a reply using this repair:', `${activityRetryCommand(squarePath, name, withoutReply)}${withoutReply.bodyProvided === false ? '' : ` < ${quoteShell(draftPath)}`}`);
         }
         else if (!repair) {
-            lines.push('  · correct the problem above before retrying; keep your intended recipients and reply:', `${retryCommand} < ${quoteShell(draftPath)}`);
+            lines.push('  · correct the problem above before retrying; keep your intended recipients and reply:', `${retryInput}`);
         }
         process.stderr.write(formatRefusal(squarePath, lines, output));
         exitCode(2);

package/dist/cli/mcp-server-command.js

@@ -1,4 +1,4 @@
-import { fail } from './context.js';
+import { fail, squareInput } from './context.js';
 export const mcpServerCommand = {
     parse(argv) {
         if (argv.length > 0)
@@ -7,7 +7,7 @@ export const mcpServerCommand = {
     },
     async execute(_intent, context) {
         const { runSquareMcpStdio } = await import('../mcp.js');
-        await runSquareMcpStdio({ cwd: context.cwd, env: context.env, path: context.squarePath, participant: context.name });
+        await runSquareMcpStdio(squareInput(context));
     },
     present() { },
 };

package/dist/cli/observation-commands.js

@@ -122,7 +122,7 @@ export const streamCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         if (!intent.ndjson) {
-            process.stderr.write(`✕ interactive stream was removed\nsquare --location ${quoteShell(path.resolve(context.cwd, squarePath))} stream --ndjson\n`);
+            process.stderr.write(`✕ interactive stream was removed\nsquare --location ${quoteShell(/^[A-Za-z][A-Za-z0-9+.-]*:/.test(squarePath) ? squarePath : path.resolve(context.cwd, squarePath))} stream --ndjson\n`);
             process.exitCode = 2;
             return;
         }
@@ -408,6 +408,7 @@ function jsonLine(sayNumbers, item) {
         body: 'body' in act && typeof act.body === 'string' ? act.body : '',
         number: act.kind === 'say' ? sayNumbers[act.index] : null,
         mentions: act.kind === 'say' ? [...(act.mentions ?? [])] : [],
+        metadata: act.kind === 'say' ? act.metadata ?? null : null,
         reach: act.kind === 'say' ? act.reach ?? null : null,
         reply: act.kind === 'say' && act.reply !== undefined ? formatActivityId(act.reply) : null,
     });

package/dist/cli/registry.js

@@ -1,6 +1,5 @@
 import { buildCommand, doneCommand, expressCommand, holdCommand, ignoreCommand, joinCommand, listenCommand, listeningCommand, resumeCommand, unlistenCommand } from './square-commands.js';
 import { doctorCommand, migrateCommand } from './maintenance-commands.js';
-import { ledgerCommand } from './ledger-command.js';
 import { harnessCommand, installCommand, uninstallCommand } from './harness-command.js';
 import { helpCommand, versionCommand } from './meta-commands.js';
 import { mcpServerCommand } from './mcp-server-command.js';
@@ -28,7 +27,6 @@ export const commandRegistry = [
     { names: ['harness'], spec: harnessCommand },
     { names: ['doctor'], spec: doctorCommand },
     { names: ['migrate'], spec: migrateCommand },
-    { names: ['ledger'], spec: ledgerCommand },
     { names: ['history'], spec: historyCommand },
     { names: ['status'], spec: statusCommand },
     { names: ['participants'], spec: participantsCommand },

package/dist/cli/square-commands.d.ts

@@ -1,5 +1,5 @@
 import { type BuildOptions, type HardCap } from '../model.js';
-import type { Reach } from '../square-facade.js';
+import type { Reach, ActivityMetadata } from '../square-facade.js';
 import { type CommandSpec } from './context.js';
 interface BuildIntent {
     options: BuildOptions & {
@@ -11,13 +11,15 @@ interface JoinIntent {
     kick: boolean;
 }
 interface ActivityIntent {
-    activity: string;
+    activity?: string;
     force: boolean;
     noWait: boolean;
     noMention: boolean;
     mentions: string[];
     reach?: Reach;
     reply?: string;
+    metadata?: ActivityMetadata;
+    metadataJson?: string;
 }
 interface BodyIntent {
     body?: string;

package/dist/cli/square-commands.js

@@ -87,6 +87,8 @@ function parseActivity(argv, context) {
     let noMention = false;
     const mentions = [];
     let reply;
+    let metadata;
+    let metadataJson;
     const bodyArgs = [];
     for (let index = 0; index < argv.length; index++) {
         const argument = argv[index];
@@ -108,25 +110,38 @@ function parseActivity(argv, context) {
             reply = requireValue(argv, index, argument);
             index += 1;
         }
+        else if (argument === '--metadata') {
+            metadataJson = requireValue(argv, index, argument);
+            try {
+                metadata = JSON.parse(metadataJson);
+            }
+            catch {
+                fail('✕ invalid --metadata: expected JSON');
+            }
+            index += 1;
+        }
         else
             bodyArgs.push(argument);
     }
     const reach = bell ? 'bell' : undefined;
-    if (bodyArgs.length !== 1) {
-        if (bodyArgs.length === 0 && !process.stdin.isTTY)
+    if (bodyArgs.length > 1)
+        fail("express accepts one body argument (a quoted string or '-')");
+    if (bodyArgs.length === 0 && metadataJson === undefined) {
+        if (!process.stdin.isTTY)
             bodyArgs.push('-');
         else
-            fail("express requires a body argument (a quoted string or '-' with piped stdin)");
+            fail("express requires a body argument or --metadata <json>");
     }
-    return { activity: bodyArgs[0], force, noWait, noMention, mentions, reach, reply };
+    return { activity: bodyArgs[0], force, noWait, noMention, mentions, reach, reply, metadata, metadataJson };
 }
 export const expressCommand = {
     parse: parseActivity,
     async execute(intent, context) {
-        const rawInput = await resolveBody(intent.activity);
+        const rawInput = intent.activity === undefined ? undefined : await resolveBody(intent.activity);
         await executeExpression((control) => Square.at(squareInput(context), control), requireSquarePath(context), context.name, rawInput, {
             force: intent.force, noWait: intent.noWait, noMention: intent.noMention,
-            mentions: intent.mentions, reach: intent.reach, reply: intent.reply,
+            mentions: intent.mentions, reach: intent.reach, reply: intent.reply, metadata: intent.metadata,
+            metadataJson: intent.metadataJson, bodyProvided: intent.activity !== undefined,
         });
     },
     present: () => { },

package/dist/codex-hook.d.ts

@@ -1,5 +1,5 @@
-import type { InboxMembership } from './model.js';
-import type { WakeAdapter } from './delivery.js';
+import type { Body, PendingMembership } from './model.js';
+import type { WakeTransports } from './notifications.js';
 export interface CodexHookInput {
     session_id?: unknown;
     hook_event_name?: unknown;
@@ -10,6 +10,6 @@ export type HookTrace = (line: string) => void;
 /** Overall hook budget: Codex kills the hook at its configured 5s timeout, so the hook must
  * bound every wait/retry itself and exit with a readable stage trace before that. */
 export declare const CODEX_HOOK_BUDGET_MS = 4500;
-export declare function codexHookResponse(input: CodexHookInput, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, deliveryAdapters?: WakeAdapter[], trace?: HookTrace): Promise<object | undefined>;
+export declare function codexHookResponse(input: CodexHookInput, lookup?: (identity: Body, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<PendingMembership[]> | PendingMembership[], env?: NodeJS.ProcessEnv, deliveryTransports?: WakeTransports, trace?: HookTrace): Promise<object | undefined>;
 export declare function runCodexHook(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;
 export declare function runCodexHookAsync(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;

package/dist/codex-hook.js

@@ -15,7 +15,7 @@ function hookBudgetMs(env) {
     const configured = Number(env.SQUARE_CODEX_HOOK_BUDGET_MS ?? CODEX_HOOK_BUDGET_MS);
     return Number.isFinite(configured) && configured > 0 ? configured : CODEX_HOOK_BUDGET_MS;
 }
-export async function codexHookResponse(input, lookup = sessionInbox, env = process.env, deliveryAdapters, trace = defaultTrace) {
+export async function codexHookResponse(input, lookup = sessionInbox, env = process.env, deliveryTransports, trace = defaultTrace) {
     if (typeof input.session_id !== 'string' || input.session_id === '')
         return undefined;
     if (typeof input.hook_event_name !== 'string')
@@ -38,20 +38,20 @@ export async function codexHookResponse(input, lookup = sessionInbox, env = proc
     await recordCodexBoundary(input.session_id, hookEventName === 'Stop' ? 'Stop' : 'non-stop', env, signal);
     stage('boundary-record');
     if (hookEventName === 'Stop') {
-        await sweepPrivilegedPending(cwd, env, deliveryAdapters, sweepDeadline, signal).catch(() => undefined);
+        await sweepPrivilegedPending(cwd, env, deliveryTransports, sweepDeadline, signal).catch(() => undefined);
         stage('sweep', signal.aborted ? 'aborted=true' : '');
         return undefined;
     }
     let response;
     try {
-        response = await presentPendingAtBoundary(input.session_id, (context) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } }), lookup, env, signal);
+        response = await presentPendingAtBoundary({ channel: 'codex', session: input.session_id }, (context) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: context } }), lookup, env, signal);
         stage('presentation', signal.aborted ? 'aborted=true' : '');
     }
     catch (error) {
         stage('presentation', `error=${error instanceof Error ? error.name : String(error)}`);
         response = undefined;
     }
-    await sweepPrivilegedPending(cwd, env, deliveryAdapters, sweepDeadline, signal).catch(() => undefined);
+    await sweepPrivilegedPending(cwd, env, deliveryTransports, sweepDeadline, signal).catch(() => undefined);
     stage('sweep', signal.aborted ? 'aborted=true' : '');
     return response;
 }

package/dist/codex-queue.d.ts

@@ -1,4 +1,4 @@
-import type { WakeAdapter, WakeAdapterResult } from './delivery.js';
+import type { WakeRequest, WakeOutcome, WakeTransportPort } from './ports.js';
 import { type WakeRoute } from './model.js';
 export interface CodexQueueRequest {
     threadId: string;
@@ -15,14 +15,13 @@ export declare function sendCodexQueue({ threadId, message }: CodexQueueRequest,
     env?: NodeJS.ProcessEnv;
     timeoutMs?: number;
 }): void;
-export interface CodexQueueAdapterOptions {
+export interface CodexQueueTransportOptions {
     env?: NodeJS.ProcessEnv;
     sendQueue?: typeof sendCodexQueue;
 }
-export declare class CodexQueueAdapter implements WakeAdapter {
+export declare class CodexQueueTransport implements WakeTransportPort {
     private readonly opts;
-    readonly kind: "codex-queue";
-    constructor(opts?: CodexQueueAdapterOptions);
-    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>, timeoutMs?: number): Promise<WakeAdapterResult>;
+    constructor(opts?: CodexQueueTransportOptions);
+    attempt(request: WakeRequest, timeoutMs: number, beforeSend: () => Promise<boolean>): Promise<WakeOutcome>;
 }
 export type { WakeRoute };

package/dist/codex-queue.js

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { codexQueueEligible } from './codex-boundary-state.js';
+import { wakePreview } from './delivery.js';
 export class CodexQueueSendError extends Error {
     kind;
     constructor(message, kind) {
@@ -30,16 +31,15 @@ export function sendCodexQueue({ threadId, message }, opts = {}) {
     const messageText = output || `codex queue exited with ${result.status ?? 'no status'}`;
     throw new CodexQueueSendError(messageText, classifyFailure(messageText));
 }
-export class CodexQueueAdapter {
+export class CodexQueueTransport {
     opts;
-    kind = 'codex-queue';
     constructor(opts = {}) {
         this.opts = opts;
     }
-    async dispatch(address, payload, beforeSend, timeoutMs = 5000) {
+    async attempt(request, timeoutMs, beforeSend) {
         const deadline = Date.now() + timeoutMs;
         const remainingMs = () => Math.max(0, deadline - Date.now());
-        const threadId = address.threadId?.trim();
+        const threadId = request.route.address.threadId?.trim();
         if (!threadId) {
             return { outcome: 'failed', unavailable: true, signature: 'invalid_address', message: 'Codex route has no thread id.', routeStale: true };
         }
@@ -53,8 +53,12 @@ export class CodexQueueAdapter {
                 retainRoute: true,
             };
         }
+        const payload = request.artifact === undefined ? undefined
+            : (await request.artifact.read((facts) => wakePreview(facts, request))).value;
+        if (payload === undefined)
+            return { outcome: 'not-capable', diagnostic: 'No pending Square activity to preview.' };
         if (!(await beforeSend()))
-            return { outcome: 'gate-rejected' };
+            return { outcome: 'not-capable' };
         if (!await codexQueueEligible(threadId, env)) {
             return {
                 outcome: 'failed',

package/dist/decisions.d.ts

@@ -1,4 +1,4 @@
-import { type Act, type Reach } from './model.js';
+import { type Act, type Reach, type ActivityMetadata } from './model.js';
 import type { SquareRead } from './ports.js';
 type TimedAct<K extends Act['kind'] = Act['kind']> = Extract<Act, {
     kind: K;
@@ -44,9 +44,10 @@ export type ActDecision = ({
 export declare function unreadActivitySummaries(facts: SquareRead, name: string, now: number): UnreadActivitySummary[];
 export declare function decideAct(facts: SquareRead, input: {
     name: string;
-    body: string;
+    body?: string;
     force: boolean;
     now: number;
+    metadata?: ActivityMetadata;
     mentions?: readonly string[];
     reach?: Reach;
     reply?: number;

package/dist/decisions.js

@@ -1,4 +1,4 @@
-import { SquareError, isSquareError, sameName, nameKey, validateName, } from './model.js';
+import { SquareError, isSquareError, sameName, nameKey, validateName, validateActivityMetadata, activityMetadataHasContent, } from './model.js';
 import { participantIdentity } from './participant-identity.js';
 import { UNREAD_BLOCK_GRACE_MS, freshWatchLease, readCursor, FACT_PAGE_SIZE, THROTTLE_WINDOW_MS } from './runtime.js';
 import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
@@ -85,11 +85,23 @@ export function unreadActivitySummaries(facts, name, now) {
     })).sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
 }
 export function decideAct(facts, input) {
-    const { now, force, body, reach, reply } = input;
+    const { now, force, reach, reply } = input;
+    let metadata;
+    try {
+        metadata = validateActivityMetadata(input.metadata);
+    }
+    catch (error) {
+        if (isSquareError(error))
+            error.facts = { ...error.facts, activityUnsent: true };
+        throw error;
+    }
+    if (input.body !== undefined && typeof input.body !== 'string')
+        throw activityRefusal('invalid_args', 'express body must be a string');
+    const body = input.body?.trim() === '' ? undefined : input.body;
+    if (body === undefined && !activityMetadataHasContent(metadata))
+        throw activityRefusal('invalid_args', 'express requires a non-empty body or metadata');
     const current = resolveStanding(facts, input.name, true);
     const name = current.name;
-    if (body.trim() === '')
-        throw activityRefusal('invalid_args', 'express body cannot be empty');
     const roster = facts.roster();
     const joinedNames = roster.filter((participant) => participant.joined).map((participant) => participant.name);
     if (reach === 'bell' && input.mentions?.length)
@@ -109,7 +121,7 @@ export function decideAct(facts, input) {
             throw activityRefusal('invalid_args', `${participantIdentity(requested)} is not standing in this square`, { reason: 'not_standing', targets: [requested] });
         addMention(resolved);
     }
-    const bodyMentions = reach === 'bell' || input.noMention === true ? [] : scanMentionCandidates(body);
+    const bodyMentions = reach === 'bell' || input.noMention === true ? [] : scanMentionCandidates(body ?? '');
     const unmatchedMentions = [];
     for (const token of bodyMentions) {
         const resolved = resolveMention(token, joinedNames);
@@ -150,7 +162,7 @@ export function decideAct(facts, input) {
         if (activitySummaries.length > 0 && activitySummaries[0].latestActivityAgeMs > UNREAD_BLOCK_GRACE_MS)
             return { type: 'blocked', activitySummaries };
     }
-    return { type: 'sent', act: { kind: 'say', actor: name, at: now, body, mentions: mentionNames,
+    return { type: 'sent', act: { kind: 'say', actor: name, at: now, ...(body === undefined ? {} : { body }), ...(metadata === undefined ? {} : { metadata }), mentions: mentionNames,
             ...(reach === undefined ? {} : { reach }), ...(reply === undefined ? {} : { reply }) },
         ...(unmatchedMentions.length === 0 ? {} : { unmatchedMentions }),
         ...(replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere }) };

package/dist/delivery-health.d.ts

@@ -1,5 +1,35 @@
 import { type DirectedNotificationRoute } from './delivery.js';
-import { type WakeAttempt, type WakeReleaseDiagnostic } from './wake-evidence.js';
+import type { DeliveryEvidence } from './ports.js';
+export interface WakeAttempt {
+    readonly nativeObservations?: readonly NonNullable<DeliveryEvidence['nativeObservations']>[number][];
+    readonly at: number;
+    readonly attention: {
+        readonly squarePath: string;
+        readonly recipient: string;
+        readonly actIndex: number;
+    };
+    readonly routeKind: import('./model.js').WakeRouteKind;
+    readonly outcome: 'accepted' | 'unknown' | 'failed';
+    readonly signature?: string;
+    readonly attemptN: number;
+    readonly session?: string;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
+}
+export interface WakeReleaseDiagnostic {
+    readonly at: number;
+    readonly attention: {
+        readonly squarePath: string;
+        readonly recipient: string;
+        readonly actIndex: number;
+    };
+    readonly routeKind?: import('./model.js').WakeRouteKind;
+    readonly attemptN?: number;
+    readonly session?: string;
+    readonly signature?: string;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
+}
 export type DeliveryHealthKind = 'awaiting' | 'wake-accepted' | 'wake-unknown' | 'presented-not-delivered' | 'unreachable';
 export interface DeliveryHealthItem {
     squarePath: string;
@@ -12,7 +42,7 @@ export interface DeliveryHealthItem {
     kind: DeliveryHealthKind;
     attempt?: WakeAttempt;
 }
-/** Purely classify current pending attention from the artifact and durable ledgers. */
+/** Classify current pending attention from the artifact's seats and delivery evidence. */
 export declare function classifyDeliveryHealth(squarePath: string, opts: {
     graceMs: number;
     now?: number;