@amanm/openpaw 0.1.0

package/cli/lib/ui-messages-to-chat-transcript.ts

@@ -0,0 +1,157 @@
+/**
+ * Maps persisted AI SDK UI messages into {@link ChatLine} rows for the terminal chat transcript.
+ */
+import type { DynamicToolUIPart, ToolUIPart, UIMessage, UITools } from "ai";
+import {
+  getToolName,
+  isFileUIPart,
+  isReasoningUIPart,
+  isTextUIPart,
+  isToolUIPart,
+} from "ai";
+import {
+  formatTuiToolDeniedMarkdown,
+  formatTuiToolErrorMarkdown,
+  formatTuiToolInputMarkdown,
+  formatTuiToolOutputMarkdown,
+  truncateJson,
+} from "../../agent/tool-stream-format";
+import type { AssistantSegment, ChatLine } from "./chat-transcript-types";
+
+/**
+ * Builds a short summary line for a tool part (plain transcript / non-markdown rows).
+ */
+function formatToolPartSummary(part: ToolUIPart<UITools> | DynamicToolUIPart): string {
+  const name = getToolName(part);
+  switch (part.state) {
+    case "input-streaming":
+      return `[Tool ${name}] …`;
+    case "input-available":
+      return `[Tool ${name}] ${truncateJson(part.input)}`;
+    case "output-available":
+      return `[Tool ${name}] → ${truncateJson(part.output)}`;
+    case "output-error":
+      return `[Tool ${name}] error: ${part.errorText}`;
+    case "output-denied":
+      return `[Tool ${name}] (denied)`;
+    case "approval-requested":
+      return `[Tool ${name}] (approval requested)`;
+    case "approval-responded":
+      return `[Tool ${name}] (approval ${part.approval.approved ? "ok" : "rejected"})`;
+    default:
+      return `[Tool ${name}]`;
+  }
+}
+
+/**
+ * Same tool display as the live TUI stream: markdown headings + fenced YAML blocks.
+ */
+function formatToolPartForAssistantTui(part: ToolUIPart<UITools> | DynamicToolUIPart): string {
+  const name = getToolName(part);
+  switch (part.state) {
+    case "input-streaming":
+      return `🔧 **Tool · ${name}**\n\n_(input streaming…)_`;
+    case "input-available":
+      return formatTuiToolInputMarkdown(name, part.input);
+    case "output-available":
+      return `${formatTuiToolInputMarkdown(name, part.input)}\n\n${formatTuiToolOutputMarkdown(part.output)}`;
+    case "output-error":
+      return `${formatTuiToolInputMarkdown(name, part.input)}\n\n${formatTuiToolErrorMarkdown(name, part.errorText)}`;
+    case "output-denied":
+      return `${formatTuiToolInputMarkdown(name, part.input)}\n\n${formatTuiToolDeniedMarkdown(name)}`;
+    case "approval-requested":
+      return `🔧 **Tool · ${name}**\n\n_(approval requested)_`;
+    case "approval-responded":
+      return `🔧 **Tool · ${name}**\n\n_(approval ${part.approval.approved ? "granted" : "rejected"})_`;
+    default:
+      return `🔧 **Tool · ${name}**`;
+  }
+}
+
+/**
+ * Merges a new string into the tail segment when `kind` matches, else appends a segment.
+ */
+function mergeAssistantSegment(
+  segments: AssistantSegment[],
+  kind: AssistantSegment["kind"],
+  text: string,
+): AssistantSegment[] {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return segments;
+  }
+  const last = segments[segments.length - 1];
+  if (last?.kind === kind) {
+    return [...segments.slice(0, -1), { kind, text: `${last.text}\n\n${trimmed}` }];
+  }
+  return [...segments, { kind, text: trimmed }];
+}
+
+/**
+ * Converts assistant message parts into ordered reasoning vs text segments for the TUI.
+ */
+function partsToAssistantSegments(parts: UIMessage["parts"]): AssistantSegment[] {
+  let segments: AssistantSegment[] = [];
+  for (const part of parts) {
+    if (isTextUIPart(part) && part.text.trim()) {
+      segments = mergeAssistantSegment(segments, "text", part.text);
+    } else if (isReasoningUIPart(part) && part.text.trim()) {
+      segments = mergeAssistantSegment(segments, "reasoning", part.text);
+    } else if (isFileUIPart(part)) {
+      segments = mergeAssistantSegment(
+        segments,
+        "text",
+        `[file: ${part.filename ?? part.mediaType}]`,
+      );
+    } else if (isToolUIPart(part)) {
+      segments = mergeAssistantSegment(segments, "tool", formatToolPartForAssistantTui(part));
+    }
+  }
+  return segments;
+}
+
+/**
+ * Joins user/system message parts into a single transcript string (no reasoning label).
+ */
+function partsToPlainTranscriptText(parts: UIMessage["parts"]): string {
+  const chunks: string[] = [];
+  for (const part of parts) {
+    if (isTextUIPart(part) && part.text.trim()) {
+      chunks.push(part.text);
+    } else if (isReasoningUIPart(part) && part.text.trim()) {
+      chunks.push(part.text);
+    } else if (isFileUIPart(part)) {
+      chunks.push(`[file: ${part.filename ?? part.mediaType}]`);
+    } else if (isToolUIPart(part)) {
+      chunks.push(formatToolPartSummary(part));
+    }
+  }
+  return chunks.join("\n\n").trim();
+}
+
+/**
+ * Maps validated session `UIMessage[]` into {@link ChatLine} rows for the terminal chat transcript.
+ * Skips messages that have no displayable content after stripping empty parts.
+ */
+export function uiMessagesToChatLines(messages: UIMessage[]): ChatLine[] {
+  const out: ChatLine[] = [];
+  for (const msg of messages) {
+    if (msg.role !== "user" && msg.role !== "assistant" && msg.role !== "system") {
+      continue;
+    }
+    if (msg.role === "assistant") {
+      const segments = partsToAssistantSegments(msg.parts);
+      if (segments.length === 0) {
+        continue;
+      }
+      out.push({ role: "assistant", segments });
+      continue;
+    }
+    const text = partsToPlainTranscriptText(msg.parts);
+    if (!text) {
+      continue;
+    }
+    out.push({ role: msg.role, text });
+  }
+  return out;
+}

package/cli/lib/use-auto-copy-selection.ts

@@ -0,0 +1,38 @@
+/**
+ * Subscribes to OpenTUI text selection updates and copies the final selection to the
+ * system clipboard using OSC 52 when the terminal supports it.
+ */
+import { useEffect } from "react";
+import { CliRenderEvents } from "@opentui/core";
+import { useRenderer } from "@opentui/react";
+
+/**
+ * Registers a renderer listener so that when the user finishes selecting text in the TUI,
+ * the selected string is sent to the clipboard (via OSC 52), then the selection is cleared.
+ */
+export function useAutoCopySelection(): void {
+  const renderer = useRenderer();
+
+  useEffect(() => {
+    const onSelection = (): void => {
+      if (!renderer.isOsc52Supported()) {
+        return;
+      }
+      const sel = renderer.getSelection();
+      if (!sel || sel.isDragging) {
+        return;
+      }
+      const text = sel.getSelectedText();
+      if (!text) {
+        return;
+      }
+      renderer.copyToClipboardOSC52(text);
+      renderer.clearSelection();
+    };
+
+    renderer.on(CliRenderEvents.SELECTION, onSelection);
+    return () => {
+      renderer.off(CliRenderEvents.SELECTION, onSelection);
+    };
+  }, [renderer]);
+}

package/cli/onboard.tsx

@@ -0,0 +1,248 @@
+#!/usr/bin/env bun
+import { createCliRenderer } from "@opentui/core";
+import { createRoot, useKeyboard, useRenderer } from "@opentui/react";
+import { useCallback, useEffect, useReducer, useState } from "react";
+import {
+  configExists,
+  deleteConfig,
+  saveConfig,
+  PERSONALITIES,
+  type OpenPawConfig,
+  type Personality,
+  type ProviderConfig,
+} from "../config";
+import { ensureWorkspaceLayout } from "../agent/workspace-bootstrap";
+import {
+  WelcomeScreen,
+  InputScreen,
+  PersonalityScreen,
+  ConfirmScreen,
+  StartChatScreen,
+} from "./components/onboard-ui";
+
+type Step =
+  | "provider-baseUrl"
+  | "provider-apiKey"
+  | "provider-model"
+  | "telegram"
+  | "personality"
+  | "confirm"
+  | "start-chat";
+
+type WizardState = {
+  step: Step;
+  provider: ProviderConfig;
+  botToken: string;
+  personality: Personality;
+};
+
+type WizardAction =
+  | { type: "SET_STEP"; step: Step }
+  | { type: "PATCH_PROVIDER"; patch: Partial<ProviderConfig> }
+  | { type: "SET_BOT_TOKEN"; value: string }
+  | { type: "SET_PERSONALITY"; value: Personality };
+
+const initialWizardState: WizardState = {
+  step: "provider-baseUrl",
+  provider: { baseUrl: "", apiKey: "", model: "" },
+  botToken: "",
+  personality: "Assistant",
+};
+
+function wizardReducer(state: WizardState, action: WizardAction): WizardState {
+  switch (action.type) {
+    case "SET_STEP":
+      return { ...state, step: action.step };
+    case "PATCH_PROVIDER":
+      return { ...state, provider: { ...state.provider, ...action.patch } };
+    case "SET_BOT_TOKEN":
+      return { ...state, botToken: action.value };
+    case "SET_PERSONALITY":
+      return { ...state, personality: action.value };
+    default: {
+      const _exhaustive: never = action;
+      return _exhaustive;
+    }
+  }
+}
+
+function OnboardingWizard({
+  onComplete,
+}: {
+  onComplete: (startChat: boolean) => void;
+}) {
+  const [state, dispatch] = useReducer(wizardReducer, initialWizardState);
+  const { step, provider, botToken, personality } = state;
+
+  const handleConfirm = async () => {
+    const config: OpenPawConfig = {
+      provider,
+      channels: botToken ? { telegram: { botToken } } : undefined,
+      personality,
+    };
+    await saveConfig(config);
+    ensureWorkspaceLayout();
+    dispatch({ type: "SET_STEP", step: "start-chat" });
+  };
+
+  switch (step) {
+    case "provider-baseUrl":
+      return (
+        <InputScreen
+          key={step}
+          title="Provider Configuration"
+          label="Enter the base URL for your LLM provider:"
+          value={provider.baseUrl}
+          onChange={(v) =>
+            dispatch({ type: "PATCH_PROVIDER", patch: { baseUrl: v } })
+          }
+          onSubmit={() =>
+            dispatch({ type: "SET_STEP", step: "provider-apiKey" })
+          }
+          placeholder="https://api.openai.com/v1"
+        />
+      );
+    case "provider-apiKey":
+      return (
+        <InputScreen
+          key={step}
+          title="Provider Configuration"
+          label="Enter your API key:"
+          value={provider.apiKey}
+          onChange={(v) =>
+            dispatch({ type: "PATCH_PROVIDER", patch: { apiKey: v } })
+          }
+          onSubmit={() =>
+            dispatch({ type: "SET_STEP", step: "provider-model" })
+          }
+          onBack={() =>
+            dispatch({ type: "SET_STEP", step: "provider-baseUrl" })
+          }
+          placeholder="sk-..."
+          password
+        />
+      );
+    case "provider-model":
+      return (
+        <InputScreen
+          key={step}
+          title="Provider Configuration"
+          label="Enter the model name:"
+          value={provider.model}
+          onChange={(v) =>
+            dispatch({ type: "PATCH_PROVIDER", patch: { model: v } })
+          }
+          onSubmit={() => dispatch({ type: "SET_STEP", step: "telegram" })}
+          onBack={() =>
+            dispatch({ type: "SET_STEP", step: "provider-apiKey" })
+          }
+          placeholder="gpt-4o"
+        />
+      );
+    case "telegram":
+      return (
+        <InputScreen
+          key={step}
+          title="Channel Configuration"
+          label="Enter your Telegram bot token:"
+          value={botToken}
+          onChange={(v) => dispatch({ type: "SET_BOT_TOKEN", value: v })}
+          onSubmit={() =>
+            dispatch({ type: "SET_STEP", step: "personality" })
+          }
+          onBack={() =>
+            dispatch({ type: "SET_STEP", step: "provider-model" })
+          }
+          placeholder="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
+          password
+        />
+      );
+    case "personality":
+      return (
+        <PersonalityScreen
+          key={step}
+          options={[...PERSONALITIES]}
+          onSelect={(index) => {
+            dispatch({
+              type: "SET_PERSONALITY",
+              value: PERSONALITIES[index] ?? "Assistant",
+            });
+            dispatch({ type: "SET_STEP", step: "confirm" });
+          }}
+          onBack={() => dispatch({ type: "SET_STEP", step: "telegram" })}
+        />
+      );
+    case "confirm":
+      return (
+        <ConfirmScreen
+          key={step}
+          config={{
+            provider,
+            channels: botToken ? { telegram: { botToken } } : undefined,
+            personality,
+          }}
+          onConfirm={handleConfirm}
+          onRestart={() =>
+            dispatch({ type: "SET_STEP", step: "provider-baseUrl" })
+          }
+          onBack={() =>
+            dispatch({ type: "SET_STEP", step: "personality" })
+          }
+        />
+      );
+    case "start-chat":
+      return (
+        <StartChatScreen
+          key={step}
+          onYes={() => onComplete(true)}
+          onNo={() => onComplete(false)}
+        />
+      );
+    default: {
+      const _exhaustive: never = step;
+      return _exhaustive;
+    }
+  }
+}
+
+function App() {
+  const [showWelcome, setShowWelcome] = useState(true);
+  const renderer = useRenderer();
+
+  useEffect(() => {
+    if (configExists()) {
+      deleteConfig();
+    }
+  }, []);
+
+  useKeyboard((key) => {
+    if (key.name === "escape") {
+      renderer.destroy();
+    }
+  });
+
+  const handleOnboardingComplete = (startChat: boolean) => {
+    renderer.destroy();
+    if (startChat) {
+      console.log("Starting chat...");
+    }
+  };
+
+  const dismissWelcome = useCallback(() => {
+    setShowWelcome(false);
+  }, []);
+
+  if (showWelcome) {
+    return <WelcomeScreen onComplete={dismissWelcome} />;
+  }
+
+  return <OnboardingWizard onComplete={handleOnboardingComplete} />;
+}
+
+export async function handleOnboard(options: {}) {
+  const renderer = await createCliRenderer({
+    exitOnCtrlC: true,
+  });
+  const root = createRoot(renderer);
+  root.render(<App />);
+}

package/cli/openpaw.tsx

@@ -0,0 +1,144 @@
+#!/usr/bin/env bun
+import { program } from "commander";
+import { startGateway } from "../gateway";
+import { runOpenPawTui } from "./tui";
+import { handleOnboard } from "./onboard";
+import { handleReset } from "./reset";
+import {
+  getGatewayDaemonStatus,
+  readGatewayDaemonLog,
+  startGatewayDaemon,
+  stopGatewayDaemon,
+} from "../gateway/daemon-manager";
+
+program.version("0.1.0").description("OpenPaw");
+
+program
+  .command("reset")
+  .description(
+    "Delete ~/.openpaw/workspace (sessions and files) and recreate onboarding default layout",
+  )
+  .action(() => {
+    try {
+      handleReset();
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("onboard")
+  .description("Go through the onboarding setup")
+  .action(handleOnboard);
+
+const gateway = program.command("gateway").description("Run messaging channel adapters (shared agent runtime)");
+
+gateway
+  .command("dev")
+  .description("Start all configured channels in foreground mode (blocking)")
+  .action(async () => {
+    try {
+      await startGateway();
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      process.exitCode = 1;
+    }
+  });
+
+gateway
+  .command("start")
+  .description("Start gateway daemon in background mode")
+  .action(() => {
+    try {
+      const result = startGatewayDaemon();
+      if (result.status === "already_running") {
+        console.log(
+          `OpenPaw gateway is already running (pid ${result.pid}). Logs: ${result.paths.logFile}`,
+        );
+        return;
+      }
+      console.log(
+        `OpenPaw gateway started in background (pid ${result.pid}). Logs: ${result.paths.logFile}`,
+      );
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      process.exitCode = 1;
+    }
+  });
+
+gateway
+  .command("stop")
+  .description("Stop gateway daemon")
+  .action(() => {
+    try {
+      const result = stopGatewayDaemon();
+      if (result.status === "already_stopped") {
+        console.log("OpenPaw gateway is not running.");
+        return;
+      }
+      console.log(`Stopped OpenPaw gateway daemon (pid ${result.pid}).`);
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      process.exitCode = 1;
+    }
+  });
+
+gateway
+  .command("status")
+  .description("Show gateway daemon status")
+  .action(() => {
+    try {
+      const status = getGatewayDaemonStatus();
+      if (status.state === "running") {
+        console.log(`OpenPaw gateway is running (pid ${status.pid}).`);
+        console.log(`stdout log: ${status.paths.logFile}`);
+        console.log(`stderr log: ${status.paths.errFile}`);
+        return;
+      }
+      if (status.state === "stale") {
+        console.log(`OpenPaw gateway had a stale pid (${status.pid}); pid file was cleaned.`);
+        return;
+      }
+      console.log("OpenPaw gateway is stopped.");
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      process.exitCode = 1;
+    }
+  });
+
+gateway
+  .command("logs")
+  .description("Print recent gateway daemon logs")
+  .option("--stderr", "Show stderr log instead of stdout")
+  .option("-n, --lines <count>", "Number of lines to show", "80")
+  .action((options: { stderr?: boolean; lines?: string }) => {
+    try {
+      const parsed = Number.parseInt(options.lines ?? "80", 10);
+      const lineCount = Number.isFinite(parsed) && parsed > 0 ? parsed : 80;
+      const stream = options.stderr ? "stderr" : "stdout";
+      const text = readGatewayDaemonLog(lineCount, stream);
+      if (!text) {
+        console.log("No daemon logs found yet.");
+        return;
+      }
+      console.log(text);
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("tui")
+  .description("Terminal chat UI (OpenTUI / local session), separate from the gateway process")
+  .action(async () => {
+    try {
+      await runOpenPawTui();
+    } catch (e) {
+      console.error(e instanceof Error ? e.message : e);
+      process.exitCode = 1;
+    }
+  });
+
+program.parse();

package/cli/reset.ts

@@ -0,0 +1,12 @@
+import { resetWorkspaceToOnboardingDefaults } from "../agent/workspace-bootstrap";
+import { getWorkspaceRoot } from "../config/paths";
+
+/**
+ * CLI handler: delete `~/.openpaw/workspace` and recreate the same layout and
+ * default markdown files as onboarding (`agents.md`, `soul.md`, `user.md`, empty `sessions/`).
+ */
+export function handleReset(): void {
+  const root = getWorkspaceRoot();
+  resetWorkspaceToOnboardingDefaults();
+  console.log(`Reset workspace: removed and recreated ${root} with onboarding defaults.`);
+}

package/cli/tui.tsx

@@ -0,0 +1,31 @@
+/**
+ * Entry for the `openpaw tui` subcommand: full-screen terminal chat against
+ * the local agent runtime (separate from the gateway process).
+ */
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { loadSessionMessages } from "../agent/session-store";
+import { createGatewayContext } from "../gateway/bootstrap";
+import { getTuiPersistenceSessionId } from "../gateway/tui/tui-active-thread-store";
+import { ChatApp } from "./components/chat-app";
+import { uiMessagesToChatLines } from "./lib/ui-messages-to-chat-transcript";
+
+/**
+ * Bootstraps config and workspace, then runs the OpenTUI chat until the user exits.
+ */
+export async function runOpenPawTui(): Promise<void> {
+  const ctx = await createGatewayContext();
+  const sessionId = await getTuiPersistenceSessionId();
+  const stored = await loadSessionMessages(sessionId, ctx.runtime.agent.tools);
+  const initialLines = uiMessagesToChatLines(stored);
+  const renderer = await createCliRenderer({
+    exitOnCtrlC: true,
+  });
+  createRoot(renderer).render(
+    <ChatApp
+      initialSessionId={sessionId}
+      initialLines={initialLines}
+      runtime={ctx.runtime}
+    />,
+  );
+}

package/config/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./paths";
+export * from "./storage";