@astrosheep/square 0.3.69 → 0.3.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.69",
+  "version": "0.3.71",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -10,9 +10,7 @@
     "dist",
     "guides",
     "skills/square",
-    "claude-plugin",
-    "extensions",
-    "codex-plugin"
+    "plugins"
   ],
   "scripts": {
     "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist',{recursive:true,force:true})\"",
@@ -60,8 +58,8 @@
       "default": "./dist/paseo.js"
     },
     "./server": {
-      "types": "./dist/opencode.d.ts",
-      "default": "./dist/opencode.js"
+      "types": "./dist/plugins/opencode/index.d.ts",
+      "default": "./dist/plugins/opencode/index.js"
     },
     "./mcp": {
       "types": "./dist/mcp.d.ts",
@@ -72,7 +70,7 @@
   "types": "dist/index.d.ts",
   "pi": {
     "extensions": [
-      "./extensions/square-pi.js"
+      "./plugins/pi/square-pi.js"
     ],
     "skills": [
       "./skills"

package/{claude-plugin → plugins/claude}/.claude-plugin/plugin.json

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

package/{codex-plugin → plugins/codex}/.codex-plugin/plugin.json

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

package/plugins/opencode/delivery.ts

@@ -0,0 +1,149 @@
+import type { EvidenceRecord, NativeDeliveryEvidence, PresenceRecord } from '../../host-ledger.js';
+import type { SquareRead, WakeTransportPort } from '../../ports.js';
+import { nameKey } from '../../model.js';
+import { nativePendingPreview, observeSessionPending, sessionInbox } from '../../inbox.js';
+import { hostLedgerForEnv } from '../../registry.js';
+import { openSquare } from '../../open-square.js';
+import { closeOpenSquare } from '../../open-square.js';
+import { presentationSuppressesWake, projectPresentationEvidence } from '../../square-projections.js';
+import { presentPending } from '../../presentation-operations.js';
+import { deliverPending } from '../../delivery-operations.js';
+import { createWakeTransport } from '../../notifications.js';
+import { publishWakeRoute } from '../../routes.js';
+import { formatActivityId, parseActivityId } from '../../square-core.js';
+import { createNativeInputId, sendNativeText, type OpenCodeNativeSession } from '../../packages/agent-delivery/src/opencode-native.js';
+
+const routeKind = 'opencode-server' as const;
+type NativeRow = EvidenceRecord & { claimToken: string; nativeDelivery: Extract<NativeDeliveryEvidence, { harness: 'opencode' }> };
+export interface OpenCodeContextMessage { readonly id?: string; readonly role: string; readonly content: readonly { readonly type: string; readonly text?: string }[] }
+const key = (location: string, participant: string, index: number) => `${location}\0${nameKey(participant)}\0${index}`;
+
+/** The one native pending preview: the audience/catch/epoch fence before send and inside presentation. */
+function preview(facts: SquareRead, owner: PresenceRecord, index: number) {
+  return nativePendingPreview(facts, { location: owner.location, routeKind, sessionId: owner.session, participant: owner.participant, actIndex: index, epoch: owner.epoch, address: { sessionId: owner.session }, cancelledThrough: owner.cancelledThrough, now: Date.now() });
+}
+
+function createOpenCodeWakeTransport(target: OpenCodeNativeSession, env: NodeJS.ProcessEnv, lifetime: AbortSignal): WakeTransportPort {
+  const ledger = hostLedgerForEnv(env);
+  return {
+    probe: async (route) => !lifetime.aborted && route.kind === routeKind && route.sessionId === target.sessionId && route.address.sessionId === target.sessionId,
+    async attempt(request, timeoutMs, beforeSend) {
+      const signal = AbortSignal.any([lifetime, AbortSignal.timeout(timeoutMs)]);
+      const deadline = Date.now() + timeoutMs;
+      // Start the native call under the ownership fence, but await it OUTSIDE: prompt may
+      // enter our context hook synchronously and that hook needs the same ownership lock.
+      const started = await ledger.withClaimLock(async () => {
+        if (signal.aborted || request.route.sessionId !== target.sessionId || !request.claimToken
+          || !await (beforeSend?.() ?? Promise.resolve(true))) return undefined;
+        const owner = (await ledger.listPresence({ location: request.location, participant: request.participant, session: target.sessionId }))
+          .find((binding) => binding.channel === 'opencode' && binding.epoch === request.route.epoch);
+        const index = parseActivityId(request.activity);
+        if (!owner || index === undefined) return undefined;
+        const square = await openSquare(owner.location, { hostLedger: ledger, env, signal });
+        try {
+          const { value: prepared } = await square.artifact.read((facts) => preview(facts, owner, index), signal);
+          if (!prepared) return undefined;
+          const row: NativeRow & { routeKind: typeof routeKind } = { location: owner.location, participant: owner.participant, session: target.sessionId,
+            activity: request.activity, kind: 'wake', outcome: 'dispatching', routeKind, attemptN: request.attemptN, claimToken: request.claimToken,
+            nativeDelivery: { harness: 'opencode', epoch: owner.epoch ?? 0, inputId: createNativeInputId(), payload: prepared.payload } };
+          if (!await ledger.prepareNativeWake(row) || !await (beforeSend?.() ?? Promise.resolve(true)) || signal.aborted
+            || (await square.artifact.read((facts) => preview(facts, owner, index)?.payload, signal)).value !== prepared.payload) return undefined;
+          return { sending: sendNativeText(target, prepared.payload, { inputId: row.nativeDelivery.inputId, delivery: 'steer',
+            timeoutMs: Math.max(1, deadline - Date.now()), signal }) };
+        } finally { await closeOpenSquare(square); }
+      }, signal);
+      if (!started) return { outcome: 'not-capable', diagnostic: 'OpenCode attention, binding or local delivery generation changed before send.' };
+      const result = await started.sending;
+      if (result.state === 'accepted') return { outcome: 'accepted' };
+      if (result.state === 'unavailable') return { outcome: 'failed', unavailable: true, retainRoute: true, signature: result.code };
+      return { outcome: 'unknown', signature: result.code };
+    },
+  };
+}
+
+/** Only the matching prepared primary context authorizes presentation, never admission. */
+export async function observeOpenCodeContext(sessionId: string, messages: readonly OpenCodeContextMessage[], env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void> {
+  const ledger = hostLedgerForEnv(env);
+  await ledger.withClaimLock(async () => {
+    if (signal.aborted) return;
+    const rows = (await ledger.listEvidence({ kind: 'wake', session: sessionId })).filter((row): row is NativeRow =>
+      row.nativeDelivery?.harness === 'opencode' && !!row.claimToken && ['dispatching', 'unknown', 'accepted'].includes(row.outcome));
+    for (const row of rows) {
+      if (signal.aborted || !messages.some((message) => message.id === row.nativeDelivery.inputId && message.role === 'user'
+        && message.content.every((part) => part.type === 'text' && typeof part.text === 'string')
+        && message.content.map((part) => part.text).join('') === row.nativeDelivery.payload)) continue;
+      const owner = (await ledger.listPresence({ location: row.location, participant: row.participant, session: sessionId }))
+        .find((binding) => binding.channel === 'opencode' && binding.epoch === row.nativeDelivery.epoch);
+      const index = parseActivityId(row.activity);
+      if (!owner || index === undefined) continue;
+      const square = await openSquare(row.location, { hostLedger: ledger, env, signal });
+      try {
+        const { value: prepared } = await square.artifact.read((facts) => preview(facts, owner, index), signal);
+        if (!prepared || prepared.payload !== row.nativeDelivery.payload) continue;
+        const prior = await projectPresentationEvidence({ hostLedger: ledger, location: row.location, participant: row.participant, sessionId, activity: row.activity });
+        if (presentationSuppressesWake(prior)) continue;
+        await presentPending({ artifact: square.artifact, hostLedger: ledger, location: row.location, participant: row.participant, session: sessionId,
+          activity: row.activity, sink: { present() {} }, markSeen: !prepared.clipped, signal,
+          current: (facts) => !signal.aborted && preview(facts, owner, index)?.payload === row.nativeDelivery.payload });
+      } finally { await closeOpenSquare(square); }
+    }
+  }, signal);
+}
+
+/** One existing observer and the existing dispatch owner; no second queue or evidence store. */
+export async function receiveOpenCodePending(target: OpenCodeNativeSession, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void> {
+  const ledger = hostLedgerForEnv(env);
+  const observer = await observeSessionPending(target.sessionId, env);
+  const excluded = new Set<string>();
+  const refreshExclusions = async () => {
+    excluded.clear();
+    const owners = await ledger.listPresence({ session: target.sessionId });
+    for (const row of await ledger.listEvidence({ kind: 'wake', session: target.sessionId })) {
+      const index = parseActivityId(row.activity);
+      const current = owners.some((owner) => owner.location === row.location && nameKey(owner.participant) === nameKey(row.participant) && owner.epoch === row.nativeDelivery?.epoch);
+      if (index !== undefined && (['accepted', 'unknown'].includes(row.outcome) || row.outcome === 'dispatching' && current && row.nativeDelivery?.harness === 'opencode')) excluded.add(key(row.location, row.participant, index));
+    }
+    for (const membership of await sessionInbox(target.sessionId, env, signal)) {
+      const owner = owners.find((binding) => binding.location === membership.squarePath && nameKey(binding.participant) === nameKey(membership.name));
+      for (const note of membership.notifications) if (note.actIndex <= (owner?.cancelledThrough ?? -1)) excluded.add(key(membership.squarePath, membership.name, note.actIndex));
+    }
+  };
+  const transport = createWakeTransport([], ledger, Date.now, { [routeKind]: createOpenCodeWakeTransport(target, env, signal) });
+  try {
+    await refreshExclusions();
+    let pending = await observer.wait(Infinity, { signal, excludeKeys: excluded });
+    while (!signal.aborted && pending.length > 0) {
+      let armed!: (value: boolean) => void;
+      const ready = new Promise<boolean>((resolve) => { armed = resolve; });
+      // Capture the next state edge BEFORE dispatch. Evidence failures alone do not retry.
+      const next = observer.wait(Infinity, { signal, excludeKeys: excluded, skipImmediate: true, onChangeArmed: armed })
+        .catch(() => { armed(false); return []; });
+      if (!await ready || signal.aborted) break;
+      for (const membership of pending) {
+        const square = await openSquare(membership.squarePath, { hostLedger: ledger, env, signal });
+        try {
+          for (const note of membership.notifications) {
+            if (signal.aborted || excluded.has(key(membership.squarePath, membership.name, note.actIndex))) continue;
+            await deliverPending({ artifact: square.artifact, hostLedger: ledger, transport, location: square.location, activity: formatActivityId(note.actIndex), now: Date.now() });
+          }
+        } finally { await closeOpenSquare(square); }
+      }
+      await refreshExclusions();
+      pending = await next;
+    }
+  } finally { observer.close(); }
+}
+
+export async function publishOpenCodeRoutes(sessionId: string, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<boolean> {
+  const ledger = hostLedgerForEnv(env);
+  return ledger.withClaimLock(async () => {
+    const owners = (await ledger.listPresence({ session: sessionId })).filter((binding) => binding.channel === 'opencode');
+    for (const owner of owners) {
+      const square = await openSquare(owner.location, { hostLedger: ledger, env, signal });
+      try { await publishWakeRoute(square.artifact, { location: owner.location, participant: owner.participant, sessionId, channel: 'opencode',
+        kind: routeKind, address: { sessionId }, epoch: owner.epoch }, { requireCurrentSession: true }); }
+      finally { await closeOpenSquare(square); }
+    }
+    return owners.length > 0;
+  }, signal);
+}

package/plugins/opencode/index.ts

@@ -0,0 +1,136 @@
+import { automaticSessionStart, operationEnv } from '../../automatic-session.js';
+import { hostLedgerForEnv } from '../../registry.js';
+import { canonicalPath } from '../../canonical-path.js';
+import { openSquare } from '../../open-square.js';
+import { closeOpenSquare } from '../../open-square.js';
+import { Square } from '../../square-application.js';
+import { connectNative, type OpenCodeNativeSession, type OpenCodeSessionCapability } from '../../packages/agent-delivery/src/opencode-native.js';
+import { observeOpenCodeContext, publishOpenCodeRoutes, receiveOpenCodePending, type OpenCodeContextMessage } from './delivery.js';
+
+interface OpenCodePluginContext {
+  readonly app: { readonly version: string };
+  readonly location: { readonly directory: string; readonly project: { readonly id: string }; readonly workspaceID?: string };
+  readonly session: OpenCodeSessionCapability & {
+    hook(name: 'prompt', callback: (event: { sessionID: string }) => Promise<void>): Promise<unknown>;
+    hook(name: 'context', callback: (event: { sessionID: string; messages: OpenCodeContextMessage[] }) => Promise<void>): Promise<unknown>;
+  };
+  readonly event: { subscribe(options: { signal: AbortSignal }): AsyncIterable<{ type: string; data: { sessionID?: string; reason?: string } }> };
+}
+interface Receiver { readonly abort: AbortController; readonly running: Promise<void>; settled: boolean }
+
+/** Actual OpenCode 2.0.20 server plugin. Harness identity belongs to ctx, never process.env. */
+export default {
+  id: 'square',
+  async setup(ctx: OpenCodePluginContext): Promise<() => Promise<void>> {
+    if (ctx.app.version !== '2.0.20') return async () => {};
+    const env = { ...process.env };
+    const ledger = hostLedgerForEnv(env);
+    const lifetime = new AbortController();
+    const receivers = new Map<string, Receiver>(); // Operational handles only; presence owns membership.
+    const directory = await canonicalPath(ctx.location.directory);
+    let coordinating = Promise.resolve();
+    const coordinate = (operation: () => Promise<void>) => {
+      const task = coordinating.then(() => lifetime.signal.aborted ? undefined : operation());
+      coordinating = task.catch(() => {}); // Optional Square hooks must never fail primary request preparation.
+      return coordinating;
+    };
+    const stop = (sessionId: string) => {
+      const receiver = receivers.get(sessionId);
+      receiver?.abort.abort();
+      receivers.delete(sessionId);
+      return receiver?.running;
+    };
+    const validate = async (sessionId: string): Promise<OpenCodeNativeSession | undefined> => {
+      let info: unknown;
+      const target = await connectNative({ sessionId, timeoutMs: 3000, signal: lifetime.signal, session: {
+        async get(input) { info = await ctx.session.get(input); return info; },
+        prompt: (input) => ctx.session.prompt(input),
+      } }).catch(() => undefined);
+      const record = info as { projectID?: string; location?: { directory?: string; workspaceID?: string } } | undefined;
+      if (!target || !record?.location?.directory || record.projectID !== ctx.location.project.id
+        || record.location.workspaceID !== ctx.location.workspaceID
+        || await canonicalPath(record.location.directory) !== directory) return undefined;
+      return target;
+    };
+    const reconcile = async (activeSession?: string) => {
+      const candidates = new Set((await ledger.listPresence({})).filter((binding) => binding.channel === 'opencode').map((binding) => binding.session));
+      if (activeSession) candidates.add(activeSession);
+      for (const sessionId of candidates) {
+        if (lifetime.signal.aborted) return;
+        const target = await validate(sessionId);
+        if (!target) { stop(sessionId); continue; }
+        const scopedEnv = operationEnv('opencode', sessionId, env);
+        if (sessionId === activeSession) await automaticSessionStart('opencode', sessionId, directory, scopedEnv);
+        if (!await publishOpenCodeRoutes(sessionId, scopedEnv, lifetime.signal)) { stop(sessionId); continue; }
+        if (receivers.get(sessionId)?.settled === false) continue;
+        const abort = new AbortController();
+        const signal = AbortSignal.any([lifetime.signal, abort.signal]);
+        const receiver: Receiver = { abort, settled: false, running: receiveOpenCodePending(target, scopedEnv, signal).catch(() => {}).finally(() => { receiver.settled = true; }) };
+        receivers.set(sessionId, receiver);
+      }
+      for (const sessionId of receivers.keys()) if (!candidates.has(sessionId)) stop(sessionId);
+    };
+    const cancel = async (sessionId: string) => {
+      if (!receivers.has(sessionId)) return;
+      // Stop synchronously; persist the cutoff before allowing reconciliation to start fresh work.
+      stop(sessionId);
+      await ledger.withClaimLock(async () => {
+        for (const owner of (await ledger.listPresence({ session: sessionId })).filter((binding) => binding.channel === 'opencode')) {
+          const square = await openSquare(owner.location, { hostLedger: ledger, env, signal: lifetime.signal });
+          try { await ledger.suppressPresence(owner, (await square.artifact.read((facts) => facts.header().nextActIndex - 1, lifetime.signal)).value); }
+          finally { await closeOpenSquare(square); }
+        }
+      }, lifetime.signal);
+      await reconcile();
+    };
+    const end = async (sessionId: string) => {
+      stop(sessionId);
+      const memberships = (await ledger.listPresence({ session: sessionId })).filter((binding) => binding.channel === 'opencode');
+      for (const owner of memberships) {
+        const square = await Square.at({ path: owner.location, hostLedger: ledger, env: operationEnv('opencode', sessionId, env) });
+        try { await square.endOwnedSession(owner.participant, sessionId, owner.epoch); }
+        finally { await square.close(); }
+      }
+    };
+
+    await ctx.session.hook('prompt', (event) => coordinate(() => reconcile(event.sessionID)));
+    await ctx.session.hook('context', async (event) => {
+      await coordinate(() => reconcile(event.sessionID));
+      const receiver = receivers.get(event.sessionID);
+      if (!receiver || lifetime.signal.aborted) return;
+      await observeOpenCodeContext(event.sessionID, event.messages, operationEnv('opencode', event.sessionID, env),
+        AbortSignal.any([lifetime.signal, receiver.abort.signal])).catch(() => {});
+    });
+    const changes = await ledger.observeChanges();
+    changes.evidence.close(); // Manual joins activate an idle receiver; evidence already has a session observer.
+    const presenceLoop = (async () => {
+      while (!lifetime.signal.aborted) {
+        const baseline = await changes.presence.read(lifetime.signal);
+        await coordinate(() => reconcile());
+        await changes.presence.changed(baseline, Infinity, lifetime.signal);
+      }
+    })().catch(() => {});
+    const eventLoop = (async () => {
+      for await (const event of ctx.event.subscribe({ signal: lifetime.signal })) {
+        const sessionId = event.data.sessionID;
+        if (!sessionId) continue;
+        if (event.type === 'session.deleted') await coordinate(() => end(sessionId));
+        else if (event.type === 'session.moved') await coordinate(async () => { stop(sessionId); await reconcile(); });
+        else if (event.type === 'session.execution.interrupted' && event.data.reason === 'user') {
+          receivers.get(sessionId)?.abort.abort();
+          await coordinate(() => cancel(sessionId));
+        }
+      }
+    })().catch(() => {});
+    // Do not await any native prompt in setup: plugin activation itself is lazy.
+    return async () => {
+      lifetime.abort();
+      changes.presence.close();
+      const tasks = [presenceLoop, eventLoop, coordinating, ...[...receivers.keys()].map(stop)];
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try { await Promise.race([Promise.allSettled(tasks), new Promise<void>((resolve) => { timer = setTimeout(resolve, 3000); })]); }
+      finally { if (timer !== undefined) clearTimeout(timer); }
+      // Instance unload is not session deletion: retain memberships and uncertain correlations.
+    };
+  },
+};

package/plugins/paseo/OVERVIEW.md

@@ -0,0 +1,14 @@
+# Square
+
+Expandable Square context in the Paseo conversation. A compact card tells you
+who reached you and where. Expand it to see the original custom-message content,
+select text, or copy it in full. The card follows the active Paseo theme on
+desktop and mobile.
+
+Requires Paseo 0.11.2 or newer with custom-message tool rows (#6090). Square
+0.3.69 or newer supplies structured card headings. Older messages and joining
+context use a neutral “Square context” heading.
+
+The plugin changes presentation only. It does not send prompts or alter model
+context. If Square clipped a body before delivery, expansion shows that same
+preview and the command for reading the rest, not an additional fetch.

package/plugins/paseo/README.md

@@ -0,0 +1,54 @@
+# Square for Paseo
+
+A client-only presentation plugin for Square custom messages. No daemon restart,
+backend entry, extra notifications, or model-context changes.
+
+## Install from GitHub
+
+```bash
+paseo plugin install git:astrosheep-zero/square:plugins/paseo
+```
+
+Use `--ref <tag-or-branch>` to select an existing ref that contains the plugin
+directory. Square tags up to v0.3.69 do not contain it.
+
+Paseo supplies all runtime modules. No Git preparation step is needed. Plugins
+are trusted, unsandboxed code running inside the Paseo app.
+
+Requires Paseo >=0.11.2 with custom-message tool rows (#6090). Square 0.3.69+
+provides `details.items` for the collapsed heading. Messages without those
+details still expand to their original content.
+
+## Display
+
+Only synthetic `tool_call` items with `metadata.customType === "square"` and
+plain-text detail are projected into a card. Real tools, other custom messages,
+and unrecognized rows remain unchanged.
+
+The collapsed heading uses `metadata.details.items`; it never reverse-parses
+the content. Expansion shows `detail.text` verbatim, including fences, clipping
+notices, and catch commands. Copy content copies that exact string. It does not
+fetch extra activity or mark anything seen. Live events and fetched history use
+the same transformer.
+
+The card uses Paseo theme colors, selectable text, accessible expansion state,
+and compact layout on narrow displays. Removing the plugin restores Paseo's
+ordinary custom-message row.
+
+## Develop
+
+```bash
+cd plugins/paseo
+npm ci
+npm run typecheck
+npm test
+paseo plugin install "$PWD"
+```
+
+After editing an installed directory source:
+
+```bash
+paseo plugin reload square
+```
+
+No Paseo restart is needed. The plugin ID is `square`.

package/plugins/paseo/client/square-message.tsx

@@ -0,0 +1,106 @@
+import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
+import { copyText, Icon, useToast } from "@getpaseo/plugin/client/react-native";
+import { useMemo, useState } from "react";
+import { Platform, Pressable, Text, View } from "react-native";
+import { squareHeadline, type SquareMessageData } from "../shared/message";
+
+function withOpacity(color: string, opacity: number): string {
+  const hex = /^#([\da-f]{3}|[\da-f]{6})$/iu.exec(color);
+  if (hex === null) return color;
+  const value = hex[1]!.length === 3 ? [...hex[1]!].map((part) => part + part).join("") : hex[1]!;
+  const alpha = Math.round(opacity * 255).toString(16).padStart(2, "0");
+  return `#${value}${alpha}`;
+}
+
+export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<SquareMessageData>) {
+  const [expanded, setExpanded] = useState(false);
+  const toast = useToast();
+  const { text, items } = item.data;
+  const first = items?.[0];
+  const muted = theme.colors.foregroundMuted;
+  const foreground = theme.colors.foreground;
+  const padding = layout.compact ? 10 : 14;
+  const styles = useMemo(() => ({
+    marker: { color: theme.colors.accent, fontSize: 10, marginTop: 2 },
+    headline: { color: foreground, fontSize: 13, lineHeight: 19, flexShrink: 1 },
+    meta: { color: muted, fontSize: 11, lineHeight: 16, flexShrink: 1 },
+    bodyPanel: {
+      backgroundColor: theme.colors.surface1,
+      borderRadius: 12,
+      marginTop: 7,
+      marginLeft: 17,
+      overflow: "hidden" as const,
+    },
+    bodyText: {
+      color: foreground,
+      fontSize: 12,
+      lineHeight: 21,
+      fontFamily: Platform.OS === "ios" ? "Menlo" : "monospace",
+      paddingHorizontal: layout.compact ? 12 : 14,
+      paddingTop: 12,
+    },
+  }), [expanded, foreground, layout.compact, muted, theme.colors.accent, theme.colors.surface1]);
+
+  return (
+    <View>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={first !== undefined ? squareHeadline(first) : "Square context"}
+        aria-expanded={expanded}
+        onPress={() => setExpanded(value => !value)}
+        style={({ pressed }) => ({
+          flexDirection: "row",
+          alignItems: "flex-start",
+          gap: 7,
+          paddingVertical: 2,
+          opacity: pressed ? 0.6 : 1,
+        })}
+      >
+        <Text style={styles.marker}>■</Text>
+        <View style={{
+          flex: 1,
+          minWidth: 0,
+          flexDirection: layout.compact ? "column" : "row",
+          alignItems: layout.compact ? "flex-start" : "center",
+          gap: layout.compact ? 2 : 8,
+        }}>
+          <Text numberOfLines={layout.compact ? 2 : 1} style={styles.headline}>
+            {first !== undefined ? squareHeadline(first) : "Square context"}
+          </Text>
+          {first && <Text numberOfLines={1} style={styles.meta}>
+            {first.square}{items && items.length > 1 ? ` · +${items.length - 1} more` : ""}
+          </Text>}
+        </View>
+        <View style={{ marginTop: 3 }}><Icon name={expanded ? "ChevronDown" : "ChevronRight"} size={14} color={muted} /></View>
+      </Pressable>
+      {expanded && <View style={styles.bodyPanel}>
+        <Text selectable style={styles.bodyText}>{text}</Text>
+        <View style={{
+          marginHorizontal: layout.compact ? 12 : 14,
+          marginTop: 12,
+          borderTopWidth: 1,
+          borderTopColor: withOpacity(theme.colors.border, 0.55),
+          paddingVertical: 7,
+          flexDirection: "row",
+          justifyContent: "flex-end",
+        }}>
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="Copy Square content"
+            onPress={() => { void copyText(text).catch(() => toast.error("Could not copy Square content")); }}
+            style={({ pressed }) => ({
+              flexDirection: "row",
+              alignItems: "center",
+              gap: 5,
+              paddingHorizontal: 2,
+              opacity: pressed ? 0.6 : 1,
+            })}
+          >
+            <Icon name="Copy" size={12} color={muted} />
+            <Text style={{ color: muted, fontSize: 11 }}>Copy content</Text>
+          </Pressable>
+        </View>
+      </View>}
+    </View>
+  );
+}

package/plugins/paseo/client/transform.ts

@@ -0,0 +1,24 @@
+import type { PluginTimelineTransformerContribution } from "@getpaseo/plugin/client";
+import { squareCardDetailsSchema } from "../shared/message.ts";
+
+// Recognition is metadata-based, not a guess from a tool name or body text.
+// The same projection applies to live events and fetched history.
+export const transformSquareMessage: PluginTimelineTransformerContribution<"tool_call">["transform"] = ({ item }) => {
+  if (item.metadata?.synthetic !== true ||
+      item.metadata.customType !== "square" ||
+      item.detail.type !== "plain_text" ||
+      typeof item.detail.text !== "string") return;
+
+  const details = squareCardDetailsSchema.safeParse(item.metadata.details);
+  return {
+    items: [{
+      type: "plugin",
+      kind: "square-message",
+      version: 1,
+      data: {
+        text: item.detail.text,
+        ...(details.success ? { items: details.data.items } : {}),
+      },
+    }],
+  };
+};

package/plugins/paseo/index.client.tsx

@@ -0,0 +1,19 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { SquareMessage } from "./client/square-message";
+import { transformSquareMessage } from "./client/transform";
+import { squareMessageSchema } from "./shared/message";
+
+export default function contribute(client: PluginClientContext) {
+  client.addTimelineTransformer({
+    id: "square-message",
+    query: { itemType: "tool_call" },
+    transform: transformSquareMessage,
+  });
+  client.addTimelineRenderer({
+    kind: "square-message",
+    version: 1,
+    schema: squareMessageSchema,
+    Component: SquareMessage,
+  });
+  return () => {};
+}

package/plugins/paseo/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@astrosheep/square-paseo",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test test/*.test.ts"
+  },
+  "devDependencies": {
+    "@getpaseo/plugin": "0.11.2",
+    "@types/react": "~19.2.0",
+    "@types/node": "^22",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  }
+}

package/plugins/paseo/paseo-plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "square",
+  "name": "Square",
+  "requirements": {
+    "paseo": ">=0.11.2"
+  }
+}

package/plugins/paseo/shared/message.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+export const squareCardDetailsSchema = z.object({
+  items: z.array(z.object({
+    square: z.string(),
+    actor: z.string().optional(),
+    recipient: z.string().optional(),
+    route: z.enum(["mention", "reply", "attention", "bell"]).optional(),
+    description: z.string(),
+  })).min(1),
+});
+
+/** Human-facing summary; the stored description is Square's agent voice, and the human is not the recipient. */
+export function squareHeadline(item: z.output<typeof squareCardDetailsSchema>["items"][number]): string {
+  if (item.actor === undefined || item.route === undefined) return item.description;
+  const to = item.recipient;
+  switch (item.route) {
+    case "mention": return to === undefined ? `${item.actor} mentioned you` : `${item.actor} mentioned ${to}`;
+    case "reply": return to === undefined ? `${item.actor} replied to you` : `${item.actor} replied to ${to}`;
+    case "attention": return `New from ${item.actor}`;
+    case "bell": return `${item.actor} called everyone`;
+  }
+}
+
+export const squareMessageSchema = z.object({
+  text: z.string(),
+  items: squareCardDetailsSchema.shape.items.optional(),
+});
+export type SquareMessageData = z.output<typeof squareMessageSchema>;

package/{extensions → plugins/pi}/square-pi.js

@@ -1,10 +1,10 @@
 import path from 'node:path';
 
-import { presentPendingAtBoundary, renderPendingAtBoundary } from '../dist/boundary-presentation.js';
-import { automaticSessionEnd, automaticSessionStart } from '../dist/automatic-session.js';
-import { sessionInbox, observeSessionPending } from '../dist/inbox.js';
-import { renderAttentionDescription } from '../dist/attention-presentation.js';
-import { createPiReceiver, sendPiMessage } from '../dist/packages/agent-delivery/src/pi.js';
+import { presentPendingAtBoundary, renderPendingAtBoundary } from '../../dist/boundary-presentation.js';
+import { automaticSessionEnd, automaticSessionStart } from '../../dist/automatic-session.js';
+import { sessionInbox, observeSessionPending } from '../../dist/inbox.js';
+import { renderAttentionDescription } from '../../dist/attention-presentation.js';
+import { createPiReceiver, sendPiMessage } from '../../dist/packages/agent-delivery/src/pi.js';
 
 class PiDeliveryDroppedError extends Error {
   constructor() {
@@ -35,6 +35,9 @@ function framePiMessage(content) {
 export function pendingCardDetails(pending) {
   const items = pending.flatMap((membership) => membership.notifications.map((note) => ({
     square: path.basename(membership.squarePath, '.square'),
+    actor: note.actor,
+    recipient: membership.name,
+    route: note.route,
     description: renderAttentionDescription({ actor: note.actor, recipient: membership.name, route: note.route }),
   })));
   return items.length === 0 ? undefined : { items };