nolo-cli 0.1.15 → 0.1.17

package/agent-runtime/index.ts

@@ -3,6 +3,7 @@ export const AGENT_RUNTIME_PACKAGE_ID = "agent-runtime";
 export { createRuntimeHostDescriptor } from "./hostAdapter";
 export { runLocalAgentTurn } from "./localLoop";
 export { resolveAgentRuntimeDecision } from "./runtimeDecision";
+export { buildAgentRuntimeDecisionInput } from "./runtimeFacts";
 export type {
   AgentRuntimeAgentConfig,
   AgentRuntimeHostAdapter,

package/agent-runtime/localLoop.ts

@@ -3,14 +3,16 @@ import type {
 } from "./hostAdapter";
 import type {
   AgentRuntimeChatMessage,
+  AgentRuntimeMessageContent,
   AgentRuntimeResult,
 } from "./types";
 
 export type LocalAgentTurnInput = {
   adapter: AgentRuntimeHostAdapter;
   agentRef: string;
-  input: string;
+  input: AgentRuntimeMessageContent;
   continueDialogId?: string;
+  maxToolRounds?: number;
 };
 
 export type LocalAgentTurnResult = AgentRuntimeResult & {
@@ -20,7 +22,7 @@ export type LocalAgentTurnResult = AgentRuntimeResult & {
 function buildMessages(args: {
   prompt?: string;
   history: AgentRuntimeChatMessage[];
-  input: string;
+  input: AgentRuntimeMessageContent;
 }): AgentRuntimeChatMessage[] {
   return [
     ...(args.prompt?.trim()
@@ -48,15 +50,48 @@ export async function runLocalAgentTurn(
     input: input.input,
   });
   const provider = await input.adapter.resolveProvider(agentConfig);
-  const result = await provider.complete(messages);
+  const maxToolRounds = input.maxToolRounds ?? 6;
+  let toolCallCount = 0;
+  let result: AgentRuntimeResult;
+  for (let round = 0; round <= maxToolRounds; round += 1) {
+    result = await provider.complete(messages);
+    const toolCalls = result.tool_calls ?? [];
+    if (toolCalls.length === 0) break;
+    if (round === maxToolRounds) {
+      throw new Error(`Local agent exceeded max tool rounds: ${maxToolRounds}`);
+    }
+    toolCallCount += toolCalls.length;
+    messages.push({
+      role: "assistant",
+      content: result.content || null,
+      tool_calls: toolCalls,
+    });
+    for (const toolCall of toolCalls) {
+      const toolResult = await input.adapter.executeTool({
+        id: toolCall.id,
+        name: toolCall.function.name,
+        arguments: toolCall.function.arguments,
+      });
+      messages.push({
+        role: "tool",
+        content: toolResult.content,
+        tool_call_id: toolCall.id,
+      });
+    }
+  }
+  result = result!;
   const saved = await input.adapter.saveTurn({
     agentKey: agentConfig.key,
     messages,
-    result,
+    result: {
+      ...result,
+      ...(toolCallCount > 0 ? { toolCallCount } : {}),
+    },
   });
 
   return {
     ...result,
+    ...(toolCallCount > 0 ? { toolCallCount } : {}),
     dialogId: saved.dialogId,
   };
 }

package/agent-runtime/runtimeFacts.ts

@@ -0,0 +1,40 @@
+import type {
+  AgentRuntimeDecisionInput,
+  AgentRuntimeHost,
+  AgentRuntimeRequestedMode,
+} from "./types";
+
+export type AgentRuntimeCapabilityFacts = {
+  host: AgentRuntimeHost;
+  requestedMode?: AgentRuntimeRequestedMode;
+  syncRequested?: boolean;
+  capabilities: string[];
+  requiresServer?: boolean;
+  serverFallbackAvailable: boolean;
+};
+
+export function buildAgentRuntimeDecisionInput(
+  facts: AgentRuntimeCapabilityFacts
+): AgentRuntimeDecisionInput {
+  const capabilities = new Set(facts.capabilities);
+  const hasLocalAgentConfig = capabilities.has("leveldb-agent-config") || capabilities.has("agent-config");
+  const hasLocalProvider = capabilities.has("local-provider") || capabilities.has("provider");
+  const hasLocalPersistence = capabilities.has("leveldb-persistence") || capabilities.has("persistence");
+  const missingLocalCapabilities = [
+    ...(hasLocalAgentConfig ? [] : ["agent-config"]),
+    ...(hasLocalProvider ? [] : ["provider"]),
+    ...(hasLocalPersistence ? [] : ["persistence"]),
+  ];
+
+  return {
+    host: facts.host,
+    ...(facts.requestedMode ? { requestedMode: facts.requestedMode } : {}),
+    syncRequested: Boolean(facts.syncRequested),
+    hasLocalAgentConfig,
+    hasLocalProvider,
+    hasLocalPersistence,
+    missingLocalCapabilities,
+    requiresServer: Boolean(facts.requiresServer),
+    serverFallbackAvailable: facts.serverFallbackAvailable,
+  };
+}

package/agent-runtime/types.ts

@@ -51,6 +51,7 @@ export interface AgentRuntimeResult {
   outputPrice?: number;
   usage?: Record<string, any>;
   trace?: AgentRuntimeChatMessage[];
+  tool_calls?: AgentRuntimeToolCall[];
   runtimeToolNames?: string[];
   toolCallCount?: number;
   policyState?: unknown;

package/agentPullCommand.ts

@@ -0,0 +1,146 @@
+import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
+import { getDefaultCliLocalRuntimeDb } from "./localRuntimeDb";
+import type { CliLocalRuntimeDb } from "./client/localRuntimeAdapter";
+
+type EnvLike = Record<string, string | undefined>;
+
+type OutputLike = {
+  write(chunk: string): unknown;
+};
+
+type AgentPullCommandDeps = {
+  env?: EnvLike;
+  output?: OutputLike;
+  db?: CliLocalRuntimeDb;
+  fetchImpl?: typeof fetch;
+};
+
+export type ParsedAgentPullArgs = {
+  agentKey: string;
+};
+
+function readFlagValue(args: string[], flag: string) {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function positionalArgs(args: string[]) {
+  const values: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg.startsWith("--")) {
+      index += 1;
+      continue;
+    }
+    values.push(arg);
+  }
+  return values;
+}
+
+export function parseAgentPullArgs(args: string[]): ParsedAgentPullArgs | null {
+  const agentKey = readFlagValue(args, "--agent") ?? positionalArgs(args)[0];
+  if (!agentKey?.trim()) return null;
+  return { agentKey: agentKey.trim() };
+}
+
+function resolveServerUrl(env: EnvLike) {
+  return (env.NOLO_SERVER || env.BASE_URL || DEFAULT_NOLO_SERVER_URL).replace(/\/+$/, "");
+}
+
+function resolveAuthToken(env: EnvLike) {
+  return env.AUTH_TOKEN || env.AUTH || env.BENCHMARK_AUTH_TOKEN || "";
+}
+
+function extractToolNames(record: any) {
+  if (Array.isArray(record?.toolNames)) return record.toolNames.filter((tool: unknown) => typeof tool === "string");
+  if (!Array.isArray(record?.tools)) return [];
+  return record.tools
+    .map((tool: any) => typeof tool === "string" ? tool : tool?.name)
+    .filter((tool: unknown): tool is string => typeof tool === "string" && tool.length > 0);
+}
+
+function normalizeAgentRecord(agentKey: string, record: any) {
+  return {
+    ...record,
+    dbKey: record?.dbKey || record?.key || agentKey,
+    key: record?.key || record?.dbKey || agentKey,
+    ...(typeof record?.provider === "string"
+      ? { provider: record.provider }
+      : typeof record?.apiSource === "string"
+        ? { provider: record.apiSource }
+        : {}),
+    toolNames: extractToolNames(record),
+    cachedBy: "nolo-cli",
+    cachedAt: new Date().toISOString(),
+  };
+}
+
+async function readRemoteAgent(args: {
+  agentKey: string;
+  serverUrl: string;
+  authToken: string;
+  fetchImpl: typeof fetch;
+}) {
+  const res = await args.fetchImpl(
+    `${args.serverUrl}/api/v1/db/read/${encodeURIComponent(args.agentKey)}`,
+    {
+      headers: {
+        ...(args.authToken ? { Authorization: `Bearer ${args.authToken}` } : {}),
+      },
+    }
+  );
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${JSON.stringify(data)}`);
+  }
+  return data?.data ?? data;
+}
+
+function writeUsage(output: OutputLike) {
+  output.write(
+    "Usage: nolo agent pull <agent>\n" +
+      "       nolo agent pull --agent <agent>\n"
+  );
+}
+
+export async function runAgentPullCommand(args: string[], deps: AgentPullCommandDeps = {}) {
+  const output = deps.output ?? process.stdout;
+  const env = deps.env ?? process.env;
+  const parsed = parseAgentPullArgs(args);
+  if (!parsed) {
+    writeUsage(output);
+    return 1;
+  }
+
+  const serverUrl = resolveServerUrl(env);
+  const authToken = resolveAuthToken(env);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const db = deps.db ?? await getDefaultCliLocalRuntimeDb();
+
+  let record: any;
+  try {
+    record = await readRemoteAgent({
+      agentKey: parsed.agentKey,
+      serverUrl,
+      authToken,
+      fetchImpl,
+    });
+  } catch (error) {
+    output.write(
+      `[nolo] Failed to pull ${parsed.agentKey} from ${serverUrl}: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+
+  if (!record || typeof record !== "object") {
+    output.write(`[nolo] Server returned an empty agent record for ${parsed.agentKey}.\n`);
+    return 1;
+  }
+
+  const localRecord = normalizeAgentRecord(parsed.agentKey, record);
+  await db.put(parsed.agentKey, localRecord);
+  output.write(`[nolo] cached ${parsed.agentKey} in local LevelDB\n`);
+  return 0;
+}

package/agentRunCommand.ts

@@ -1,6 +1,8 @@
 import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
 import { runAgentTurn, type RunAgentTurnResult } from "./client/agentRun";
 import type { AgentRuntimeRequestedMode } from "./agentRuntimeLocal";
+import { existsSync, readFileSync } from "node:fs";
+import { extname, resolve } from "node:path";
 
 type EnvLike = Record<string, string | undefined>;
 
@@ -18,6 +20,8 @@ type AgentRunCommandDeps = {
 type ParsedAgentRunArgs = {
   agentKey: string;
   message: string;
+  imageUrls: string[];
+  allowShell: boolean;
   runtimeMode?: AgentRuntimeRequestedMode;
   continueDialogId?: string;
 };
@@ -28,6 +32,17 @@ function readFlagValue(args: string[], flag: string) {
   return args[index + 1];
 }
 
+function readRepeatedFlagValues(args: string[], flag: string) {
+  const values: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag && args[index + 1]) {
+      values.push(args[index + 1]);
+      index += 1;
+    }
+  }
+  return values;
+}
+
 function runtimeModeFromArgs(args: string[]): AgentRuntimeRequestedMode | undefined {
   if (args.includes("--local")) return "local";
   if (args.includes("--server")) return "server";
@@ -37,9 +52,15 @@ function runtimeModeFromArgs(args: string[]): AgentRuntimeRequestedMode | undefi
 
 function positionalArgs(args: string[]) {
   const values: string[] = [];
+  const valuelessFlags = new Set([
+    "--local",
+    "--server",
+    "--auto",
+    "--dangerously-allow-shell",
+  ]);
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
-    if (arg === "--local" || arg === "--server" || arg === "--auto") continue;
+    if (valuelessFlags.has(arg)) continue;
     if (arg.startsWith("--")) {
       index += 1;
       continue;
@@ -56,14 +77,42 @@ export function parseAgentRunArgs(args: string[]): ParsedAgentRunArgs | null {
   if (!agentKey || !message.trim()) return null;
   const runtimeMode = runtimeModeFromArgs(args);
   const continueDialogId = readFlagValue(args, "--continue") ?? readFlagValue(args, "--dialog");
+  const imageUrls = [
+    ...readRepeatedFlagValues(args, "--image"),
+    ...readRepeatedFlagValues(args, "--image-url"),
+  ];
   return {
     agentKey,
     message: message.trim(),
+    imageUrls,
+    allowShell: args.includes("--dangerously-allow-shell"),
     ...(runtimeMode ? { runtimeMode } : {}),
     ...(continueDialogId ? { continueDialogId } : {}),
   };
 }
 
+function mimeTypeForPath(path: string) {
+  switch (extname(path).toLowerCase()) {
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".webp":
+      return "image/webp";
+    case ".gif":
+      return "image/gif";
+    default:
+      return "image/png";
+  }
+}
+
+export function normalizeCliImageInput(input: string) {
+  if (/^(https?:|data:|file:)/i.test(input)) return input;
+  const absolutePath = resolve(input);
+  if (!existsSync(absolutePath)) return input;
+  const base64 = readFileSync(absolutePath).toString("base64");
+  return `data:${mimeTypeForPath(absolutePath)};base64,${base64}`;
+}
+
 function resolveServerUrl(env: EnvLike) {
   return (env.NOLO_SERVER || env.BASE_URL || DEFAULT_NOLO_SERVER_URL).replace(/\/+$/, "");
 }
@@ -71,7 +120,7 @@ function resolveServerUrl(env: EnvLike) {
 function writeUsage(output: OutputLike) {
   output.write(
     "Usage: nolo agent run <agent> <message> [--local|--server|--auto] [--continue <dialogId>]\n" +
-      "       nolo agent run --agent <agent> --msg <message> [--local|--server|--auto]\n"
+      "       nolo agent run --agent <agent> --msg <message> [--image <url-or-path>] [--dangerously-allow-shell] [--local|--server|--auto]\n"
   );
 }
 
@@ -85,13 +134,17 @@ export async function runAgentRunCommand(args: string[], deps: AgentRunCommandDe
   }
 
   const runner = deps.runner ?? runAgentTurn;
+  const runEnv = parsed.allowShell
+    ? { ...env, NOLO_LOCAL_SHELL_MODE: "worktree" }
+    : env;
   const result: RunAgentTurnResult = await runner({
     agentName: parsed.agentKey,
     agentKey: parsed.agentKey,
     serverUrl: resolveServerUrl(env),
     message: parsed.message,
+    imageUrls: parsed.imageUrls.map(normalizeCliImageInput),
     scriptDir: deps.scriptDir,
-    env,
+    env: runEnv,
     output,
     ...(parsed.runtimeMode ? { runtimeMode: parsed.runtimeMode } : {}),
     ...(parsed.continueDialogId ? { continueDialogId: parsed.continueDialogId } : {}),

package/client/agentRun.test.ts

@@ -73,7 +73,34 @@ describe("cli agent run client", () => {
     expect(result).toEqual({ exitCode: 0, dialogId: "dialog-1" });
     expect(output.text()).toContain("nolo -> working");
     expect(output.text()).toContain("nolo > hi");
-    expect(output.text()).not.toContain("tokens=");
+    expect(output.text()).not.toContain("tokens=");
+  });
+
+  test("sends image inputs as multimodal userInput over HTTP", async () => {
+    const output = new CaptureOutput();
+    const requests: Array<{ body: any }> = [];
+
+    await runAgentTurn({
+      agentName: "vision",
+      agentKey: "agent-pub-vision",
+      serverUrl: "https://nolo.chat",
+      message: "describe this",
+      imageUrls: ["https://example.com/a.png"],
+      scriptDir: "C:/missing/scripts",
+      env: { AUTH_TOKEN: "token-123" },
+      output,
+      runtimeMode: "server",
+      scriptPathExists: () => false,
+      fetchImpl: async (_url, init) => {
+        requests.push({ body: JSON.parse(String(init?.body)) });
+        return Response.json({ content: "ok" });
+      },
+    });
+
+    expect(requests[0]?.body.userInput).toEqual([
+      { type: "text", text: "describe this" },
+      { type: "image_url", image_url: { url: "https://example.com/a.png" } },
+    ]);
   });
 
   test("runs forced local turns through the injected runtime adapter without HTTP", async () => {
@@ -121,6 +148,50 @@ describe("cli agent run client", () => {
     expect(output.text()).toContain("frontend > local:polish notifications");
   });
 
+  test("auto mode prefers a working local runtime before HTTP", async () => {
+    const output = new CaptureOutput();
+    const httpCalls: string[] = [];
+
+    const result = await runAgentTurn({
+      agentName: "frontend",
+      agentKey: "frontend-local",
+      serverUrl: "https://nolo.chat",
+      message: "polish notifications",
+      scriptDir: "C:/missing/scripts",
+      env: { AUTH_TOKEN: "token-123" },
+      output,
+      runtimeMode: "auto",
+      localRuntimeAdapter: {
+        host: "cli",
+        capabilities: ["leveldb-agent-config", "local-provider"],
+        loadAgentConfig: async (agentRef) => ({
+          key: agentRef,
+          name: "Frontend",
+          prompt: "Fix UI",
+          model: "fake-local",
+        }),
+        loadDialogHistory: async () => [],
+        saveTurn: async () => ({ dialogId: "dialog-auto-local" }),
+        resolveProvider: async () => ({
+          model: "fake-local",
+          complete: async () => ({ content: "auto local ok", model: "fake-local" }),
+        }),
+        executeTool: async () => {
+          throw new Error("no tools expected");
+        },
+      },
+      scriptPathExists: () => false,
+      fetchImpl: async (url) => {
+        httpCalls.push(String(url));
+        return Response.json({ content: "server" });
+      },
+    });
+
+    expect(result).toEqual({ exitCode: 0, dialogId: "dialog-auto-local" });
+    expect(httpCalls).toEqual([]);
+    expect(output.text()).toContain("frontend -> working locally");
+  });
+
   test("builds the default local adapter when env requests local mode", async () => {
     const output = new CaptureOutput();
     const builtModes: string[] = [];

package/client/agentRun.ts

@@ -11,12 +11,13 @@ type OutputLike = {
   write(chunk: string): unknown;
 };
 
-type RunAgentTurnOptions = {
-  agentName: string;
-  agentKey: string;
-  serverUrl: string;
-  message: string;
-  continueDialogId?: string;
+type RunAgentTurnOptions = {
+  agentName: string;
+  agentKey: string;
+  serverUrl: string;
+  message: string;
+  imageUrls?: string[];
+  continueDialogId?: string;
   scriptDir: string;
   env: EnvLike;
   output: OutputLike;
@@ -62,6 +63,28 @@ function buildDefaultLocalRuntimeAdapter(options: RunAgentTurnOptions) {
     fetchImpl: options.fetchImpl,
   });
 }
+
+function buildUserInputContent(message: string, imageUrls: string[] = []) {
+  if (imageUrls.length === 0) return message;
+  return [
+    ...(message.trim() ? [{ type: "text" as const, text: message }] : []),
+    ...imageUrls.map((url) => ({
+      type: "image_url" as const,
+      image_url: { url },
+    })),
+  ];
+}
+
+function shouldAttemptAutoLocal(options: RunAgentTurnOptions) {
+  if (options.localRuntimeAdapter || options.localRuntimeAdapterFactory) return true;
+  return Boolean(
+    options.env.NOLO_LOCAL_OPENAI_API_KEY ||
+      options.env.OPENAI_API_KEY ||
+      options.env.NOLO_LOCAL_OPENAI_BASE_URL ||
+      options.env.OPENAI_BASE_URL ||
+      options.env.NOLO_LOCAL_AGENT_KEY
+  );
+}
 
 function formatUsage(usage: any, dialogId: unknown) {
   const parts: string[] = [];
@@ -146,9 +169,9 @@ async function runHttpAgentTurn(options: RunAgentTurnOptions, authToken: string)
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
-        agentKey: options.agentKey,
-        userInput: options.message,
-        runtimeContext: {
+        agentKey: options.agentKey,
+        userInput: buildUserInputContent(options.message, options.imageUrls),
+        runtimeContext: {
           surface: "cli",
           host: "terminal",
           runtime: "bun",
@@ -204,6 +227,13 @@ async function runHttpAgentTurn(options: RunAgentTurnOptions, authToken: string)
 }
 
 async function runInjectedLocalAgentTurn(options: RunAgentTurnOptions) {
+  return runLocalAgentTurnForCli(options, { reportFailure: true });
+}
+
+async function runLocalAgentTurnForCli(
+  options: RunAgentTurnOptions,
+  settings: { reportFailure: boolean }
+) {
   const adapter =
     options.localRuntimeAdapter ||
     options.localRuntimeAdapterFactory?.(options.env) ||
@@ -218,7 +248,7 @@ async function runInjectedLocalAgentTurn(options: RunAgentTurnOptions) {
     const result = await runLocalAgentTurn({
       adapter,
       agentRef: options.agentKey,
-      input: options.message,
+      input: buildUserInputContent(options.message, options.imageUrls),
       continueDialogId: options.continueDialogId,
     });
     const content = result.content.trim();
@@ -229,12 +259,14 @@ async function runInjectedLocalAgentTurn(options: RunAgentTurnOptions) {
     }
     return { exitCode: 0, dialogId: result.dialogId };
   } catch (error) {
-    options.output.write(
-      `[nolo] Local agent run failed: ${
-        error instanceof Error ? error.message : String(error)
-      }\n`
-    );
-    return { exitCode: 1 };
+    if (settings.reportFailure) {
+      options.output.write(
+        `[nolo] Local agent run failed: ${
+          error instanceof Error ? error.message : String(error)
+        }\n`
+      );
+    }
+    return { exitCode: 1, localError: error };
   }
 }
 
@@ -340,11 +372,22 @@ export async function runAgentTurn(options: RunAgentTurnOptions) {
   const authToken = resolveAuthToken(options.env);
   const scriptPath = join(options.scriptDir, "chatWithAgent.ts");
   const scriptPathExists = (options.scriptPathExists ?? existsSync)(scriptPath);
+  const runtimeMode = resolveRequestedRuntimeMode(options);
 
-  if (resolveRequestedRuntimeMode(options) === "local") {
+  if (runtimeMode === "local") {
     return runInjectedLocalAgentTurn(options);
   }
 
+  if (runtimeMode === "auto" && shouldAttemptAutoLocal(options)) {
+    const localResult = await runLocalAgentTurnForCli(options, { reportFailure: false });
+    if (localResult.exitCode === 0) {
+      return {
+        exitCode: localResult.exitCode,
+        ...(localResult.dialogId ? { dialogId: localResult.dialogId } : {}),
+      };
+    }
+  }
+
   if (shouldUseScriptBridge({ hasAuthToken: Boolean(authToken), scriptPathExists })) {
     return runScriptBridge(options, scriptPath);
   }

package/client/localRuntimeAdapter.test.ts

@@ -120,7 +120,50 @@ describe("CLI local runtime adapter", () => {
     });
   });
 
-  test("rejects tools until local tool policy is implemented", async () => {
+  test("passes image_url message parts through to OpenAI-compatible providers", async () => {
+    const requests: Array<{ body: any }> = [];
+    const adapter = createCliLocalRuntimeAdapter({
+      env: {
+        OPENAI_API_KEY: "sk-local",
+        NOLO_LOCAL_OPENAI_BASE_URL: "http://127.0.0.1:11434/v1",
+      },
+      db: {
+        get: async () => ({
+          dbKey: "agent-local-vision",
+          prompt: "Describe images.",
+          model: "gpt-4.1-mini",
+        }),
+        put: async () => {},
+        batch: async () => {},
+        iterator: () => (async function* () {})(),
+      },
+      fetchImpl: async (_url, init) => {
+        requests.push({ body: JSON.parse(String(init?.body)) });
+        return Response.json({
+          choices: [{ message: { content: "image ok" } }],
+        });
+      },
+    });
+
+    await runLocalAgentTurn({
+      adapter,
+      agentRef: "vision",
+      input: [
+        { type: "text", text: "describe this" },
+        { type: "image_url", image_url: { url: "https://example.com/a.png" } },
+      ],
+    });
+
+    expect(requests[0]?.body.messages.at(-1)).toEqual({
+      role: "user",
+      content: [
+        { type: "text", text: "describe this" },
+        { type: "image_url", image_url: { url: "https://example.com/a.png" } },
+      ],
+    });
+  });
+
+  test("rejects tools unless the local tool policy allows and registers them", async () => {
     const adapter = createCliLocalRuntimeAdapter({
       env: {},
       fetchImpl: async () => Response.json({}),
@@ -130,6 +173,113 @@ describe("CLI local runtime adapter", () => {
       id: "call-1",
       name: "execShell",
       arguments: "{}",
-    })).rejects.toThrow("Local runtime tools are not enabled");
+    })).rejects.toThrow("execShell requires NOLO_LOCAL_SHELL_MODE");
+  });
+
+  test("executes explicitly allowed registered local tools declared by the agent", async () => {
+    const store = new Map<string, any>([
+      ["agent-user-1-reader", {
+        dbKey: "agent-user-1-reader",
+        id: "reader",
+        prompt: "Read files.",
+        toolNames: ["readFile"],
+      }],
+    ]);
+    const adapter = createCliLocalRuntimeAdapter({
+      env: {
+        NOLO_LOCAL_USER_ID: "user-1",
+        NOLO_LOCAL_ALLOWED_TOOLS: "readFile",
+      },
+      db: {
+        get: async (key) => {
+          if (!store.has(key)) throw new Error(`not found: ${key}`);
+          return store.get(key);
+        },
+        put: async () => {},
+        batch: async () => {},
+        iterator: () => (async function* () {})(),
+      },
+      localToolExecutors: {
+        readFile: async (call) => ({ content: `read:${call.arguments}` }),
+      },
+      fetchImpl: async () => Response.json({}),
+    });
+
+    await adapter.loadAgentConfig("reader");
+    const result = await adapter.executeTool({
+      id: "call-1",
+      name: "readFile",
+      arguments: "{\"path\":\"README.md\"}",
+    });
+
+    expect(result.content).toContain("README.md");
+  });
+
+  test("advertises execShell to OpenAI-compatible providers when the agent declares it", async () => {
+    const requests: Array<{ body: any }> = [];
+    const adapter = createCliLocalRuntimeAdapter({
+      env: {
+        OPENAI_API_KEY: "sk-local",
+        NOLO_LOCAL_OPENAI_BASE_URL: "http://127.0.0.1:11434/v1",
+        NOLO_LOCAL_SHELL_MODE: "worktree",
+      },
+      db: {
+        get: async () => ({
+          dbKey: "agent-local-shell",
+          prompt: "Use shell.",
+          model: "gpt-4.1-mini",
+          toolNames: ["execShell"],
+        }),
+        put: async () => {},
+        batch: async () => {},
+        iterator: () => (async function* () {})(),
+      },
+      fetchImpl: async (_url, init) => {
+        requests.push({ body: JSON.parse(String(init?.body)) });
+        return Response.json({
+          choices: [{ message: { content: "done" } }],
+        });
+      },
+    });
+
+    await runLocalAgentTurn({
+      adapter,
+      agentRef: "shell",
+      input: "pwd",
+    });
+
+    expect(requests[0]?.body.tools).toEqual([{
+      type: "function",
+      function: expect.objectContaining({
+        name: "execShell",
+      }),
+    }]);
+  });
+
+  test("runs execShell locally in explicit worktree shell mode", async () => {
+    const adapter = createCliLocalRuntimeAdapter({
+      env: { NOLO_LOCAL_SHELL_MODE: "worktree" },
+      db: {
+        get: async () => ({
+          dbKey: "agent-local-shell",
+          toolNames: ["execShell"],
+        }),
+        put: async () => {},
+        batch: async () => {},
+        iterator: () => (async function* () {})(),
+      },
+      cwd: import.meta.dir,
+      fetchImpl: async () => Response.json({}),
+    });
+
+    await adapter.loadAgentConfig("shell");
+    const result = await adapter.executeTool({
+      id: "call-1",
+      name: "execShell",
+      arguments: "{\"cmd\":\"pwd\"}",
+    });
+
+    expect(result.content).toContain(import.meta.dir);
+    expect(result.metadata).toMatchObject({ exitCode: 0 });
   });
 });

package/client/localRuntimeAdapter.ts

@@ -5,6 +5,7 @@ import type {
 } from "../agentRuntimeLocal";
 import type { AgentRuntimeChatMessage } from "../../agent-runtime";
 import { getDefaultCliLocalRuntimeDb } from "../localRuntimeDb";
+import { executeLocalToolWithPolicy } from "./localToolPolicy";
 
 type EnvLike = Record<string, string | undefined>;
 
@@ -21,6 +22,8 @@ export type CliLocalRuntimeAdapterDeps = {
   now?: () => number;
   createId?: () => string;
   fetchImpl?: typeof fetch;
+  cwd?: string;
+  localToolExecutors?: Record<string, (call: any) => Promise<{ content: string; metadata?: Record<string, unknown> }>>;
 };
 
 async function defaultLocalRuntimeDb(): Promise<CliLocalRuntimeDb> {
@@ -44,6 +47,77 @@ function resolveLocalUserId(env: EnvLike) {
   return env.NOLO_LOCAL_USER_ID || env.NOLO_USER_ID || "local";
 }
 
+function buildExecShellTool() {
+  return {
+    type: "function",
+    function: {
+      name: "execShell",
+      description: "Run a shell command in the current isolated local workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          cmd: {
+            type: "string",
+            description: "Shell command to run.",
+          },
+        },
+        required: ["cmd"],
+      },
+    },
+  };
+}
+
+function buildOpenAiTools(toolNames: string[] = []) {
+  return toolNames.includes("execShell") ? [buildExecShellTool()] : [];
+}
+
+function parseToolArguments(raw: string) {
+  try {
+    const parsed = JSON.parse(raw || "{}");
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function executeShellCommand(args: {
+  call: any;
+  cwd: string;
+}) {
+  const parsed = parseToolArguments(String(args.call.arguments ?? ""));
+  const cmd = String(parsed.cmd ?? parsed.command ?? "").trim();
+  if (!cmd) throw new Error("execShell requires a non-empty cmd argument.");
+  const proc = Bun.spawn(["/bin/sh", "-lc", cmd], {
+    cwd: args.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return {
+    content: [
+      stdout.trim() ? `stdout:\n${stdout.trim()}` : "",
+      stderr.trim() ? `stderr:\n${stderr.trim()}` : "",
+      `exitCode: ${exitCode}`,
+    ].filter(Boolean).join("\n\n"),
+    metadata: { exitCode },
+  };
+}
+
+function buildLocalToolExecutors(deps: CliLocalRuntimeAdapterDeps) {
+  return {
+    execShell: (call: any) => executeShellCommand({
+      call,
+      cwd: deps.cwd ?? process.cwd(),
+    }),
+    ...(deps.localToolExecutors ?? {}),
+  };
+}
+
 async function resolveDb(deps: CliLocalRuntimeAdapterDeps) {
   return deps.db ?? defaultLocalRuntimeDb();
 }
@@ -80,13 +154,7 @@ async function readAgentFromDb(args: {
 function toOpenAiMessages(messages: AgentRuntimeChatMessage[]) {
   return messages.map((message) => ({
     role: message.role,
-    content: typeof message.content === "string"
-      ? message.content
-      : Array.isArray(message.content)
-        ? message.content
-            .map((part) => part.type === "text" ? part.text : `[image:${part.image_url.url}]`)
-            .join("\n")
-        : "",
+    content: message.content ?? "",
   }));
 }
 
@@ -124,6 +192,14 @@ async function writeDialog(args: {
   const nowIso = new Date(now).toISOString();
   const dialogKey = `dialog-${args.userId}-${dialogId}`;
   const lastUser = [...args.input.messages].reverse().find((message) => message.role === "user");
+  const lastUserText = typeof lastUser?.content === "string"
+    ? lastUser.content
+    : Array.isArray(lastUser?.content)
+      ? lastUser.content
+          .filter((part) => part.type === "text")
+          .map((part) => part.text)
+          .join(" ")
+      : "";
   const ops: Array<{ type: "put"; key: string; value: any }> = [
     {
       type: "put",
@@ -135,8 +211,8 @@ async function writeDialog(args: {
         userId: args.userId,
         cybots: [args.input.agentKey],
         primaryAgentKey: args.input.agentKey,
-        title: typeof lastUser?.content === "string" && lastUser.content.trim()
-          ? lastUser.content.trim().slice(0, 80)
+        title: lastUserText.trim()
+          ? lastUserText.trim().slice(0, 80)
           : "Local agent run",
         status: "done",
         triggerType: "cli-local",
@@ -186,15 +262,21 @@ export function createCliLocalRuntimeAdapter(
   const createId = deps.createId ?? createFallbackId;
   const fetchImpl = deps.fetchImpl ?? fetch;
   const userId = resolveLocalUserId(deps.env);
+  let activeAgentToolNames: string[] = [];
+  const localToolExecutors = buildLocalToolExecutors(deps);
 
   return {
     host: "cli",
     capabilities: ["leveldb-agent-config", "local-provider", "leveldb-persistence"],
-    loadAgentConfig: async (agentRef) => readAgentFromDb({
-      agentRef,
-      db: await resolveDb(deps),
-      userId,
-    }),
+    loadAgentConfig: async (agentRef) => {
+      const agentConfig = await readAgentFromDb({
+        agentRef,
+        db: await resolveDb(deps),
+        userId,
+      });
+      activeAgentToolNames = agentConfig?.toolNames ?? [];
+      return agentConfig;
+    },
     loadDialogHistory: async (dialogId) => readDialogMessages({
       dialogId,
       db: await resolveDb(deps),
@@ -209,6 +291,7 @@ export function createCliLocalRuntimeAdapter(
     resolveProvider: async (agentConfig) => ({
       model: agentConfig.model || "gpt-4.1-mini",
       complete: async (messages) => {
+        const tools = buildOpenAiTools(agentConfig.toolNames ?? []);
         const res = await fetchImpl(`${resolveOpenAiCompatibleBaseUrl(deps.env)}/chat/completions`, {
           method: "POST",
           headers: {
@@ -221,24 +304,30 @@ export function createCliLocalRuntimeAdapter(
             model: agentConfig.model || "gpt-4.1-mini",
             messages: toOpenAiMessages(messages),
             stream: false,
+            ...(tools.length > 0 ? { tools } : {}),
           }),
         });
         const data = await res.json().catch(() => ({}));
         if (!res.ok) {
           throw new Error(`local provider failed: HTTP ${res.status} ${JSON.stringify(data)}`);
         }
-        const content = String(data?.choices?.[0]?.message?.content ?? "");
+        const choiceMessage = data?.choices?.[0]?.message ?? {};
+        const content = String(choiceMessage?.content ?? "");
         return {
           content,
           model: agentConfig.model || "gpt-4.1-mini",
           provider: agentConfig.provider || "openai-compatible",
+          ...(Array.isArray(choiceMessage?.tool_calls) ? { tool_calls: choiceMessage.tool_calls } : {}),
           usage: data?.usage,
           trace: messages,
         };
       },
     }),
-    executeTool: async () => {
-      throw new Error("Local runtime tools are not enabled for text-only CLI runs.");
-    },
+    executeTool: async (call) => executeLocalToolWithPolicy({
+      env: deps.env,
+      agentToolNames: activeAgentToolNames,
+      call,
+      executors: localToolExecutors,
+    }),
   };
 }

package/client/localToolPolicy.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+
+import { executeLocalToolWithPolicy, resolveLocalToolPolicy } from "./localToolPolicy";
+
+describe("CLI local tool policy", () => {
+  test("allows execShell in explicit worktree shell mode", () => {
+    expect(resolveLocalToolPolicy({
+      env: { NOLO_LOCAL_SHELL_MODE: "worktree" },
+      agentToolNames: ["execShell"],
+      toolName: "execShell",
+    })).toEqual({ allowed: true, toolName: "execShell" });
+  });
+
+  test("blocks execShell unless explicit shell mode is enabled", () => {
+    expect(resolveLocalToolPolicy({
+      env: { NOLO_LOCAL_ALLOWED_TOOLS: "execShell" },
+      agentToolNames: ["execShell"],
+      toolName: "execShell",
+    })).toMatchObject({ allowed: false });
+  });
+
+  test("requires both env allowlist and agent declaration", () => {
+    expect(resolveLocalToolPolicy({
+      env: { NOLO_LOCAL_ALLOWED_TOOLS: "readFile" },
+      agentToolNames: ["readFile"],
+      toolName: "readFile",
+    })).toEqual({ allowed: true, toolName: "readFile" });
+
+    expect(resolveLocalToolPolicy({
+      env: { NOLO_LOCAL_ALLOWED_TOOLS: "readFile" },
+      agentToolNames: [],
+      toolName: "readFile",
+    })).toMatchObject({ allowed: false });
+  });
+
+  test("executes only registered tools after policy allows them", async () => {
+    const result = await executeLocalToolWithPolicy({
+      env: { NOLO_LOCAL_ALLOWED_TOOLS: "readFile" },
+      agentToolNames: ["readFile"],
+      call: { id: "call-1", name: "readFile", arguments: "{\"path\":\"README.md\"}" },
+      executors: {
+        readFile: async (call) => ({ content: `read:${call.arguments}` }),
+      },
+    });
+
+    expect(result.content).toContain("README.md");
+  });
+});

package/client/localToolPolicy.ts

@@ -0,0 +1,85 @@
+import type { AgentRuntimeToolCallInput, AgentRuntimeToolResult } from "../../agent-runtime";
+
+type EnvLike = Record<string, string | undefined>;
+
+export type LocalToolPolicyDecision =
+  | { allowed: true; toolName: string }
+  | { allowed: false; toolName: string; reason: string };
+
+const NEVER_LOCAL_TOOLS = new Set([
+  "deleteSpaces",
+  "updateAgent",
+  "updateSelf",
+  "createAgent",
+]);
+
+function parseCsv(value: string | undefined) {
+  return (value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function resolveLocalToolPolicy(args: {
+  env: EnvLike;
+  agentToolNames?: string[];
+  toolName: string;
+}): LocalToolPolicyDecision {
+  if (args.toolName === "execShell") {
+    const shellMode = args.env.NOLO_LOCAL_SHELL_MODE || "";
+    const agentTools = new Set(args.agentToolNames ?? []);
+    if (
+      agentTools.has("execShell") &&
+      ["worktree", "dangerous", "1", "true"].includes(shellMode)
+    ) {
+      return { allowed: true, toolName: args.toolName };
+    }
+    return {
+      allowed: false,
+      toolName: args.toolName,
+      reason: "execShell requires NOLO_LOCAL_SHELL_MODE=worktree and an agent that declares execShell.",
+    };
+  }
+
+  if (NEVER_LOCAL_TOOLS.has(args.toolName)) {
+    return {
+      allowed: false,
+      toolName: args.toolName,
+      reason: `${args.toolName} is blocked by the local CLI safety policy.`,
+    };
+  }
+
+  const allowedByEnv = new Set(parseCsv(args.env.NOLO_LOCAL_ALLOWED_TOOLS));
+  const agentTools = new Set(args.agentToolNames ?? []);
+  if (allowedByEnv.has(args.toolName) && agentTools.has(args.toolName)) {
+    return { allowed: true, toolName: args.toolName };
+  }
+
+  return {
+    allowed: false,
+    toolName: args.toolName,
+    reason:
+      `${args.toolName} is not enabled for local CLI runs. ` +
+      "Set NOLO_LOCAL_ALLOWED_TOOLS and make sure the agent declares the tool before using it locally.",
+  };
+}
+
+export async function executeLocalToolWithPolicy(args: {
+  env: EnvLike;
+  agentToolNames?: string[];
+  call: AgentRuntimeToolCallInput;
+  executors?: Record<string, (call: AgentRuntimeToolCallInput) => Promise<AgentRuntimeToolResult>>;
+}): Promise<AgentRuntimeToolResult> {
+  const decision = resolveLocalToolPolicy({
+    env: args.env,
+    agentToolNames: args.agentToolNames,
+    toolName: args.call.name,
+  });
+  if (!decision.allowed) throw new Error(decision.reason);
+
+  const executor = args.executors?.[args.call.name];
+  if (!executor) {
+    throw new Error(`${args.call.name} is allowed by policy but no local executor is registered.`);
+  }
+  return executor(args.call);
+}

package/commandRegistry.ts

@@ -28,6 +28,7 @@ export const COMMANDS: CommandEntry[] = [
   { path: ["table", "meta"], script: "upsertTableMeta.ts", description: "Create or update table metadata" },
 
   { path: ["agent", "list"], script: "listMyAgents.ts", description: "List owned agents" },
+  { path: ["agent", "pull"], script: "", description: "Cache an agent for local runs" },
   { path: ["agent", "read"], script: "readAgent.ts", description: "Read a single agent" },
   { path: ["agent", "run"], script: "", description: "Run an agent" },
   { path: ["agent", "update"], script: "updateAgent.ts", description: "Update agent fields" },
@@ -94,6 +95,7 @@ export function renderHelpText() {
     '  nolo doc create --title "Trip Notes" --body "hello" --sync local,us --dry-run',
     '  nolo skill-doc create --title "Agent Query Skill" --description "Inspect recent agent dialogs" --sync local,main,us',
     "  nolo agent list --json",
+    "  nolo agent pull agent-pub-01APPBUILDER00000001YAII3I",
     "  nolo agent read agent-pub-01APPBUILDER00000001YAII3I",
     '  nolo agent run frontend-implementer --msg "polish notifications" --local',
     "  nolo agent bind-current agent-user-1-agent-1",

package/index.ts

@@ -12,6 +12,7 @@ import {
   runDoctorRuntimeCommand,
 } from "./agentRuntimeCommands";
 import { runAgentRunCommand } from "./agentRunCommand";
+import { runAgentPullCommand } from "./agentPullCommand";
 import { buildEnvFromProfile, loadProfileConfig } from "./client/profileConfig";
 import { resolveTuiLaunchMode } from "./runtimeModeArgs";
 import {
@@ -130,6 +131,10 @@ if (args[0] === "agent" && args[1] === "run") {
   }));
 }
 
+if (args[0] === "agent" && args[1] === "pull") {
+  process.exit(await runAgentPullCommand(args.slice(2), { env: runtimeEnv }));
+}
+
 if (args[0] === "agent" && args[1] === "runtime-doctor") {
   process.exit(await runAgentRuntimeDoctorCommand(args.slice(2), { env: runtimeEnv }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nolo-cli",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "description": "Agent-first terminal workspace for Nolo",
   "bin": {
@@ -12,6 +12,7 @@
     "agentRuntimeLocal.ts",
     "localRuntimeDb.ts",
     "agentRuntimeCommands.ts",
+    "agentPullCommand.ts",
     "agentRunCommand.ts",
     "authCommands.ts",
     "commandRegistry.ts",