@astrosheep/square 0.3.91 → 0.3.92

package/dist/packages/agent-delivery/src/file-lock.js

@@ -0,0 +1,64 @@
+import { DatabaseSync } from 'node:sqlite';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+export class FileLockError extends Error {
+    code = 'not_a_database';
+    constructor(lockPath, cause) {
+        super(`File lock is not a database: ${lockPath}`);
+        this.name = 'FileLockError';
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+function isBusy(error) {
+    return error instanceof Error && /database is locked|SQLITE_BUSY/i.test(error.message);
+}
+function isNotADatabase(error) {
+    return error instanceof Error && /not a database|file is not a database/i.test(error.message);
+}
+export async function withFileLock(lockPath, options, fn) {
+    if (options.createParent !== false)
+        await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    while (true) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? new Error('File lock acquisition aborted');
+        let database;
+        try {
+            database = new DatabaseSync(lockPath);
+            database.exec(`PRAGMA busy_timeout = 0;
+        BEGIN EXCLUSIVE;
+        CREATE TABLE IF NOT EXISTS __agent_delivery_lock (id INTEGER PRIMARY KEY CHECK (id = 1));`);
+        }
+        catch (error) {
+            try {
+                database?.close();
+            }
+            catch { }
+            if (isBusy(error)) {
+                if (options.skipIfBusy)
+                    return undefined;
+                await sleep(options.retryMs, undefined, { signal: options.signal });
+                continue;
+            }
+            if (isNotADatabase(error))
+                throw new FileLockError(lockPath, error);
+            throw error;
+        }
+        try {
+            const result = await fn();
+            database.exec('COMMIT;');
+            return result;
+        }
+        catch (error) {
+            try {
+                database.exec('ROLLBACK;');
+            }
+            catch { }
+            throw error;
+        }
+        finally {
+            database.close();
+        }
+    }
+}

package/dist/packages/agent-delivery/src/index.d.ts

@@ -1,6 +1,6 @@
 import { DeliveryError } from './errors.js';
-import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
-export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions } from './types.js';
+import type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
+export type { OpenCodeConnectOptions, ClaudeConnectOptions, PiConnectOptions, PaseoConnectOptions, CodexConnectOptions, CodexAppServerConnectOptions, CodexCliConnectOptions } from './types.js';
 export interface SendOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
@@ -34,10 +34,24 @@ export type PaseoAgent = Steerable<KeyedSendOptions> & {
     readonly harness: 'paseo';
     readonly agentId: string;
 };
-export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent;
+export type CodexAppServerAgent = Steerable & Queueable & {
+    readonly harness: 'codex';
+    readonly transport: 'app-server';
+    readonly sessionId: string;
+};
+export type CodexCliAgent = Queueable & {
+    readonly harness: 'codex';
+    readonly transport: 'cli';
+    readonly sessionId: string;
+};
+export type CodexAgent = CodexAppServerAgent | CodexCliAgent;
+export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent | CodexAgent;
 export declare function connect(options: OpenCodeConnectOptions): Promise<OpenCodeAgent>;
 export declare function connect(options: ClaudeConnectOptions): Promise<ClaudeAgent>;
 export declare function connect(options: PiConnectOptions): Promise<PiAgent>;
 export declare function connect(options: PaseoConnectOptions): Promise<PaseoAgent>;
+export declare function connect(options: CodexCliConnectOptions): Promise<CodexCliAgent>;
+export declare function connect(options: CodexAppServerConnectOptions): Promise<CodexAppServerAgent>;
+export declare function connect(options: CodexConnectOptions): Promise<CodexAgent>;
 export { DeliveryError };
 export type { DeliveryErrorCode } from './errors.js';

package/dist/packages/agent-delivery/src/index.js

@@ -25,11 +25,30 @@ function failure(error, phase, id) {
     const code = attempt.state === 'unavailable'
         ? attempt.code === 'aborted' ? 'aborted' : attempt.code === 'timeout' ? 'timeout'
             : attempt.code === 'authentication_failed' ? 'authentication_failed' : 'unavailable'
-        : attempt.state === 'rejected' ? attempt.code === 'not_found' ? 'session_not_found' : 'rejected'
+        : attempt.state === 'rejected' ? attempt.code === 'not_found' ? 'session_not_found'
+            : attempt.code === 'unsupported_version' ? 'unsupported_version' : 'rejected'
             : codes[attempt.code ?? 'transport'] ?? 'transport';
     return new DeliveryError(code, attempt.state === 'unknown', id ?? attempt.inputId, attempt.status);
 }
 const harnesses = {
+    'codex-cli': {
+        harness: 'codex', transport: 'cli', proof: 'admitted', accepted: 'admitted', coordinate: 'sessionId', keyed: false, queue: true, steer: false,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectCodexCli } = await import('./codex-cli.js');
+            const target = await connectCodexCli(options);
+            return { coordinate: target.coordinate, send: (text, value) => target.send(text, value) };
+        },
+    },
+    codex: {
+        harness: 'codex', transport: 'app-server', proof: 'admitted', accepted: 'admitted', coordinate: 'sessionId', keyed: false, queue: true,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectCodex, sendCodexText } = await import('./codex.js');
+            const target = await connectCodex(options);
+            return { coordinate: target.sessionId, send: (text, value) => sendCodexText(target, text, value) };
+        },
+    },
     opencode: {
         harness: 'opencode', proof: 'admitted', accepted: 'accepted', coordinate: 'sessionId', keyed: true, queue: true,
         id: (result) => result.inputId,
@@ -70,8 +89,9 @@ const harnesses = {
 export async function connect(options) {
     const harness = isRecord(options) && typeof options.harness === 'string' ? options.harness : undefined;
     // An own-key check keeps Object.prototype names out of the transport table.
-    const spec = harness !== undefined && Object.hasOwn(harnesses, harness) ? harnesses[harness] : undefined;
-    if (spec === undefined)
+    const key = harness === 'codex' && isRecord(options) && options.transport === 'cli' ? 'codex-cli' : harness;
+    const spec = key !== undefined && Object.hasOwn(harnesses, key) ? harnesses[key] : undefined;
+    if (spec === undefined || spec.harness !== harness)
         throw new DeliveryError('invalid_arguments');
     let opened;
     try {
@@ -86,6 +106,8 @@ export async function connect(options) {
             throw new DeliveryError('invalid_arguments');
         // An unusable caller id is an argument precondition; the native sender rejects it.
         const id = options.id;
+        if (!spec.keyed && id !== undefined)
+            throw new DeliveryError('invalid_arguments');
         try {
             const result = await opened.send(text, spec.keyed
                 ? { delivery, inputId: id, timeoutMs: options.timeoutMs, signal: options.signal }
@@ -101,8 +123,11 @@ export async function connect(options) {
     const agent = {
         harness: spec.harness,
         [spec.coordinate]: opened.coordinate,
-        steer: (text, value) => send(text, value, 'steer'),
     };
+    if (spec.transport)
+        agent.transport = spec.transport;
+    if (spec.steer !== false)
+        agent.steer = (text, value) => send(text, value, 'steer');
     if (spec.queue)
         agent.queue = (text, value) => send(text, value, 'queue');
     return Object.freeze(agent);

package/dist/packages/agent-delivery/src/types.d.ts

@@ -1,3 +1,4 @@
+import type { CodexBoundaryStore } from './codex-boundary.js';
 declare const targetBrand: unique symbol;
 export interface OpenCodeTarget {
     readonly harness: 'opencode';
@@ -19,7 +20,12 @@ export interface PaseoTarget {
     readonly agentId: string;
     readonly [targetBrand]: true;
 }
-export type Target = OpenCodeTarget | ClaudeTarget | PiTarget | PaseoTarget;
+export interface CodexTarget {
+    readonly harness: 'codex';
+    readonly sessionId: string;
+    readonly [targetBrand]: true;
+}
+export type Target = OpenCodeTarget | ClaudeTarget | PiTarget | PaseoTarget | CodexTarget;
 export type Delivery = 'steer' | 'queue';
 export interface OpenCodeSendTextOptions {
     readonly delivery?: Delivery;
@@ -45,7 +51,13 @@ export interface PaseoSendTextOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
-export type SendTextOptions = OpenCodeSendTextOptions | ClaudeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions;
+export interface CodexSendTextOptions {
+    readonly delivery?: Delivery;
+    readonly inputId?: never;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type SendTextOptions = OpenCodeSendTextOptions | ClaudeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions | CodexSendTextOptions;
 export interface OpenCodeConnectOptions {
     readonly harness: 'opencode';
     readonly sessionId: string;
@@ -88,6 +100,32 @@ export interface PaseoConnectOptions {
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
+/** Connect only to an existing app-server; never starts a service or resumes a thread. */
+export interface CodexAppServerConnectOptions {
+    readonly harness: 'codex';
+    readonly transport?: 'app-server';
+    readonly sessionId: string;
+    readonly endpoint?: string;
+    readonly token?: string;
+    readonly codexHome?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Bind CLI coordinates and the same lifecycle source used by the receiver's hooks. */
+export interface CodexCliConnectOptions {
+    readonly harness: 'codex';
+    readonly transport: 'cli';
+    readonly sessionId: string;
+    readonly boundaries: Pick<CodexBoundaryStore, 'queueEligible'>;
+    readonly codexHome?: string;
+    readonly endpoint?: string;
+    readonly bin?: string;
+    readonly args?: readonly string[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type CodexConnectOptions = CodexAppServerConnectOptions | CodexCliConnectOptions;
 interface OpenCodeAttempt {
     readonly harness: 'opencode';
     readonly sessionId: string;
@@ -158,5 +196,22 @@ export type PaseoDeliveryResult = (PaseoAttempt & {
     readonly state: 'unknown';
     readonly code: 'timeout' | 'aborted' | 'transport';
 });
-export type DeliveryResult = OpenCodeDeliveryResult | ClaudeDeliveryResult | PiDeliveryResult | PaseoDeliveryResult;
+interface CodexAttempt {
+    readonly harness: 'codex';
+    readonly sessionId: string;
+    readonly inputId: string;
+}
+export type CodexDeliveryResult = (CodexAttempt & {
+    readonly state: 'admitted';
+}) | (CodexAttempt & {
+    readonly state: 'unknown';
+    readonly code: 'timeout' | 'aborted' | 'transport' | 'invalid_response';
+}) | (CodexAttempt & {
+    readonly state: 'unavailable';
+    readonly code: 'timeout' | 'aborted' | 'transport' | 'authentication_failed';
+}) | (CodexAttempt & {
+    readonly state: 'rejected';
+    readonly code: 'not_found' | 'refused' | 'unsupported_version';
+});
+export type DeliveryResult = OpenCodeDeliveryResult | ClaudeDeliveryResult | PiDeliveryResult | PaseoDeliveryResult | CodexDeliveryResult;
 export {};

package/guides/codex-delivery.md

@@ -0,0 +1,79 @@
+# Codex delivery
+
+Square uses the shared Codex leaves in `packages/agent-delivery/src`, rather than
+maintaining a second hook protocol, boundary store or CLI sender. The standalone
+package's [README](../packages/agent-delivery/README.md) describes both its native
+app-server capability and its host-owned hook integration.
+
+## Square's hook path
+
+`plugins/codex/hooks/hooks.json` invokes `square codex-hook`:
+
+- `SessionStart`, `SessionResume` and `UserPromptSubmit` invalidate the previous
+  Stop observation. `SessionEnd` marks the session ended and ends Square's owned
+  memberships. Later Stop/tool callbacks cannot re-enable queue until a new
+  `SessionStart` or `SessionResume`.
+- `PostToolUse` asks Square for current pending activity and returns the existing
+  bounded `additionalContext` presentation.
+- `Stop` records queue eligibility and sweeps pending work, but does not itself
+  claim that a preview was presented.
+
+The shared handler owns hook framing, lifecycle sequencing, its cancellation
+budget and bounded sweeps. Square supplies activity selection, formatting,
+artifact-owned presentation claims, cancellation, membership cleanup and
+pending-work sweeps. The handler cooperatively awaits Square's pull: the signal
+cancels work before presentation, but a successful presentation's `settleAs`
+finishes independently of request cancellation. Even when that settlement crosses
+the internal budget, the hook waits for it and returns the associated context;
+it never abandons settlement that can mark activity seen without returning text.
+After expiry, no sweep starts, and a sweep timeout cannot erase successful pull
+output. Settlement must still finish within Codex's external hook timeout. Hook inbox lookup uses
+an exact Body (`{ channel: 'codex', session }`), not a bare session id. The shared
+boundary store uses Square's caller-selected `SQUARE_CODEX_BOUNDARIES` file,
+defaulting to `~/.square/codex-boundaries.json`; its JSON observations are not
+conversation storage and are not proof of current native execution or consumption.
+Square's format5 artifact remains authoritative for seats and delivery evidence.
+
+`CodexQueueTransport` implements the existing `WakeTransportPort` and uses the public
+`connect({ harness: 'codex', transport: 'cli', sessionId, boundaries, ... })`
+and `agent.queue(text)` interface, just like independent hosts. Square reads its
+stored pending preview and finishes its currentness gate first; the bound client
+checks boundary eligibility once inside `queue()`, then launches the CLI. No
+caller-side lifecycle check is duplicated. Outcomes continue through the existing
+artifact-owned delivery path; no host ledger or new route kind is introduced.
+
+Both CLI coordinate creation and MCP call-local Codex coordinates capture the
+recipient's `CODEX_HOME` (or home default), so later senders use the recipient's
+CLI configuration rather than their own. Only an explicitly configured
+`SQUARE_CODEX_ENDPOINT` adds a remote endpoint. `SQUARE_CODEX_BIN` remains
+Square's executable selection; it is not an environment convention of the
+independent package.
+
+By default the sender runs `codex queue --thread ... --message ...`, allowing the
+CLI's normal connection/startup behavior. Only an explicit endpoint adds
+`--remote`. This does not make another host's private stdio pipe attachable.
+After an observed `SessionEnd`, Square does not dispatch queue; the bound lifecycle
+check also catches an end observed while the currentness gate was running.
+It cannot retract a submission already launched or infer a missed end hook.
+Queue success means native admission only; its receipt id is a local attempt
+UUID, not a server message id. The child runs asynchronously and respects the
+send's abort signal/deadline. Timeout, killed child and unexplained post-launch
+failures remain unknown, not a safe reason to resend. A receiver with no tool
+calls waits for Stop; this path is not instantaneous native steer.
+
+## Optional native app-server capability
+
+Independent consumers can use `connect({ harness: 'codex', sessionId, endpoint })`
+from `@astrosheep/agent-delivery` for fenced busy steer and native queue.
+`transport: 'app-server'` is the explicit spelling and the default when omitted;
+it exposes both methods. `transport: 'cli'` exposes queue only and requires the
+host's hook lifecycle source at connection time. There is no automatic fallback
+between transports. The app-server transport never starts a service or calls
+`thread/resume`. This does not replace Square's hook policy or add a new persisted
+Square route kind. A loaded thread's owner remains its existing host, not the
+external sender.
+
+Neither path implements a read-receipt roundtrip. Admission and runtime
+observations must not be presented as model comprehension or completion. An
+unknown outcome stays unknown. Installing, restarting or changing a real Codex
+server is outside this integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.91",
+  "version": "0.3.92",
   "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.91",
+  "version": "0.3.92",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

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

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

package/plugins/codex/hooks/hooks.json

@@ -9,6 +9,9 @@
     "SessionEnd": [
       { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 3 }] }
     ],
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+    ],
     "PostToolUse": [
       {
         "hooks": [

package/plugins/paseo/client/markdown.tsx

@@ -1,10 +1,7 @@
 import { useMemo, type ReactNode } from "react";
-import { Platform, Text, View, type TextStyle } from "react-native";
+import { Platform, Text, View, type TextStyle, type ViewStyle } from "react-native";
 import type { PluginTheme } from "@getpaseo/plugin";
 import { Lexer, lexer, type Token, type Tokens } from "marked";
-import { parseSquareBlocks } from "../shared/message.ts";
-
-export { parseSquareBlocks };
 
 export const MONO = Platform.select({ ios: "Menlo", android: "monospace", default: "ui-monospace, Menlo, monospace" });
 
@@ -12,30 +9,21 @@ function makeStyles(colors: PluginTheme["colors"]) {
   return {
     block: { gap: 6 },
     text: { color: colors.foreground, fontSize: 13, lineHeight: 19 },
-    strong: { fontWeight: "700" as const },
-    em: { fontStyle: "italic" as const },
-    del: { textDecorationLine: "line-through" as const },
+    strong: { fontWeight: "500" as const, color: colors.foreground },
+    em: { color: colors.foregroundMuted, fontStyle: "italic" as const },
+    del: { color: colors.foregroundMuted, textDecorationLine: "line-through" as const },
     link: { color: colors.accent, textDecorationLine: "underline" as const },
-    inlineCode: { fontFamily: MONO, fontSize: 12, backgroundColor: colors.surface2, color: colors.foreground },
-    codeBlock: {
-      backgroundColor: colors.surface0,
-      borderRadius: 8,
-      borderWidth: 1,
-      borderColor: colors.border,
-      paddingHorizontal: 9,
-      paddingVertical: 7,
-    },
-    codeText: { fontFamily: MONO, fontSize: 11.5, lineHeight: 17, color: colors.foreground },
+    inlineCode: { fontFamily: MONO },
+    codeBlock: { backgroundColor: colors.surface0, borderRadius: 4, paddingHorizontal: 8, paddingVertical: 6 },
+    codeText: { fontFamily: MONO, fontSize: 13, lineHeight: 19, color: colors.foreground },
     quote: { borderLeftWidth: 2, borderLeftColor: colors.border, paddingLeft: 8, gap: 2 },
     quoteText: { color: colors.foregroundMuted, fontStyle: "italic" as const },
-    meta: { color: colors.foregroundMuted, fontSize: 11, lineHeight: 15, fontFamily: MONO },
-    actor: { color: colors.accent, fontSize: 12, lineHeight: 17 },
     separator: { height: 1, backgroundColor: colors.border, marginVertical: 4 },
     listRow: { flexDirection: "row" as const, gap: 6 },
     listItem: { flexShrink: 1, gap: 2 },
-    bullet: { color: colors.accent, fontSize: 13, lineHeight: 19 },
+    bullet: { color: colors.foregroundMuted, fontSize: 13, lineHeight: 19 },
     tableRow: { flexDirection: "row" as const, gap: 8 },
-    tableCell: { flex: 1, fontSize: 12 },
+    tableCell: { flex: 1 },
   };
 }
 
@@ -55,7 +43,7 @@ function renderInlines(tokens: Token[], styles: Styles, prefix: string, extra?:
       case "em": return nested(styles.em);
       case "del": return nested(styles.del);
       case "link": return nested(styles.link);
-      case "codespan": return <Text key={key} style={[styles.text, extra, styles.inlineCode]}>{` ${token.text} `}</Text>;
+      case "codespan": return <Text key={key} style={[styles.text, extra, styles.inlineCode]}>{token.text}</Text>;
       case "br": return "\n";
       case "image": return token.text;
       default: {
@@ -86,7 +74,7 @@ function renderBlocks(tokens: Token[], styles: Styles, prefix: string, textStyle
         );
       case "heading":
         return (
-          <Text key={key} style={[styles.text, textStyle, styles.strong, { fontSize: Math.max(13, 18 - token.depth) }]}>
+          <Text key={key} style={[styles.text, textStyle, styles.strong]}>
             {renderInlines(children(token), styles, key)}
           </Text>
         );
@@ -100,7 +88,7 @@ function renderBlocks(tokens: Token[], styles: Styles, prefix: string, textStyle
             {list.items.map((item, itemIndex) => (
               <View key={`${key}-${itemIndex}`} style={styles.listRow}>
                 <Text style={styles.bullet}>
-                  {item.task ? (item.checked === true ? "☑" : "☐") : list.ordered ? `${start + itemIndex}.` : "•"}
+                  {item.task ? (item.checked === true ? "☑" : "☐") : list.ordered ? `${start + itemIndex}.` : "·"}
                 </Text>
                 <View style={styles.listItem}>{renderBlocks(children(item), styles, `${key}-${itemIndex}`, textStyle)}</View>
               </View>
@@ -153,19 +141,9 @@ export function SquareInline({ text, theme, numberOfLines, style }: {
   );
 }
 
-export function SquareMarkdown({ text, theme }: { text: string; theme: PluginTheme }) {
+/** A body of Markdown: no envelope, no route line — the words only, indented by the card. */
+export function SquareMarkdownBody({ text, theme, style }: { text: string; theme: PluginTheme; style?: ViewStyle }) {
   const styles = useMemo(() => makeStyles(theme.colors), [theme.colors]);
-  const blocks = useMemo(() => parseSquareBlocks(text), [text]);
-  return (
-    <View style={styles.block}>
-      {blocks.map((block, index) => (
-        <View key={index} style={styles.block}>
-          {index > 0 && <View style={styles.separator} />}
-          {block.meta !== undefined && <Text style={styles.meta}>{block.meta}</Text>}
-          {block.actor !== undefined && <Text style={styles.actor}>{block.actor}</Text>}
-          {renderBlocks(lexer(block.body), styles, `${index}`)}
-        </View>
-      ))}
-    </View>
-  );
+  const tokens = useMemo(() => lexer(text), [text]);
+  return <View style={[styles.block, style]}>{renderBlocks(tokens, styles, "body")}</View>;
 }

package/plugins/paseo/client/palette.ts

@@ -0,0 +1,62 @@
+import type { PluginTheme } from "@getpaseo/plugin";
+
+/**
+ * Square's own courtyard palette: cool pewter slate and a cold blue voice,
+ * deliberately no relative of notesoup's warm parchment or pi-meantime's
+ * neutral carbon. Every token here is opaque and self-contained — the card and
+ * Markdown never borrow the host's surface ramp or accent, only its appearance
+ * (read from the host ink) and its accentForeground, which paints text on top
+ * of an accent fill.
+ */
+const DARK = {
+  surface0: "#121519", // inset / code
+  surface1: "#171b20", // card
+  surface2: "#121519", // inset / code
+  border: "#262d36",
+  foreground: "#e6ebf2",
+  foregroundMuted: "#7d8999",
+  accent: "#60a5fa", // plaza ■ / links
+} as const;
+
+const LIGHT = {
+  surface0: "#e8edf3",
+  surface1: "#f3f6fa", // pewter slate, not notesoup's warm parchment
+  surface2: "#e8edf3",
+  border: "#d5dee8",
+  foreground: "#141b24",
+  foregroundMuted: "#64748b",
+  accent: "#2563eb",
+} as const;
+
+const VOICE = { dark: "#93c5fd", light: "#3b82f6" } as const;
+
+export interface SquarePalette {
+  /** Complete theme for the card and its Markdown surfaces. */
+  theme: PluginTheme;
+  /** The filled ● speaker dot; the hollow ○ keeps the muted ink instead. */
+  voice: string;
+}
+
+/** Paseo theme colors are hex (#RGB or #RRGGBB). */
+function brightness(hex: string): number {
+  const rgb = hex.length === 4 ? hex.slice(1).replace(/./g, digit => digit + digit) : hex.slice(1, 7);
+  return 0.299 * parseInt(rgb.slice(0, 2), 16)
+    + 0.587 * parseInt(rgb.slice(2, 4), 16)
+    + 0.114 * parseInt(rgb.slice(4, 6), 16);
+}
+
+export function squarePalette(theme: PluginTheme): SquarePalette {
+  // The SDK exposes colors, not appearance. Use the host theme, never the OS color scheme.
+  const dark = brightness(theme.colors.foreground) > brightness(theme.colors.surface0);
+  const palette = dark ? DARK : LIGHT;
+  return {
+    theme: { colors: {
+      ...palette,
+      accentForeground: theme.colors.accentForeground,
+      statusSuccess: theme.colors.statusSuccess,
+      statusWarning: theme.colors.statusWarning,
+      statusDanger: theme.colors.statusDanger,
+    } },
+    voice: dark ? VOICE.dark : VOICE.light,
+  };
+}