nolo-cli 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @nolo/cli
+
+Agent-first terminal client for Nolo.
+
+`nolo` should be understood as the terminal workspace for Nolo agents. The
+existing command mode still wraps repo scripts, but the product direction is a
+TUI-first experience similar to Claude Code / Codex CLI:
+
+- open `nolo` and work inside a persistent Agent session;
+- chat with an Agent;
+- inspect and manage that Agent's dialogs, docs, tables, skills, and spaces;
+- run internal ops/doctor agents with the same mental model;
+- use non-interactive commands and `--json` for automation.
+
+The current MVP uses a dependency-free readline workspace. It is intentionally
+small: status line, text input, lightweight slash commands, and script-backed
+Agent chat. A richer Ink UI can replace the rendering layer later without
+changing the session model.
+
+## Usage
+
+```bash
+npm install -g nolo-cli
+nolo
+
+# update later
+npm update -g nolo-cli
+```
+
+The npm package expects Bun to be available because the executable is a Bun
+TypeScript script. For agent calls outside this repository, provide a token:
+
+```bash
+NOLO_SERVER=https://nolo.chat AUTH_TOKEN=<token> nolo
+```
+
+Local repo development can still use the script bridge without `AUTH_TOKEN`.
+
+```bash
+nolo --help
+nolo
+nolo chat
+nolo run "summarize my latest agent dialogs"
+nolo doc create --title "Trip Notes" --body "hello"
+nolo skill-doc create --title "Agent Query Skill" --description "Inspect recent agent dialogs"
+nolo agent list --json
+nolo chat --agent agent-pub-01APPBUILDER00000001YAII3I --msg "你好"
+```
+
+## Product Shape
+
+The preferred command model is Agent-first:
+
+```bash
+nolo agent list
+nolo agent switch <agent>
+nolo agent read <agent>
+nolo agent run <agent> "检查最近失败任务"
+nolo dialog list --agent <agent>
+nolo dialog read <dialog>
+nolo doc list --agent <agent>
+nolo table query <table> --agent <agent>
+```
+
+Inside the future TUI, the same actions should be available as slash commands:
+
+```text
+/agent list
+/agent switch ops
+/dialog open latest
+/doc list
+/table query builtin-dialog-probe-runs
+```
+
+See [`docs/nolo-cli-tui.md`](../../docs/nolo-cli-tui.md) for the product and
+technical direction.

package/client/agentRun.ts

@@ -0,0 +1,139 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+type EnvLike = Record<string, string | undefined>;
+
+type OutputLike = {
+  write(chunk: string): unknown;
+};
+
+type RunAgentTurnOptions = {
+  agentName: string;
+  agentKey: string;
+  serverUrl: string;
+  message: string;
+  scriptDir: string;
+  env: EnvLike;
+  output: OutputLike;
+  scriptPathExists?: (path: string) => boolean;
+  fetchImpl?: typeof fetch;
+};
+
+type ScriptBridgeDecision = {
+  hasAuthToken: boolean;
+  scriptPathExists: boolean;
+};
+
+export function shouldUseScriptBridge(decision: ScriptBridgeDecision) {
+  return !decision.hasAuthToken && decision.scriptPathExists;
+}
+
+function resolveAuthToken(env: EnvLike) {
+  return env.AUTH_TOKEN || env.AUTH || env.BENCHMARK_AUTH_TOKEN || "";
+}
+
+function formatUsage(usage: any, dialogId: unknown) {
+  const parts: string[] = [];
+  if (typeof dialogId === "string" && dialogId) parts.push(`dialog=${dialogId}`);
+
+  const input = usage?.input_tokens ?? usage?.prompt_tokens ?? 0;
+  const output = usage?.output_tokens ?? usage?.completion_tokens ?? 0;
+  if (input || output) parts.push(`tokens=${input}+${output}`);
+
+  return parts.length ? `  (${parts.join("  ")})` : "";
+}
+
+async function runScriptBridge(options: RunAgentTurnOptions, scriptPath: string) {
+  options.output.write(`\n${options.agentName} -> working via local script...\n\n`);
+  const proc = Bun.spawn({
+    cmd: [
+      process.execPath,
+      scriptPath,
+      "--agent",
+      options.agentKey,
+      "--server",
+      options.serverUrl,
+      "--msg",
+      options.message,
+      "--no-default-test-root",
+    ],
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env: {
+      ...process.env,
+      ...options.env,
+      ASSISTANT_LABEL: options.agentName,
+    },
+  });
+
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    options.output.write(`\n[nolo] Agent run exited with code ${exitCode}.\n`);
+  }
+  return exitCode;
+}
+
+async function runHttpAgentTurn(options: RunAgentTurnOptions, authToken: string) {
+  options.output.write(`\n${options.agentName} -> working...\n\n`);
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const res = await fetchImpl(`${options.serverUrl}/api/agent/run`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      agentKey: options.agentKey,
+      userInput: options.message,
+      stream: false,
+    }),
+  });
+
+  let data: any = {};
+  try {
+    data = await res.json();
+  } catch {
+    data = {};
+  }
+
+  if (!res.ok) {
+    options.output.write(`[nolo] Agent request failed: HTTP ${res.status}\n`);
+    if (data?.error || data?.message) {
+      options.output.write(`${data.error || data.message}\n`);
+    }
+    return 1;
+  }
+
+  const content = String(data?.content ?? data?.message ?? "").trim();
+  if (content) {
+    options.output.write(`${options.agentName}: ${content}\n`);
+  } else {
+    options.output.write(`${options.agentName}: (no text response)\n`);
+  }
+
+  const usage = formatUsage(data?.usage, data?.dialogId);
+  if (usage) options.output.write(`${usage}\n`);
+  return 0;
+}
+
+export async function runAgentTurn(options: RunAgentTurnOptions) {
+  const authToken = resolveAuthToken(options.env);
+  const scriptPath = join(options.scriptDir, "chatWithAgent.ts");
+  const scriptPathExists = (options.scriptPathExists ?? existsSync)(scriptPath);
+
+  if (shouldUseScriptBridge({ hasAuthToken: Boolean(authToken), scriptPathExists })) {
+    return runScriptBridge(options, scriptPath);
+  }
+
+  if (!authToken) {
+    options.output.write(
+      "[nolo] This install needs an auth token before it can talk to agents.\n" +
+        "Set AUTH_TOKEN, or use the repo-local CLI where the dev script bridge is available.\n"
+    );
+    return 1;
+  }
+
+  return runHttpAgentTurn(options, authToken);
+}

package/commandRegistry.ts

@@ -0,0 +1,95 @@
+export type CommandEntry = {
+  path: string[];
+  script: string;
+  description: string;
+};
+
+export const COMMANDS: CommandEntry[] = [
+  { path: ["chat"], script: "chatWithAgent.ts", description: "Chat with an agent" },
+
+  { path: ["doc", "create"], script: "createDoc.ts", description: "Create a normal doc" },
+  { path: ["doc", "read"], script: "readDoc.ts", description: "Read a normal doc" },
+  { path: ["doc", "update"], script: "updateDoc.ts", description: "Update a normal doc" },
+  { path: ["doc", "delete"], script: "deleteDoc.ts", description: "Delete a normal doc" },
+
+  { path: ["skill-doc", "create"], script: "createSkillDoc.ts", description: "Create a skill doc" },
+  { path: ["skill-doc", "read"], script: "readSkillDoc.ts", description: "Read a skill doc" },
+  { path: ["skill-doc", "update"], script: "updateSkillDoc.ts", description: "Update a skill doc" },
+  { path: ["skill-doc", "delete"], script: "deleteSkillDoc.ts", description: "Delete a skill doc" },
+
+  { path: ["dialog", "read"], script: "readDialog.ts", description: "Read a dialog" },
+  { path: ["space", "read"], script: "readSpace.ts", description: "Read a space" },
+  { path: ["space", "category"], script: "upsertSpaceCategory.ts", description: "Create or update a space category" },
+  { path: ["space", "content-category"], script: "setSpaceContentCategory.ts", description: "Move content into a space category" },
+
+  { path: ["table", "data"], script: "tableData.ts", description: "Query or mutate table rows" },
+  { path: ["table", "meta"], script: "upsertTableMeta.ts", description: "Create or update table metadata" },
+
+  { path: ["agent", "list"], script: "listMyAgents.ts", description: "List owned agents" },
+  { path: ["agent", "read"], script: "readAgent.ts", description: "Read a single agent" },
+  { path: ["agent", "update"], script: "updateAgent.ts", description: "Update agent fields" },
+  { path: ["agent", "unpublish"], script: "unpublishAgent.ts", description: "Remove an agent's public record" },
+  { path: ["agent", "chat"], script: "chatWithAgent.ts", description: "Chat with an agent" },
+  { path: ["agent", "dialogs"], script: "queryAgentDialogs.ts", description: "Inspect recent dialogs for an agent" },
+  { path: ["agent", "doctor"], script: "doctorAgentWorkspace.ts", description: "Audit agent workspace health" },
+  { path: ["agent", "create-custom"], script: "createCustomCodingAgent.ts", description: "Create a custom coding agent" },
+  { path: ["agent", "create-space"], script: "createSpaceAgents.ts", description: "Create or attach shared-space agents" },
+  { path: ["agent", "setup-demo"], script: "setupDemoAgent.ts", description: "Bootstrap demo publisher agents" },
+  { path: ["agent", "supervise"], script: "runAutonomousAgent.ts", description: "Run an agent in autonomous cycles" },
+
+  { path: ["llama"], script: "llamaServerSupervisor.ts", description: "Manage the llama.cpp runtime" },
+  { path: ["model-runtime"], script: "localModelRuntimeSupervisor.ts", description: "Manage local model runtime processes" },
+  { path: ["dev"], script: "devControl.ts", description: "Manage the local dev environment" },
+];
+
+export const GROUP_ORDER = [
+  "chat",
+  "doc",
+  "skill-doc",
+  "agent",
+  "dialog",
+  "space",
+  "table",
+  "llama",
+  "model-runtime",
+  "dev",
+] as const;
+
+export function renderHelpText() {
+  const lines = [
+    "nolo — Agent-first terminal workspace",
+    "",
+    "Usage:",
+    "  nolo",
+    "  nolo <command> [subcommand] [...args]",
+    "",
+    "Examples:",
+    "  nolo",
+    "  nolo chat",
+    '  nolo doc create --title "Trip Notes" --body "hello"',
+    '  nolo skill-doc create --title "Agent Query Skill" --description "Inspect recent agent dialogs"',
+    "  nolo agent list --json",
+    "  nolo agent read agent-pub-01APPBUILDER00000001YAII3I",
+    '  nolo chat --agent agent-pub-01APPBUILDER00000001YAII3I --msg "你好"',
+    "  nolo table data --table 01ABCXYZ --action query",
+    "  nolo llama status",
+  ];
+
+  for (const group of GROUP_ORDER) {
+    const commands = COMMANDS.filter((entry) => entry.path[0] === group);
+    if (commands.length === 0) continue;
+    lines.push("", group);
+    for (const entry of commands) {
+      lines.push(`  ${entry.path.join(" ")}  ${entry.description}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function resolveCommand(args: string[]) {
+  const sorted = [...COMMANDS].sort((a, b) => b.path.length - a.path.length);
+  return sorted.find((entry) =>
+    entry.path.every((part, index) => args[index] === part)
+  );
+}

package/index.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { renderHelpText, resolveCommand } from "./commandRegistry";
+import { startTuiWorkspace } from "./tui/readlineWorkspace";
+
+const CLI_DIR = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(CLI_DIR, "..", "..");
+const SCRIPT_DIR = join(ROOT_DIR, "scripts");
+
+async function runScript(script: string, forwardedArgs: string[]) {
+  const scriptPath = join(SCRIPT_DIR, script);
+  const proc = Bun.spawn({
+    cmd: [process.execPath, scriptPath, ...forwardedArgs],
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env: process.env,
+  });
+  const exitCode = await proc.exited;
+  process.exit(exitCode);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  if (process.stdin.isTTY) {
+    await startTuiWorkspace({ scriptDir: SCRIPT_DIR });
+  } else {
+    console.log(renderHelpText());
+  }
+  process.exit(0);
+}
+
+if (args.length === 1 && (args[0] === "tui" || args[0] === "chat")) {
+  await startTuiWorkspace({ scriptDir: SCRIPT_DIR });
+  process.exit(0);
+}
+
+if (args[0] === "--help" || args[0] === "-h") {
+  console.log(renderHelpText());
+  process.exit(0);
+}
+
+const command = resolveCommand(args);
+if (!command) {
+  console.error(`Unknown command: ${args.join(" ")}`);
+  console.error("");
+  console.log(renderHelpText());
+  process.exit(1);
+}
+
+const forwardedArgs = args.slice(command.path.length);
+await runScript(command.script, forwardedArgs);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "nolo-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Agent-first terminal workspace for Nolo",
+  "bin": {
+    "nolo": "./index.ts"
+  },
+  "module": "index.ts",
+  "files": [
+    "index.ts",
+    "commandRegistry.ts",
+    "client/agentRun.ts",
+    "tui/readlineWorkspace.ts",
+    "tui/session.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "bun-types": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/tui/readlineWorkspace.ts

@@ -0,0 +1,79 @@
+import { createInterface } from "node:readline";
+import { stdin as defaultInput, stdout as defaultOutput } from "node:process";
+import { runAgentTurn } from "../client/agentRun";
+import {
+  createInitialTuiState,
+  handleTuiInput,
+  renderPrompt,
+  renderStatusLine,
+  renderWelcome,
+  type TuiState,
+} from "./session";
+
+type WorkspaceOptions = {
+  scriptDir: string;
+  env?: NodeJS.ProcessEnv;
+  input?: NodeJS.ReadableStream;
+  output?: NodeJS.WritableStream;
+};
+
+async function runAgentChat(
+  scriptDir: string,
+  state: TuiState,
+  message: string,
+  env: NodeJS.ProcessEnv,
+  output: NodeJS.WritableStream
+) {
+  const exitCode = await runAgentTurn({
+    agentName: state.agentName,
+    agentKey: state.agentKey,
+    serverUrl: state.serverUrl,
+    message,
+    scriptDir,
+    env,
+    output,
+  });
+  return exitCode;
+}
+
+export async function startTuiWorkspace(options: WorkspaceOptions) {
+  let state = createInitialTuiState(options.env ?? process.env);
+  const input = options.input ?? defaultInput;
+  const output = options.output ?? defaultOutput;
+  const rl = createInterface({ input, output });
+
+  output.write(renderWelcome(state));
+  rl.setPrompt(renderPrompt(state));
+  rl.prompt();
+
+  try {
+    for await (const line of rl) {
+      const result = handleTuiInput(line, state);
+      state = result.nextState;
+
+      if (result.output) {
+        output.write(`${result.output}\n`);
+      }
+
+      if (result.action?.type === "exit") {
+        break;
+      }
+
+      if (result.action?.type === "chat") {
+        await runAgentChat(
+          options.scriptDir,
+          state,
+          result.action.message,
+          options.env ?? process.env,
+          output
+        );
+      }
+
+      output.write(`\n${renderStatusLine(state)}\n`);
+      rl.setPrompt(renderPrompt(state));
+      rl.prompt();
+    }
+  } finally {
+    rl.close();
+  }
+}

package/tui/session.ts

@@ -0,0 +1,232 @@
+export const DEFAULT_TUI_AGENT_KEY = "agent-pub-01NOLOAPPBLD000000019KCKT0";
+export const DEFAULT_TUI_SERVER_URL = "http://127.0.0.1:38123";
+
+const KNOWN_AGENT_ALIASES: Record<string, { name: string; key: string }> = {
+  nolo: {
+    name: "nolo",
+    key: DEFAULT_TUI_AGENT_KEY,
+  },
+  "app-builder": {
+    name: "app-builder",
+    key: "agent-pub-01APPBUILDER00000001YAII3I",
+  },
+};
+
+export type TuiState = {
+  agentKey: string;
+  agentName: string;
+  dialogLabel: string;
+  profileName: string;
+  serverUrl: string;
+  attachedDocs: string[];
+};
+
+export type TuiAction =
+  | {
+      type: "chat";
+      message: string;
+      agentKey: string;
+    }
+  | {
+      type: "exit";
+    };
+
+export type TuiInputResult = {
+  nextState: TuiState;
+  output: string;
+  action?: TuiAction;
+};
+
+type EnvLike = Record<string, string | undefined>;
+
+export function createInitialTuiState(env: EnvLike = process.env): TuiState {
+  const agentKey = env.NOLO_AGENT?.trim() || DEFAULT_TUI_AGENT_KEY;
+  const agentName = env.NOLO_AGENT_NAME?.trim() || "nolo";
+
+  return {
+    agentKey,
+    agentName,
+    dialogLabel: env.NOLO_DIALOG?.trim() || "new",
+    profileName: env.NOLO_PROFILE?.trim() || "local",
+    serverUrl: (env.NOLO_SERVER || env.BASE_URL || DEFAULT_TUI_SERVER_URL).replace(/\/+$/, ""),
+    attachedDocs: [],
+  };
+}
+
+export function renderStatusLine(state: TuiState) {
+  const docs =
+    state.attachedDocs.length > 0
+      ? state.attachedDocs.join(", ")
+      : "0 attached";
+
+  return [
+    `agent ${state.agentName}`,
+    `dialog ${state.dialogLabel}`,
+    `docs ${docs}`,
+    `profile ${state.profileName}`,
+  ].join(" | ");
+}
+
+export function renderWelcome(state: TuiState) {
+  return [
+    "",
+    "Nolo workspace",
+    "--------------",
+    `agent   ${state.agentName}`,
+    `dialog  ${state.dialogLabel}`,
+    `docs    ${state.attachedDocs.length ? state.attachedDocs.join(", ") : "none"}`,
+    `profile ${state.profileName}`,
+    `server  ${state.serverUrl}`,
+    "",
+    "Tell nolo what you want. Use /help for commands.",
+    "",
+  ].join("\n");
+}
+
+export function renderPrompt(_state: TuiState) {
+  return "you > ";
+}
+
+export function renderTuiHelp() {
+  return [
+    "Commands:",
+    "  /help                 Show this help",
+    "  /new                  Start a fresh dialog label",
+    "  /agent                Show the current agent",
+    "  /switch <agent>       Switch the current agent",
+    "  /dialog               Show the current dialog",
+    "  /doc                  List attached docs",
+    "  /doc attach <doc>     Attach a doc to this workspace",
+    "  /customize            Describe how you want to tune nolo",
+    "  /login                Show login/profile hint",
+    "  /profile              Show active profile",
+    "  /exit                 Leave the workspace",
+    "",
+    "You can also type normally. nolo will send it to the current agent.",
+  ].join("\n");
+}
+
+function resolveSwitchTarget(rawTarget: string) {
+  const target = rawTarget.trim();
+  const alias = KNOWN_AGENT_ALIASES[target.toLowerCase()];
+  if (alias) return alias;
+  if (/^\d+$/.test(target)) return null;
+  if (target.startsWith("agent-") || target.startsWith("agent-pub-")) {
+    return { name: target, key: target };
+  }
+  return null;
+}
+
+export function handleTuiInput(input: string, state: TuiState): TuiInputResult {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return { nextState: state, output: "" };
+  }
+
+  if (!trimmed.startsWith("/")) {
+    return {
+      nextState: state,
+      output: "",
+      action: {
+        type: "chat",
+        message: trimmed,
+        agentKey: state.agentKey,
+      },
+    };
+  }
+
+  const [command = "", ...rest] = trimmed.split(/\s+/);
+  const argText = rest.join(" ").trim();
+
+  switch (command) {
+    case "/help":
+      return { nextState: state, output: renderTuiHelp() };
+    case "/exit":
+    case "/quit":
+      return { nextState: state, output: "Bye.", action: { type: "exit" } };
+    case "/new":
+      return {
+        nextState: { ...state, dialogLabel: "new", attachedDocs: [] },
+        output: "Started a fresh workspace.",
+      };
+    case "/agent":
+      return {
+        nextState: state,
+        output: `Current agent: ${state.agentName} (${state.agentKey})`,
+      };
+    case "/switch": {
+      if (!argText) {
+        return {
+          nextState: state,
+          output: "Usage: /switch <agent-key|alias>",
+        };
+      }
+      const resolvedTarget = resolveSwitchTarget(argText);
+      if (!resolvedTarget) {
+        return {
+          nextState: state,
+          output:
+            `I don't know agent shortcut "${argText}" yet.\n` +
+            "Use /switch nolo, /switch app-builder, or a full agent key like agent-pub-...",
+        };
+      }
+      return {
+        nextState: {
+          ...state,
+          agentName: resolvedTarget.name,
+          agentKey: resolvedTarget.key,
+        },
+        output: `Switched to ${resolvedTarget.name}.`,
+      };
+    }
+    case "/dialog":
+      return {
+        nextState: state,
+        output: `Current dialog: ${state.dialogLabel}`,
+      };
+    case "/doc": {
+      if (rest[0] === "attach") {
+        const docName = rest.slice(1).join(" ").trim();
+        if (!docName) {
+          return { nextState: state, output: "Usage: /doc attach <doc>" };
+        }
+        const attachedDocs = state.attachedDocs.includes(docName)
+          ? state.attachedDocs
+          : [...state.attachedDocs, docName];
+        return {
+          nextState: { ...state, attachedDocs },
+          output: `Attached doc: ${docName}`,
+        };
+      }
+      return {
+        nextState: state,
+        output:
+          state.attachedDocs.length > 0
+            ? `Attached docs: ${state.attachedDocs.join(", ")}`
+            : "No docs attached. Use /doc attach <doc>.",
+      };
+    }
+    case "/customize":
+      return {
+        nextState: state,
+        output:
+          "Tell nolo what to change, for example: /customize make my default agent more concise.",
+      };
+    case "/login":
+      return {
+        nextState: state,
+        output:
+          "MVP login uses profile/env auth. Set AUTH_TOKEN, NOLO_SERVER, or NOLO_PROFILE before starting nolo.",
+      };
+    case "/profile":
+      return {
+        nextState: state,
+        output: `Profile: ${state.profileName}`,
+      };
+    default:
+      return {
+        nextState: state,
+        output: `Unknown command: ${command}\n\n${renderTuiHelp()}`,
+      };
+  }
+}