paseo-form-render 0.0.0-stage → 0.1.0

package/client/rpc-bridge.tsx

@@ -0,0 +1,27 @@
+import type { PluginRpcContract } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { useRpc } from "@getpaseo/plugin/client";
+import React, { createContext, useContext } from "react";
+import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+
+export type PfrRpcFn = PluginClientContext["rpc"];
+
+const PfrRpcContext = createContext<PfrRpcFn | null>(null);
+
+export const PfrRpcProvider: React.FC<{ rpc?: PfrRpcFn; children: React.ReactNode }> = ({
+  rpc,
+  children,
+}) => {
+  if (!rpc) return <>{children}</>;
+  return <PfrRpcContext.Provider value={rpc}>{children}</PfrRpcContext.Provider>;
+};
+
+export function usePfrRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
+  contract: PluginRpcContract<InputSchema, OutputSchema>,
+): (input: ZodInput<InputSchema>) => Promise<ZodOutput<OutputSchema>> {
+  const customRpc = useContext(PfrRpcContext);
+  if (customRpc) {
+    return (input: ZodInput<InputSchema>) => customRpc(contract, input);
+  }
+  return useRpc(contract);
+}

package/client/settings-screen.tsx

@@ -0,0 +1,168 @@
+import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { useSettings } from "@getpaseo/plugin/client";
+import React from "react";
+import { ActivityIndicator, Pressable, StyleSheet, Switch, Text, View } from "react-native";
+import { MAX_AUTO_FIX_RETRIES, pfrSettings } from "../shared/settings";
+
+export const PfrSettingsScreen: React.FC<PluginSurfaceProps> = ({ theme }) => {
+  const settings = useSettings(pfrSettings);
+  const { colors } = theme;
+
+  if (settings.status === "loading") {
+    return (
+      <View style={styles.container}>
+        <ActivityIndicator color={colors.accent} />
+      </View>
+    );
+  }
+
+  if (settings.status === "error" || settings.status === "invalid") {
+    return (
+      <View style={styles.container}>
+        <Text style={[styles.errorText, { color: colors.statusDanger }]}>
+          Could not load settings: {settings.error}
+        </Text>
+        <Pressable
+          style={[styles.stepButton, styles.retryButton, { borderColor: colors.border, backgroundColor: colors.surface2 }]}
+          onPress={() => void settings.reload()}
+        >
+          <Text style={[styles.stepText, { color: colors.foreground }]}>Retry</Text>
+        </Pressable>
+        {settings.status === "invalid" && (
+          <Pressable
+            style={[styles.stepButton, styles.retryButton, { borderColor: colors.border, backgroundColor: colors.surface2 }]}
+            onPress={() => void settings.reset()}
+          >
+            <Text style={[styles.stepText, { color: colors.foreground }]}>Reset to defaults</Text>
+          </Pressable>
+        )}
+      </View>
+    );
+  }
+
+  const value = settings.values.autoFixMaxRetries;
+  const change = (next: number) => {
+    if (next < 0 || next > MAX_AUTO_FIX_RETRIES || settings.saving) return;
+    void settings.save({ ...settings.values, autoFixMaxRetries: next }, settings.revision);
+  };
+  const stepStyle = (disabled: boolean) => [
+    styles.stepButton,
+    { borderColor: colors.border, backgroundColor: colors.surface2 },
+    disabled && { opacity: 0.4 },
+  ];
+
+  return (
+    <View style={styles.container}>
+      <Text style={[styles.title, { color: colors.foreground }]}>Automatic form fixes</Text>
+      <Text style={[styles.description, { color: colors.foregroundMuted }]}>
+        When an agent replies with a pfr-form block that fails validation, ask it to re-send a corrected block
+        automatically. This sets how many times in a row the agent is asked; 0 turns automatic fixes off. The
+        "Ask agent to fix" button on an error box always works.
+      </Text>
+
+      <View style={styles.row}>
+        <Text style={[styles.label, { color: colors.foreground }]}>Maximum retries</Text>
+        <View style={styles.stepper}>
+          <Pressable
+            accessibilityLabel="Decrease retries"
+            disabled={value <= 0 || settings.saving}
+            style={stepStyle(value <= 0 || settings.saving)}
+            onPress={() => change(value - 1)}
+          >
+            <Text style={[styles.stepText, { color: colors.foreground }]}>−</Text>
+          </Pressable>
+          <Text style={[styles.value, { color: colors.foreground }]}>{value}</Text>
+          <Pressable
+            accessibilityLabel="Increase retries"
+            disabled={value >= MAX_AUTO_FIX_RETRIES || settings.saving}
+            style={stepStyle(value >= MAX_AUTO_FIX_RETRIES || settings.saving)}
+            onPress={() => change(value + 1)}
+          >
+            <Text style={[styles.stepText, { color: colors.foreground }]}>+</Text>
+          </Pressable>
+        </View>
+      </View>
+
+      <Text style={[styles.hint, { color: colors.foregroundMuted }]}>
+        {value === 0 ? "Automatic fixes are off." : `Up to ${value} automatic ${value === 1 ? "request" : "requests"} per reply.`}
+        {settings.saving ? " Saving…" : ""}
+      </Text>
+
+      <Text style={[styles.title, { color: colors.foreground }]}>Prefer forms</Text>
+      <Text style={[styles.description, { color: colors.foregroundMuted }]}>
+        By default the agent is only told it can use pfr-form. Turn this on to require it to ask for choices,
+        parameters, and confirmations with a form instead of plain text. Applies to agents created after the change.
+      </Text>
+      <View style={styles.row}>
+        <Text style={[styles.label, { color: colors.foreground }]}>Require forms for user input</Text>
+        <Switch
+          accessibilityLabel="Require forms for user input"
+          value={settings.values.preferForms}
+          disabled={settings.saving}
+          onValueChange={(next) => void settings.save({ ...settings.values, preferForms: next }, settings.revision)}
+        />
+      </View>
+      {settings.saveError && (
+        <Text style={[styles.errorText, { color: colors.statusDanger }]}>Could not save: {settings.saveError}</Text>
+      )}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 16,
+    gap: 12,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  description: {
+    fontSize: 13,
+    lineHeight: 18,
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+  },
+  label: {
+    fontSize: 14,
+    fontWeight: "500",
+  },
+  stepper: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+  },
+  stepButton: {
+    width: 36,
+    height: 36,
+    borderRadius: 6,
+    borderWidth: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  retryButton: {
+    width: undefined,
+    alignSelf: "flex-start",
+    paddingHorizontal: 12,
+  },
+  stepText: {
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  value: {
+    fontSize: 16,
+    fontWeight: "600",
+    minWidth: 20,
+    textAlign: "center",
+  },
+  hint: {
+    fontSize: 12,
+  },
+  errorText: {
+    fontSize: 12,
+  },
+});

package/index.client.tsx

@@ -0,0 +1,102 @@
+import type { PluginClientContext, PluginTimelineItemProps } from "@getpaseo/plugin/client";
+import { usePaseo } from "@getpaseo/plugin/client";
+import React from "react";
+import { Platform } from "react-native";
+import { z } from "zod";
+import { hasFormBlock } from "./shared/parser";
+import { MessageContainer } from "./client/container";
+import { PfrSettingsScreen } from "./client/settings-screen";
+import { showDemoForm } from "./shared/demo";
+import { PFR_PROMPT_INSTRUCTION } from "./shared/prompt";
+
+const timelineKind = "pfr-form";
+const timelineDataSchema = z.object({
+  text: z.string(),
+});
+
+export default function contribute(client: PluginClientContext) {
+  function TimelineMessageView({
+    item,
+    agentId,
+    theme,
+  }: PluginTimelineItemProps<z.output<typeof timelineDataSchema>>) {
+    const paseo = usePaseo();
+
+    const handleSubmit = async (formattedMessage: string) => {
+      await paseo.agents.ref(agentId).send(formattedMessage);
+    };
+
+    return (
+      <MessageContainer
+        text={item.data.text}
+        theme={theme}
+        agentId={agentId}
+        rpc={client.rpc}
+        onSubmit={handleSubmit}
+      />
+    );
+  }
+  // Transform assistant messages that include pfr-form fences across all platforms (web & mobile).
+  client.addTimelineTransformer({
+    id: "pfr-transformer",
+    query: { itemType: "assistant_message" },
+    transform({ item }) {
+      if (!hasFormBlock(item.text)) {
+        return;
+      }
+      return {
+        items: [
+          {
+            type: "plugin",
+            kind: timelineKind,
+            version: 1,
+            data: {
+              text: item.text,
+            },
+          },
+        ],
+      };
+    },
+  });
+
+  // Render plugin timeline items
+  client.addTimelineRenderer({
+    kind: timelineKind,
+    version: 1,
+    schema: timelineDataSchema,
+    Component: TimelineMessageView,
+  });
+
+  // Host-level settings, including the automatic fix retry limit
+  client.addSettingsScreen({
+    id: "paseo-form-render-settings",
+    title: "Paseo Form Render",
+    icon: "Settings",
+    Component: PfrSettingsScreen,
+  });
+
+  // Slash command to enable pfr-form in an existing agent session
+  client.addSlashCommand({
+    name: "form",
+    description: "Instruct the agent to use pfr-form protocol",
+    argumentHint: "[task]",
+    context: "agent",
+    async onSubmit({ args, paseo, agent }) {
+      const task = args || "Please enable the pfr-form protocol and present interactive forms when applicable.";
+      await paseo.agents.ref(agent.id).send(`${PFR_PROMPT_INSTRUCTION}\n\n${task}`);
+    },
+  });
+
+  // Slash command to show a sample form
+  client.addSlashCommand({
+    name: "form-demo",
+    description: "Show a demo interactive form",
+    argumentHint: "",
+    context: "agent",
+    async onSubmit({ rpc, agent }) {
+      await rpc(showDemoForm, { agentId: agent.id });
+    },
+  });
+
+  return () => {};
+}

package/index.server.ts

@@ -0,0 +1,38 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { registerAutoFix } from "./server/auto-fix";
+import { appendDemoForm } from "./server/demo";
+import { readPfrSettings, registerPfrSettings } from "./server/settings";
+import { handleListProjectFiles, handleCreateDirectory } from "./server/file-picker";
+import { showDemoForm } from "./shared/demo";
+import { listProjectFilesRpc, createDirectoryRpc } from "./shared/pickers";
+import { buildPromptInstruction } from "./shared/prompt";
+
+export default function contribute(server: PluginServerContext) {
+  const settings = registerPfrSettings(server);
+
+  // Inject instructions when a new agent is created
+  server.before("agent.create", async ({ request }) => {
+    const previous = request.config.systemPrompt ?? "";
+    if (previous.includes("[paseo-form-render]")) {
+      return;
+    }
+    const { preferForms } = await readPfrSettings(settings);
+    return {
+      ...request,
+      config: {
+        ...request.config,
+        systemPrompt: [previous, buildPromptInstruction({ preferForms })].filter(Boolean).join("\n\n"),
+      },
+    };
+  });
+
+  server.handle(showDemoForm, appendDemoForm);
+  server.handle(listProjectFilesRpc, handleListProjectFiles);
+  server.handle(createDirectoryRpc, handleCreateDirectory);
+
+  const stopAutoFix = registerAutoFix(server, settings);
+
+  return () => {
+    stopAutoFix();
+  };
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "paseo-form-render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Interactive forms, dashboards, and metric displays in Paseo conversations using pfr-form code fences.",
+  "license": "MIT",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "paseo-plugin.json",
+    "index.client.tsx",
+    "index.server.ts",
+    "client/",
+    "server/",
+    "shared/",
+    "!**/*.test.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "pack:offline": "node scripts/pack-offline.mjs",
+    "e2e": "npm --prefix e2e run e2e --"
+  },
+  "devDependencies": {
+    "@getpaseo/client": "^0.11.2",
+    "@getpaseo/plugin": "^0.11.2",
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^22.20.4",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.4.3"
+  },
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "forms",
+    "dashboards",
+    "interactive-ui",
+    "form-render"
+  ],
+  "author": "Weiqiang",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quickwind/paseo-form-render.git"
+  },
+  "homepage": "https://github.com/quickwind/paseo-form-render#readme",
+  "bugs": {
+    "url": "https://github.com/quickwind/paseo-form-render/issues"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "paseo-form-render",
+  "name": "Paseo Form Render",
+  "description": "Render interactive forms, metrics, and dashboards in conversations using pfr-form code blocks",
+  "requirements": {
+    "paseo": ">=0.11.4"
+  }
+}

package/server/auto-fix.ts

@@ -0,0 +1,199 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import {
+  buildFixMessage,
+  collectTurnFormFailures,
+  countTrailingFixAttempts,
+  type FormFailure,
+  type TimelineEntry,
+} from "../shared/form-fix";
+import { readPfrSettings, type PfrSettingsHandle } from "./settings";
+
+/** How many of the newest timeline entries to fetch when checking the conversation history. */
+const HISTORY_LIMIT = 300;
+
+export type AutoFixSkipReason =
+  | "not-completed"
+  | "no-failures"
+  | "disabled"
+  | "history-unavailable"
+  | "history-truncated"
+  | "superseded"
+  | "limit-reached"
+  | "busy"
+  | "status-unavailable";
+
+export type AutoFixPlan = { ok: false; reason: AutoFixSkipReason } | { ok: true; failures: FormFailure[] };
+
+export type AutoFixDecision =
+  | { send: false; reason: AutoFixSkipReason }
+  | { send: true; message: string; attempt: number };
+
+export interface TurnInput {
+  /** The `timeline` of the `agent.turn_ended` event. It may cover only the finished turn. */
+  turnTimeline: readonly TimelineEntry[];
+  outcome: { readonly kind: string };
+  /** Maximum consecutive fix requests; 0 disables auto-fix. */
+  maxRetries: number;
+}
+
+export interface AutoFixInput extends TurnInput {
+  /** The newest part of the conversation, fetched just before sending. Missing or null means it could not be read. */
+  latestTimeline?: readonly TimelineEntry[] | null;
+  /** True when older entries exist beyond `latestTimeline`. */
+  latestTruncated?: boolean;
+}
+
+/** Cheap first gate that needs only the event: is there anything to fix, and is fixing on? */
+export function planAutoFix({ turnTimeline, outcome, maxRetries }: TurnInput): AutoFixPlan {
+  if (outcome.kind !== "completed") return { ok: false, reason: "not-completed" };
+  const failures = collectTurnFormFailures(turnTimeline);
+  if (failures.length === 0) return { ok: false, reason: "no-failures" };
+  if (maxRetries <= 0) return { ok: false, reason: "disabled" };
+  return { ok: true, failures };
+}
+
+function isRealUserMessage(entry: TimelineEntry): boolean {
+  return entry.type === "user_message" && countTrailingFixAttempts([entry]) === 0;
+}
+
+/**
+ * Decides whether to ask the agent to repair its pfr-form blocks. Failures come from the finished
+ * turn; the retry count and "did anything newer happen" checks use the freshly fetched history,
+ * and the answer is never to send when that history is unavailable.
+ */
+export function decideAutoFix(input: AutoFixInput): AutoFixDecision {
+  const plan = planAutoFix(input);
+  if (!plan.ok) return { send: false, reason: plan.reason };
+
+  const latest = input.latestTimeline;
+  if (!latest) return { send: false, reason: "history-unavailable" };
+
+  // A user message after the last assistant output means the conversation moved on since this turn
+  // ended (the user typed something, or a fix request is already on its way).
+  const lastAssistant = lastIndexOf(latest, (e) => e.type === "assistant_message");
+  const lastUser = lastIndexOf(latest, (e) => e.type === "user_message");
+  if (lastAssistant < 0 || lastUser > lastAssistant) return { send: false, reason: "superseded" };
+
+  // If the finished turn shows the message that started it, the newest user message in the history
+  // must be that same message; anything else is a newer request that has already been answered.
+  // A fetched window with no user message at all holds only this turn's tail, so nothing newer
+  // arrived (a newer message would sit at the end of the window).
+  const turnLastUser = lastIndexOf(input.turnTimeline, (e) => e.type === "user_message");
+  if (lastUser >= 0 && turnLastUser >= 0 && latest[lastUser].text !== input.turnTimeline[turnLastUser].text) {
+    return { send: false, reason: "superseded" };
+  }
+
+  // Count from the fetched history; when a long turn pushed every real user message out of that
+  // window, fall back to the event timeline, which may hold the full history.
+  let countFrom: readonly TimelineEntry[] = latest;
+  if (input.latestTruncated && lastIndexOf(latest, isRealUserMessage) < 0) {
+    if (lastIndexOf(input.turnTimeline, isRealUserMessage) < 0) return { send: false, reason: "history-truncated" };
+    countFrom = input.turnTimeline;
+  }
+
+  const attempts = countTrailingFixAttempts(countFrom);
+  if (attempts >= input.maxRetries) return { send: false, reason: "limit-reached" };
+
+  return { send: true, message: buildFixMessage(plan.failures), attempt: attempts + 1 };
+}
+
+function lastIndexOf(entries: readonly TimelineEntry[], predicate: (entry: TimelineEntry) => boolean): number {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (predicate(entries[i])) return i;
+  }
+  return -1;
+}
+
+/**
+ * Reads timeline items out of a `timeline.refetch()` payload (`entries[].item`, `hasOlder`, `error`).
+ * Returns null when the payload reports an error or is not shaped as expected.
+ */
+export function timelineFromPayload(payload: unknown): { items: TimelineEntry[]; truncated: boolean } | null {
+  if (typeof payload !== "object" || payload === null) return null;
+  const { entries, error, hasOlder } = payload as { entries?: unknown; error?: unknown; hasOlder?: unknown };
+  if (error || !Array.isArray(entries)) return null;
+
+  const items: TimelineEntry[] = [];
+  for (const entry of entries) {
+    const item = (entry as { item?: unknown } | null)?.item as { type?: unknown; text?: unknown } | undefined;
+    if (!item || typeof item.type !== "string") return null;
+    items.push({ type: item.type, text: typeof item.text === "string" ? item.text : undefined });
+  }
+  return { items, truncated: hasOlder === true };
+}
+
+/** Skip reason when the agent is already busy, or its status cannot be read; null when it is idle. */
+export function idleGate(status: string | null | undefined): "busy" | "status-unavailable" | null {
+  if (!status) return "status-unavailable";
+  return status === "idle" ? null : "busy";
+}
+
+async function checkAgentIdle(agent: {
+  refresh(): Promise<unknown>;
+  readonly status: string | null;
+}): Promise<"busy" | "status-unavailable" | null> {
+  try {
+    await agent.refresh();
+  } catch (error) {
+    console.warn("[paseo-form-render] could not refresh agent status", error);
+    return "status-unavailable";
+  }
+  return idleGate(agent.status);
+}
+
+/** Registers the turn-end hook that sends automatic fix requests. */
+export function registerAutoFix(server: PluginServerContext, settings: PfrSettingsHandle) {
+  async function readMaxRetries(): Promise<number> {
+    return (await readPfrSettings(settings)).autoFixMaxRetries;
+  }
+
+  return server.on("agent.turn_ended", async (event, { paseo, signal }) => {
+    try {
+      const turn: TurnInput = {
+        turnTimeline: event.timeline,
+        outcome: event.outcome,
+        maxRetries: await readMaxRetries(),
+      };
+      if (!planAutoFix(turn).ok) return;
+
+      // Yield first so the send never runs re-entrantly inside the turn-end dispatch. The hook stays
+      // pending until the send settles because its `paseo` handle may be scoped to this invocation.
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+      if (signal.aborted) return;
+
+      const agent = paseo.agents.ref(event.agent.id);
+      let history: ReturnType<typeof timelineFromPayload> = null;
+      try {
+        history = timelineFromPayload(
+          await agent.timeline.refetch({ direction: "tail", limit: HISTORY_LIMIT, projection: "projected" }),
+        );
+      } catch (error) {
+        console.warn("[paseo-form-render] could not fetch agent history, skipping auto-fix", error);
+        return;
+      }
+
+      const decision = decideAutoFix({
+        ...turn,
+        latestTimeline: history?.items ?? null,
+        latestTruncated: history?.truncated,
+      });
+      if (!decision.send) {
+        if (decision.reason === "history-unavailable" || decision.reason === "history-truncated") {
+          console.warn(`[paseo-form-render] skipping auto-fix: ${decision.reason}`);
+        }
+        return;
+      }
+      // `send` interrupts a running turn, so a message that arrived after the history fetch would be
+      // cancelled. Re-read the status right before sending and leave a running agent alone. A small
+      // window remains: Paseo has no "send only if idle" option (see README).
+      const gate = await checkAgentIdle(agent);
+      if (gate) {
+        if (gate === "status-unavailable") console.warn("[paseo-form-render] skipping auto-fix: status-unavailable");
+        return;
+      }
+      await agent.send(decision.message);
+    } catch (error) {
+      console.warn("[paseo-form-render] auto-fix hook failed", error);
+    }
+  });
+}

package/server/demo.ts

@@ -0,0 +1,20 @@
+import type { RpcInput } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { DEMO_FORM_TEXT, TIMELINE_KIND, type showDemoForm } from "../shared/demo";
+
+type Paseo = Parameters<Parameters<PluginServerContext["handle"]>[1]>[1]["paseo"];
+
+/** Adds the demo form as a row the form renderer draws; the agent is not prompted. */
+export async function appendDemoForm(
+  { agentId }: RpcInput<typeof showDemoForm>,
+  { paseo }: { paseo: Paseo },
+) {
+  await paseo.agents.ref(agentId).timeline.append({
+    type: "plugin",
+    id: `pfr-form-demo-${Date.now()}`,
+    kind: TIMELINE_KIND,
+    version: 1,
+    data: { text: DEMO_FORM_TEXT },
+  });
+  return {};
+}