@pinagent/react-native 0.1.0

package/src/native/transcript.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Transcript reducer + wire types for the RN widget.
+ *
+ * Deliberate, dependency-free mirror of `@pinagent/shared`'s `AgentEvent`
+ * union (event-bus.ts), `ServerMessage` (ws-protocol.ts), and the canonical
+ * `renderTranscript` (render-transcript.ts). We DON'T import the package: the
+ * native client ships as **source** and is bundled onto the device by the
+ * consumer's Metro, but `@pinagent/shared` is `private` (unpublished) and
+ * built for Node — importing it into device code would break a real
+ * `npm install @pinagent/react-native`, the same way bundling any unpublished
+ * `@pinagent/*` dep does. The package's `./server` entry CAN depend on shared
+ * (tsdown bundles it into dist); device source cannot.
+ *
+ * Keep in sync with those three files. The shapes are stable and the reducer
+ * mirrors the shared one, extended with the streaming-only kinds (ask/status)
+ * the interactive RN sheet renders.
+ */
+
+/** Flat AgentEvent union — mirror of `@pinagent/shared`'s `event-bus.ts`. */
+export type AgentEvent =
+  | { type: 'init'; sessionId: string; model: string; permissionMode: string; apiKeySource: string }
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; name: string; summary: string }
+  | { type: 'tool_result'; ok: boolean }
+  | { type: 'progress'; turn: number }
+  | { type: 'ask_user'; askId: string; question: string; context?: string; options?: string[] }
+  | { type: 'error'; message: string }
+  | { type: 'result'; subtype: string; numTurns: number; totalCostUsd: number; durationMs: number }
+  | {
+      type: 'status_changed';
+      status: 'pending' | 'fixed' | 'wontfix' | 'deferred';
+      note: string | null;
+      commitSha: string | null;
+      resolvedAt: string | null;
+    };
+
+/** Server → client frames the RN client acts on (subset of the web protocol). */
+export type ServerMessage =
+  | { type: 'event'; feedbackId: string; event: AgentEvent }
+  | { type: 'done'; feedbackId: string }
+  | { type: 'error'; feedbackId?: string; message: string }
+  | { type: 'worktree_state'; feedbackId: string; state: string; commitSha?: string }
+  // Frames the RN client receives but ignores (project / extension fan-out, pong).
+  | { type: string; [k: string]: unknown };
+
+export type TranscriptKind = 'text' | 'tool' | 'error' | 'result' | 'ask' | 'status';
+
+export interface TranscriptRow {
+  /** Stable key for React lists; derived from event index. */
+  id: string;
+  kind: TranscriptKind;
+  /** Primary text. For tools, the tool name. */
+  text: string;
+  /** Tool argument summary / ask options, when present. */
+  detail?: string;
+  /** tool_result success flag → ✓/✗ marker. */
+  ok?: boolean;
+}
+
+/**
+ * Fold AgentEvents into render-ready rows. Pure and deterministic — mirrors
+ * the shared `renderTranscript`, plus `ask_user` / `status_changed` rows the
+ * interactive RN sheet shows. `init`, `progress`, `tool_result` produce no row
+ * of their own (`tool_result` annotates the preceding tool row with ✓/✗).
+ */
+export function renderTranscript(events: AgentEvent[]): TranscriptRow[] {
+  const rows: TranscriptRow[] = [];
+  events.forEach((event, i) => {
+    switch (event.type) {
+      case 'text': {
+        const text = event.text.trim();
+        if (text) rows.push({ id: `e${i}`, kind: 'text', text });
+        break;
+      }
+      case 'tool_use':
+        rows.push({
+          id: `e${i}`,
+          kind: 'tool',
+          text: event.name,
+          ...(event.summary ? { detail: event.summary } : {}),
+        });
+        break;
+      case 'tool_result':
+        for (let j = rows.length - 1; j >= 0; j--) {
+          if (rows[j].kind === 'tool') {
+            rows[j].ok = event.ok;
+            break;
+          }
+        }
+        break;
+      case 'ask_user':
+        rows.push({
+          id: `e${i}`,
+          kind: 'ask',
+          text: event.question,
+          ...(event.options?.length ? { detail: event.options.join(' · ') } : {}),
+        });
+        break;
+      case 'error':
+        rows.push({ id: `e${i}`, kind: 'error', text: event.message });
+        break;
+      case 'status_changed':
+        rows.push({
+          id: `e${i}`,
+          kind: 'status',
+          text: event.note
+            ? `Resolved (${event.status}): ${event.note}`
+            : `Resolved (${event.status})`,
+        });
+        break;
+      case 'result': {
+        const ok = event.subtype === 'success';
+        const cost = event.totalCostUsd > 0 ? ` · $${event.totalCostUsd.toFixed(4)}` : '';
+        const turns = `${event.numTurns} turn${event.numTurns === 1 ? '' : 's'}`;
+        rows.push({
+          id: `e${i}`,
+          kind: 'result',
+          text: ok ? `Done · ${turns}${cost}` : `Ended: ${event.subtype} · ${turns}${cost}`,
+          ok,
+        });
+        break;
+      }
+      // init, progress: no transcript row.
+    }
+  });
+  return rows;
+}
+
+/** The latest unanswered ask_user, if the run is currently blocked on one. */
+export function pendingAsk(
+  events: AgentEvent[],
+): { askId: string; question: string; options: string[] } | null {
+  let ask: { askId: string; question: string; options: string[] } | null = null;
+  for (const event of events) {
+    if (event.type === 'ask_user') {
+      ask = { askId: event.askId, question: event.question, options: event.options ?? [] };
+    }
+    // A terminal result/error clears any pending question.
+    if (event.type === 'result' || event.type === 'error') ask = null;
+  }
+  return ask;
+}

package/src/native/transport.ts

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * POST the assembled feedback to the Metro dev server.
+ *
+ * The web widget POSTs to a same-origin `/__pinagent/feedback`. RN has no
+ * origin, so we derive the dev-server base from the bundle URL
+ * (`NativeModules.SourceCode.scriptURL`) — that's the host Metro is
+ * already serving from, which also resolves the awkward cases for free:
+ * a physical device gets the LAN host, the iOS simulator gets localhost,
+ * the Android emulator gets `10.0.2.2`. No hard-coded host needed.
+ */
+import { NativeModules, Platform } from 'react-native';
+import type { FeedbackInput } from './types';
+
+interface DevServerInfo {
+  url?: string;
+  bundleLoadedFromServer?: boolean;
+}
+
+let cachedGetDevServer: (() => DevServerInfo) | null | undefined;
+
+/**
+ * RN's own dev-server resolver. It reads the `NativeSourceCode` **TurboModule**,
+ * which — unlike the legacy `NativeModules.SourceCode` bridge proxy — is
+ * populated under the New Architecture (bridgeless, RN 0.82+, the only mode RN
+ * ships now). Lazy + cached: a release build (widget `__DEV__`-gated away)
+ * never reaches into RN internals. `require` takes a static string literal —
+ * Metro forbids `require(variable)`.
+ */
+function loadGetDevServer(): (() => DevServerInfo) | null {
+  if (cachedGetDevServer !== undefined) return cachedGetDevServer;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+    const mod = require('react-native/Libraries/Core/Devtools/getDevServer');
+    const fn = (mod as { default?: unknown })?.default ?? mod;
+    cachedGetDevServer = typeof fn === 'function' ? (fn as () => DevServerInfo) : null;
+  } catch {
+    cachedGetDevServer = null;
+  }
+  return cachedGetDevServer;
+}
+
+/**
+ * Parse `http://192.168.1.5:8081/index.bundle?...` (or the RN packager's
+ * variants) down to `http://192.168.1.5:8081`. Returns null in release builds,
+ * where no Metro server is reachable.
+ *
+ * Prefers RN's `getDevServer()` (TurboModule-backed, works under the New
+ * Architecture) and falls back to the legacy `NativeModules.SourceCode.scriptURL`
+ * for pre-bridgeless RN. The legacy proxy is empty under bridgeless, which is
+ * what made every submit fail with "No dev server" on RN 0.82+.
+ */
+export function devServerBaseUrl(): string | null {
+  const getDevServer = loadGetDevServer();
+  if (getDevServer) {
+    try {
+      const info = getDevServer();
+      // `bundleLoadedFromServer` is false in release builds (url defaults to
+      // localhost:8081 there, so the url alone can't be trusted).
+      if (info?.url && info.bundleLoadedFromServer !== false) {
+        const m = /^(https?:\/\/[^/]+)/.exec(info.url);
+        if (m) return m[1]!;
+      }
+    } catch {
+      // Fall through to the legacy bridge read.
+    }
+  }
+  const scriptURL: string | undefined = NativeModules?.SourceCode?.scriptURL;
+  if (!scriptURL) return null;
+  const match = /^(https?:\/\/[^/]+)/.exec(scriptURL);
+  return match ? match[1]! : null;
+}
+
+export interface SubmitResult {
+  ok: boolean;
+  id?: string;
+  agentSpawned?: boolean;
+  error?: string;
+}
+
+/**
+ * Send one comment. Mirrors the web widget's POST to
+ * `/__pinagent/feedback`; the response (`{ id, agentSpawned }`) is the
+ * same one the Vite/Next middleware returns.
+ */
+export async function submitFeedback(input: FeedbackInput): Promise<SubmitResult> {
+  const base = devServerBaseUrl();
+  if (!base) {
+    return { ok: false, error: 'No dev server (release build?)' };
+  }
+  try {
+    const res = await fetch(`${base}/__pinagent/feedback`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(input),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      return { ok: false, error: `${res.status} ${text}`.trim() };
+    }
+    const json = (await res.json()) as { id?: string; agentSpawned?: boolean };
+    return { ok: true, id: json.id, agentSpawned: json.agentSpawned };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * Fetch the conversation list from the dev server (`GET /__pinagent/feedback`).
+ * Used on `<Pinagent/>` mount to restore minimized pills after an app reload —
+ * the server's `.pinagent/db.sqlite` is the source of truth, so RN keeps no
+ * device-local mirror. Returns `[]` (degrade silently) when the dev server is
+ * unreachable or the request fails — exactly as today when there's no server.
+ *
+ * The items are the `storage.list()` projection (`FeedbackRecord[]`); the
+ * caller filters them with `restorePills`. Typed loosely here so the wire JSON
+ * doesn't drag the agent-runner type into RN source.
+ */
+export async function fetchFeedbackList(): Promise<unknown[]> {
+  const base = devServerBaseUrl();
+  if (!base) return [];
+  try {
+    const res = await fetch(`${base}/__pinagent/feedback`, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+    });
+    if (!res.ok) return [];
+    const json = (await res.json()) as unknown;
+    return Array.isArray(json) ? json : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Ask the dev server to open a source location in the editor on the machine
+ * running Metro — the RN analog of the web composer's "navigate to file".
+ * Fire-and-forget: the device gets no useful signal beyond "request sent".
+ */
+export async function openInEditor(loc: {
+  file: string;
+  line: number;
+  col: number;
+}): Promise<boolean> {
+  const base = devServerBaseUrl();
+  if (!base) return false;
+  try {
+    const res = await fetch(`${base}/__pinagent/open`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(loc),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** `${Platform.OS} ${Platform.Version}` — RN's stand-in for a UA string. */
+export function platformTag(): string {
+  return `${Platform.OS} ${String(Platform.Version)}`;
+}

package/src/native/types.ts

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The wire shape the RN widget produces. It mirrors `FeedbackInputSchema`
+ * in `packages/agent-runner/src/storage.ts` so the existing server
+ * accepts a phone-filed comment with zero backend changes. Keep this in
+ * lockstep with that zod schema — the middleware re-validates against it.
+ */
+export interface FeedbackInput {
+  /** Comment text the developer typed. 1..8000 chars (server-enforced). */
+  comment: string;
+  /**
+   * Source location of the tapped component, from the fiber's
+   * `_debugSource` (the RN analog of web's `data-pa-loc`). Null when the
+   * tapped view has no resolvable source (a deep native view with no
+   * composite owner in dev).
+   */
+  loc: { file: string; line: number; col: number } | null;
+  /**
+   * Web sends a CSS selector here for HMR re-anchoring. RN has no
+   * selectors, so v1 sends the component display-name chain (e.g.
+   * "App > HomeScreen > PrimaryButton") purely to satisfy the schema and
+   * give the agent a human-readable hint. See the design doc's
+   * "Deliberate cuts for v1".
+   */
+  selector: string;
+  /** The current route/screen name (web sends the page URL). */
+  url: string;
+  /** Window dimensions at pick time. */
+  viewport: { w: number; h: number };
+  /** `${Platform.OS} ${Platform.Version}` — the RN analog of a UA string. */
+  userAgent: string;
+  /** base64 PNG (no data: prefix). Capped at 5MB by the middleware. */
+  screenshot: string;
+  /** ISO timestamp. */
+  createdAt: string;
+  /**
+   * Extra elements the developer multi-picked into the SAME comment (the
+   * 2nd…Nth taps). Optional — omitted entirely for a single pick, exactly
+   * like the web widget (the server stores `additional_anchors` as null
+   * unless this is a non-empty array). The agent receives them as
+   * `additionalTargets` and addresses every location. Same per-anchor shape
+   * the web sends in `FeedbackInputSchema.additionalAnchors`
+   * (`packages/agent-runner/src/storage.ts`).
+   */
+  additionalAnchors?: AdditionalAnchor[];
+}
+
+/**
+ * One extra (non-primary) pick. Matches the web `AdditionalAnchorSchema`
+ * exactly so the server accepts it unchanged: `clickX`/`clickY` are required
+ * integers (the tap point in window coordinates); `component` is optional.
+ */
+export interface AdditionalAnchor {
+  file: string | null;
+  line: number | null;
+  col: number | null;
+  selector: string;
+  clickX: number;
+  clickY: number;
+  component?: string | null;
+}
+
+/** One segment of the component breadcrumb. */
+export interface PickCrumb {
+  /** Component display name (e.g. `FeatureCard`). */
+  name: string;
+  /**
+   * Source location of that component, from its own `data-pa-loc`. Null when
+   * the component carries no resolvable source (e.g. an untagged 3rd-party
+   * wrapper). Lets the breadcrumb re-anchor the comment onto an ancestor.
+   */
+  loc: FeedbackInput['loc'];
+  /**
+   * Highlight rectangle for this component (window coordinates), so pressing
+   * the crumb moves the on-screen selection outline onto it. Null when it
+   * couldn't be measured.
+   */
+  frame: { x: number; y: number; width: number; height: number } | null;
+}
+
+/** Result of resolving a tap point to a source location. */
+export interface PickResult {
+  /** The precise tapped element's source location (the default target). */
+  loc: FeedbackInput['loc'];
+  /** Component display-name breadcrumb, newest (tapped) last. */
+  nameChain: string[];
+  /**
+   * Per-segment breadcrumb (same order as {@link nameChain}: root first,
+   * tapped component last), each carrying its own `loc` so pressing a
+   * breadcrumb can re-anchor the comment onto that ancestor.
+   */
+  chain: PickCrumb[];
+  /** Highlight rectangle in window coordinates, for the overlay outline. */
+  frame: { x: number; y: number; width: number; height: number } | null;
+}

package/src/native/ws-client.ts

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * RN WebSocket client for live agent streaming.
+ *
+ * Connects to the same Metro host the feedback POST uses (derived from
+ * `devServerBaseUrl()`), swapping the scheme to `ws(s)` and hitting
+ * `/__pinagent/ws` — the endpoint the server mounts via
+ * `pinagentWebsocketEndpoints` (Metro `config.server.websocketEndpoints`).
+ * Because it rides Metro's own port, a physical device needs no port
+ * discovery: if the bundle loaded, this URL is reachable.
+ *
+ * The wire protocol is the web one (`@pinagent/shared`'s ws-protocol): we send
+ * `subscribe` / `user_message` / `ask_response` / `interrupt`, and receive
+ * `event` / `done` / `error`. On reconnect the server replays the full
+ * transcript, so we fire `onReset` first to let the UI rebuild from scratch.
+ *
+ * Scoped to ONE feedback id per client — the RN widget streams a single
+ * conversation at a time (the one just submitted). That keeps this far smaller
+ * than the web client's multiplexed map.
+ */
+
+import type { AgentEvent, ServerMessage } from './transcript';
+import { devServerBaseUrl } from './transport';
+
+const RECONNECT_MIN_MS = 500;
+const RECONNECT_MAX_MS = 8000;
+
+export interface StreamHandlers {
+  /** A reconnect is about to replay the transcript — clear and rebuild. */
+  onReset(): void;
+  onEvent(event: AgentEvent): void;
+  /** The run's bus closed (agent finished or idle). */
+  onDone(): void;
+  onError(message: string): void;
+}
+
+/** Derive `ws(s)://host:port/__pinagent/ws` from Metro's bundle URL. */
+export function devServerWsUrl(): string | null {
+  const base = devServerBaseUrl();
+  if (!base) return null;
+  return `${base.replace(/^http/, 'ws')}/__pinagent/ws`;
+}
+
+export class StreamClient {
+  private socket: WebSocket | null = null;
+  private reconnectDelay = RECONNECT_MIN_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private closed = false;
+  private connectedBefore = false;
+
+  constructor(
+    private readonly feedbackId: string,
+    private readonly handlers: StreamHandlers,
+  ) {}
+
+  /** Open the socket and subscribe. Safe to call once per instance. */
+  start(): void {
+    this.closed = false;
+    this.connect();
+  }
+
+  /** Tear down for good — no further reconnects. Call on unmount/dismiss. */
+  stop(): void {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    try {
+      this.socket?.close();
+    } catch {
+      // already closing
+    }
+    this.socket = null;
+  }
+
+  /** Queue a follow-up turn for the agent. No-op if the socket isn't open. */
+  sendUserMessage(content: string): void {
+    this.send({ type: 'user_message', feedbackId: this.feedbackId, content });
+  }
+
+  /** Answer an `ask_user` prompt. */
+  sendAskResponse(askId: string, answer: string): void {
+    this.send({ type: 'ask_response', askId, answer });
+  }
+
+  /** Interrupt the in-flight run. */
+  interrupt(): void {
+    this.send({ type: 'interrupt', feedbackId: this.feedbackId });
+  }
+
+  private connect(): void {
+    const url = devServerWsUrl();
+    if (!url) {
+      this.handlers.onError('No dev server (release build?)');
+      return;
+    }
+    let socket: WebSocket;
+    try {
+      socket = new WebSocket(url);
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.socket = socket;
+
+    socket.onopen = () => {
+      // On a reconnect the server replays the whole transcript; let the UI
+      // wipe and rebuild so we don't double-render.
+      if (this.connectedBefore) this.handlers.onReset();
+      this.connectedBefore = true;
+      this.reconnectDelay = RECONNECT_MIN_MS;
+      this.send({ type: 'subscribe', feedbackId: this.feedbackId });
+    };
+
+    socket.onmessage = (ev: { data?: unknown }) => {
+      this.onMessage(ev.data);
+    };
+
+    socket.onclose = () => {
+      if (this.closed) return;
+      this.scheduleReconnect();
+    };
+
+    // RN fires onerror then onclose; reconnect is driven by onclose.
+    socket.onerror = () => {};
+  }
+
+  private onMessage(data: unknown): void {
+    if (typeof data !== 'string') return;
+    let msg: ServerMessage;
+    try {
+      msg = JSON.parse(data) as ServerMessage;
+    } catch {
+      return;
+    }
+    switch (msg.type) {
+      case 'event':
+        if (msg.feedbackId === this.feedbackId && msg.event) this.handlers.onEvent(msg.event);
+        break;
+      case 'done':
+        if (msg.feedbackId === this.feedbackId) this.handlers.onDone();
+        break;
+      case 'error':
+        // Server scopes some errors to a feedback id; surface ours + global.
+        if (!msg.feedbackId || msg.feedbackId === this.feedbackId) {
+          this.handlers.onError(msg.message ?? 'unknown error');
+        }
+        break;
+      // worktree_state / pong / project fan-out: ignored by the RN widget.
+    }
+  }
+
+  private send(msg: Record<string, unknown>): void {
+    const s = this.socket;
+    if (!s || s.readyState !== 1 /* OPEN */) return;
+    try {
+      s.send(JSON.stringify(msg));
+    } catch {
+      // socket closing mid-write
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed || this.reconnectTimer) return;
+    const delay = this.reconnectDelay;
+    this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (!this.closed) this.connect();
+    }, delay);
+  }
+}