hoomanjs 1.12.0 → 1.13.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>Hooman</h1>
   <p>
-    Hooman is a Bun-powered local AI agent CLI built with TypeScript, <a href="https://www.npmjs.com/package/@strands-agents/sdk">Strands Agents SDK</a>, and <a href="https://github.com/vadimdemedes/ink">Ink</a>.
+    Hooman is a hackable, Bun-powered AI agent toolkit for local workflows. It is built with TypeScript, <a href="https://www.npmjs.com/package/@strands-agents/sdk">Strands Agents SDK</a>, and <a href="https://github.com/vadimdemedes/ink">Ink</a>.
   </p>
   <p>
     <a href="https://bun.com"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun&logoColor=000000" alt="Bun" /></a>
@@ -16,12 +16,12 @@
   </p>
 </div>
 
-It gives you:
+It gives you a practical toolkit to build and run agent workflows:
 
 - a one-shot `exec` command for single prompts
-- a stateful `chat` interface for interactive sessions
-- a `daemon` command for processing MCP channel notifications in background
-- an Ink-powered `configure` workflow for editing app config, `instructions.md`, MCP servers, and installed skills
+- a stateful `chat` interface for iterative sessions
+- a `daemon` command for channel-driven MCP automation
+- an Ink-powered `configure` workflow for app config, prompts, MCP servers, and installed skills
 - an `acp` command for running Hooman as an Agent Client Protocol (ACP) agent over stdio
 
 ## Features
@@ -32,6 +32,7 @@ It gives you:
 - MCP server `instructions` support: server-provided instructions are appended to the agent system prompt
 - MCP channel notification support through `hooman daemon --channels`
 - Skill discovery / install / removal through the integrated configure flow
+- Toolkit-oriented architecture with configurable tools, prompts, memory, and transports
 - Interactive terminal UI for chat and configuration
 
 ## Requirements
@@ -157,18 +158,21 @@ hooman daemon --channels --yolo
 
 ### Feature Flags
 
-Runtime tools and prompt sections are controlled from `config.json` under `features`:
+Runtime tools and prompt sections are controlled from `config.json` under `tools`:
 
-- `features.fetch.enabled`
-- `features.filesystem.enabled`
-- `features.shell.enabled`
-- `features.ltm.enabled`
-- `features.wiki.enabled`
+- `tools.todo.enabled`
+- `tools.fetch.enabled`
+- `tools.filesystem.enabled`
+- `tools.shell.enabled`
+- `tools.ltm.enabled`
+- `tools.wiki.enabled`
+- `tools.mcp.enabled` (enables MCP management tools + prefixed MCP server tools/instructions)
+- `tools.skills.enabled` (enables skills management tools + skills prompt sections)
 
 Both `ltm` and `wiki` include dedicated Chroma settings under:
 
-- `features.ltm.chroma` (default collection: `memory`)
-- `features.wiki.chroma` (default collection: `wiki`)
+- `tools.ltm.chroma` (default collection: `memory`)
+- `tools.wiki.chroma` (default collection: `wiki`)
 
 ### `hooman configure`
 
@@ -211,7 +215,7 @@ Hooman stores its data in:
 
 Important files and folders:
 
-- `config.json` - app name, LLM provider/model, tool approvals, feature flags, LTM/wiki settings, compaction
+- `config.json` - app name, LLM provider/model, tool flags, LTM/wiki settings, compaction
 - `instructions.md` - system instructions used to build the agent prompt
 - `mcp.json` - MCP server definitions
 - `skills/` - installed skills
@@ -231,9 +235,9 @@ This is the shape managed by `hooman configure`:
     "params": {}
   },
   "tools": {
-    "allowed": []
-  },
-  "features": {
+    "todo": {
+      "enabled": true
+    },
     "fetch": {
       "enabled": true
     },
@@ -260,6 +264,12 @@ This is the shape managed by `hooman configure`:
           "wiki": "wiki"
         }
       }
+    },
+    "mcp": {
+      "enabled": false
+    },
+    "skills": {
+      "enabled": false
     }
   },
   "compaction": {
@@ -269,6 +279,8 @@ This is the shape managed by `hooman configure`:
 }
 ```
 
+Tool approvals are session-scoped and are not persisted in `config.json`.
+
 Supported `llm.provider` values:
 
 - `ollama`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoomanjs",
-  "version": "1.12.0",
-  "description": "Bun-powered local AI agent CLI with chat, exec, ACP, MCP, and skills support.",
+  "version": "1.13.0",
+  "description": "Hackable Bun-powered AI agent toolkit for building local CLI, ACP, MCP, and channel-driven workflows.",
   "author": {
     "name": "Vaibhav Pandey",
     "email": "contact@vaibhavpandey.com"

package/src/acp/sessions/config-options.ts

@@ -7,11 +7,25 @@ import type { Config } from "../../core/config.ts";
 
 export const HOOMAN_LTM_CONFIG_ID = "hooman.longTermMemory" as const;
 export const HOOMAN_WIKI_CONFIG_ID = "hooman.wiki" as const;
+export const HOOMAN_TODO_CONFIG_ID = "hooman.todo" as const;
 
 export function buildSessionConfigOptions(
   config: Config,
 ): SessionConfigOption[] {
   return [
+    {
+      type: "select",
+      id: HOOMAN_TODO_CONFIG_ID,
+      name: "Todo tracking",
+      description:
+        "When enabled, the agent can use update_todos to track multi-step progress in app state.",
+      category: "_hooman",
+      currentValue: config.tools.todo.enabled ? "on" : "off",
+      options: [
+        { value: "on", name: "On" },
+        { value: "off", name: "Off" },
+      ],
+    },
     {
       type: "select",
       id: HOOMAN_LTM_CONFIG_ID,
@@ -51,6 +65,7 @@ export function applySessionConfigOption(
     });
   }
   if (
+    params.configId !== HOOMAN_TODO_CONFIG_ID &&
     params.configId !== HOOMAN_LTM_CONFIG_ID &&
     params.configId !== HOOMAN_WIKI_CONFIG_ID
   ) {
@@ -77,6 +92,18 @@ export function applySessionConfigOption(
     return;
   }
 
+  if (params.configId === HOOMAN_TODO_CONFIG_ID) {
+    config.update({
+      tools: {
+        ...config.tools,
+        todo: {
+          enabled: value === "on",
+        },
+      },
+    });
+    return;
+  }
+
   const chroma = config.wiki.chroma;
   config.update({
     tools: {

package/src/acp/utils/tool-kind.ts

@@ -22,6 +22,7 @@ const KNOWN_TOOL_KINDS = new Map<string, ToolKind>([
   ["wiki_stats", "read"],
   ["wiki_search", "search"],
   ["think", "think"],
+  ["update_todos", "other"],
   ["get_current_time", "other"],
   ["convert_time", "other"],
 ]);

package/src/chat/app.tsx

@@ -5,11 +5,15 @@ import React, {
   useRef,
   useState,
 } from "react";
+import fastq from "fastq";
 import { Box, useApp, useInput } from "ink";
 import {
   BeforeToolCallEvent,
+  Message,
+  TextBlock,
   type Agent,
   type AgentStreamEvent,
+  type ContentBlock,
 } from "@strands-agents/sdk";
 import type { Manager as McpManager } from "../core/mcp/index.ts";
 import type { Registry } from "../core/skills/index.ts";
@@ -19,9 +23,14 @@ import {
 } from "./approvals.ts";
 import { ApprovalPrompt } from "./components/ApprovalPrompt.tsx";
 import { Composer } from "./components/Composer.tsx";
+import { QueuedPrompts } from "./components/QueuedPrompts.tsx";
 import { StatusBar } from "./components/StatusBar.tsx";
+import { TodoPanel } from "./components/TodoPanel.tsx";
 import { Transcript } from "./components/Transcript.tsx";
 import type { ApprovalRequest, ChatLine } from "./types.ts";
+import { getTodoViewState, type TodoViewState } from "../core/tools/todo.ts";
+import { attachmentPathsToPromptBlocks } from "../core/utils/attachments.ts";
+import type { PromptSubmission } from "./components/prompt-input/usePromptInputController.ts";
 
 type ChatAppProps = {
   agent: Agent;
@@ -33,7 +42,27 @@ type ChatAppProps = {
   onExit: () => void;
 };
 
-const INPUT_HINT = "enter: send | esc/ctrl+c: cancel or exit";
+type QueuedPrompt = {
+  id: string;
+  prompt: PromptSubmission;
+};
+
+function normalizePromptSubmission(
+  value: string | PromptSubmission,
+): PromptSubmission {
+  if (typeof value === "string") {
+    return { text: value, attachments: [] };
+  }
+  return {
+    text: value.text,
+    attachments: [
+      ...new Set(value.attachments.map((item) => item.trim()).filter(Boolean)),
+    ],
+  };
+}
+
+const INPUT_HINT =
+  "enter: queue prompt | shift/meta+enter or \\+enter: newline | esc/ctrl+c: cancel or exit";
 
 function nowId(): string {
   return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -65,6 +94,23 @@ function toToolResultText(result: unknown): string {
   return body || `Tool finished with status: ${data.status ?? "unknown"}`;
 }
 
+function getToolUseId(value: unknown): string | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const data = value as {
+    toolUseId?: unknown;
+    toolUse?: { toolUseId?: unknown };
+  };
+  if (typeof data.toolUseId === "string") {
+    return data.toolUseId;
+  }
+  if (typeof data.toolUse?.toolUseId === "string") {
+    return data.toolUse.toolUseId;
+  }
+  return null;
+}
+
 export function ChatApp({
   agent,
   sessionId,
@@ -93,11 +139,17 @@ export function ChatApp({
   });
   const [pendingApproval, setPendingApproval] =
     useState<ApprovalRequest | null>(null);
+  const [queuedPrompts, setQueuedPrompts] = useState<QueuedPrompt[]>([]);
   const [liveReasoning, setLiveReasoning] = useState("");
+  const [todoState, setTodoState] = useState<TodoViewState>(() =>
+    getTodoViewState(agent),
+  );
   const controllerRef = useRef(new ChatApprovalController());
+  const mountedRef = useRef(true);
   const runningRef = useRef(false);
   const assistantLineIdRef = useRef<string | null>(null);
-  const toolLineIdRef = useRef<string | null>(null);
+  const toolLineIdsRef = useRef(new Map<string, string>());
+  const pendingToolLineIdsRef = useRef<string[]>([]);
   const initialRanRef = useRef(false);
 
   useEffect(() => {
@@ -148,6 +200,22 @@ export function ChatApp({
     };
   }, [agent, yolo]);
 
+  useEffect(() => {
+    let active = true;
+    const refresh = () => {
+      if (!active) {
+        return;
+      }
+      setTodoState(getTodoViewState(agent));
+    };
+    refresh();
+    const timer = setInterval(refresh, running ? 200 : 800);
+    return () => {
+      active = false;
+      clearInterval(timer);
+    };
+  }, [agent, running]);
+
   const appendLine = useCallback((line: ChatLine) => {
     setLines((prev) => [...prev, line]);
   }, []);
@@ -187,11 +255,14 @@ export function ChatApp({
   }, []);
 
   const runTurn = useCallback(
-    async (prompt: string) => {
-      const trimmed = prompt.trim();
-      if (!trimmed || runningRef.current) {
+    async (prompt: PromptSubmission) => {
+      const trimmed = prompt.text.trim();
+      if (!trimmed && prompt.attachments.length === 0) {
         return;
       }
+      const attachmentBlocks = await attachmentPathsToPromptBlocks(
+        prompt.attachments,
+      );
 
       runningRef.current = true;
       setRunning(true);
@@ -202,7 +273,12 @@ export function ChatApp({
       appendLine({
         id: nowId(),
         role: "user",
-        content: trimmed,
+        content:
+          prompt.attachments.length > 0
+            ? `${trimmed || "[attachments]"}\n\n${prompt.attachments
+                .map((attachmentPath) => `[attachment] ${attachmentPath}`)
+                .join("\n")}`
+            : trimmed,
         done: true,
       });
 
@@ -216,7 +292,19 @@ export function ChatApp({
       });
 
       try {
-        for await (const event of agent.stream(trimmed)) {
+        const streamInput =
+          attachmentBlocks.length > 0
+            ? [
+                new Message({
+                  role: "user",
+                  content: [
+                    ...(trimmed ? [new TextBlock(trimmed)] : []),
+                    ...attachmentBlocks,
+                  ] as ContentBlock[],
+                }),
+              ]
+            : trimmed;
+        for await (const event of agent.stream(streamInput)) {
           const e = event as AgentStreamEvent;
           switch (e.type) {
             case "contentBlockEvent": {
@@ -230,7 +318,12 @@ export function ChatApp({
                 appendAssistantText(block.text ?? "");
               } else if (block.type === "toolUseBlock") {
                 const toolId = nowId();
-                toolLineIdRef.current = toolId;
+                const toolUseId = getToolUseId(block);
+                if (toolUseId) {
+                  toolLineIdsRef.current.set(toolUseId, toolId);
+                } else {
+                  pendingToolLineIdsRef.current.push(toolId);
+                }
                 appendLine({
                   id: toolId,
                   role: "tool",
@@ -248,13 +341,31 @@ export function ChatApp({
             }
             case "toolResultEvent": {
               const resultContent = toToolResultText(e.result);
-              if (toolLineIdRef.current) {
-                updateLine(toolLineIdRef.current, {
+              const toolUseId = getToolUseId(e.result);
+              let toolLineId = toolUseId
+                ? toolLineIdsRef.current.get(toolUseId)
+                : undefined;
+              if (toolLineId && toolUseId) {
+                toolLineIdsRef.current.delete(toolUseId);
+              }
+              toolLineId ??= pendingToolLineIdsRef.current.shift();
+              if (!toolLineId) {
+                const firstTrackedTool = toolLineIdsRef.current
+                  .entries()
+                  .next();
+                if (!firstTrackedTool.done) {
+                  const [trackedToolUseId, trackedToolLineId] =
+                    firstTrackedTool.value;
+                  toolLineIdsRef.current.delete(trackedToolUseId);
+                  toolLineId = trackedToolLineId;
+                }
+              }
+              if (toolLineId) {
+                updateLine(toolLineId, {
                   phase: "done",
                   done: true,
                   resultContent,
                 });
-                toolLineIdRef.current = null;
               } else {
                 appendLine({
                   id: nowId(),
@@ -324,10 +435,14 @@ export function ChatApp({
       } finally {
         updateLine(assistantId, { done: true });
         assistantLineIdRef.current = null;
-        if (toolLineIdRef.current) {
-          updateLine(toolLineIdRef.current, { phase: "done", done: true });
-          toolLineIdRef.current = null;
+        for (const toolLineId of toolLineIdsRef.current.values()) {
+          updateLine(toolLineId, { phase: "done", done: true });
         }
+        for (const toolLineId of pendingToolLineIdsRef.current) {
+          updateLine(toolLineId, { phase: "done", done: true });
+        }
+        toolLineIdsRef.current.clear();
+        pendingToolLineIdsRef.current = [];
         runningRef.current = false;
         setRunning(false);
         setTurnStartedAt(null);
@@ -338,22 +453,81 @@ export function ChatApp({
     [agent, appendAssistantText, appendLine, moveLineToEnd, updateLine],
   );
 
+  const runTurnRef = useRef(runTurn);
+  useEffect(() => {
+    runTurnRef.current = runTurn;
+  }, [runTurn]);
+
+  const queueRef = useRef<fastq.queueAsPromised<QueuedPrompt, void> | null>(
+    null,
+  );
+  if (!queueRef.current) {
+    queueRef.current = fastq.promise(async (item: QueuedPrompt) => {
+      if (mountedRef.current) {
+        setQueuedPrompts((prev) =>
+          prev.filter((entry) => entry.id !== item.id),
+        );
+      }
+      await runTurnRef.current(item.prompt);
+    }, 1);
+  }
+
+  useEffect(() => {
+    return () => {
+      mountedRef.current = false;
+      queueRef.current?.kill();
+    };
+  }, []);
+
+  const pushPrompt = useCallback(
+    (value: string | PromptSubmission): boolean => {
+      const normalized = normalizePromptSubmission(value);
+      const trimmed = normalized.text.trim();
+      if (!trimmed && normalized.attachments.length === 0) {
+        return false;
+      }
+      const item: QueuedPrompt = {
+        id: nowId(),
+        prompt: { ...normalized, text: trimmed },
+      };
+      setQueuedPrompts((prev) => [...prev, item]);
+      void queueRef.current?.push(item).catch((error) => {
+        if (!mountedRef.current) {
+          return;
+        }
+        setQueuedPrompts((prev) =>
+          prev.filter((entry) => entry.id !== item.id),
+        );
+        appendLine({
+          id: nowId(),
+          role: "system",
+          title: "error",
+          content: error instanceof Error ? error.message : String(error),
+          done: true,
+        });
+      });
+      return true;
+    },
+    [appendLine],
+  );
+
   useEffect(() => {
     if (initialPrompt && !initialRanRef.current) {
       initialRanRef.current = true;
-      void runTurn(initialPrompt);
+      pushPrompt(initialPrompt);
     }
-  }, [initialPrompt, runTurn]);
+  }, [initialPrompt, pushPrompt]);
 
   const onSubmit = useCallback(
-    (value: string) => {
-      if (running || pendingApproval) {
+    (value: PromptSubmission) => {
+      if (pendingApproval) {
         return;
       }
-      setInput("");
-      void runTurn(value);
+      if (pushPrompt(value)) {
+        setInput("");
+      }
     },
-    [pendingApproval, runTurn, running],
+    [pendingApproval, pushPrompt],
   );
 
   useInput(
@@ -390,9 +564,22 @@ export function ChatApp({
     return `${String(min).padStart(2, "0")}:${String(sec).padStart(2, "0")}`;
   }, [turnElapsedMs]);
 
+  const activeTodo = useMemo(
+    () => todoState.todos.find((todo) => todo.status === "in_progress"),
+    [todoState.todos],
+  );
+  const statusLabel =
+    running && activeTodo
+      ? activeTodo.activeForm.trim() || activeTodo.content
+      : status;
+
   return (
     <Box flexDirection="column" width="100%" paddingX={1}>
       <Transcript lines={lines} liveReasoning={liveReasoning} />
+      {running && todoState.visible && todoState.todos.length > 0 ? (
+        <TodoPanel todos={todoState.todos} />
+      ) : null}
+      <QueuedPrompts prompts={queuedPrompts} />
 
       {pendingApproval ? (
         <ApprovalPrompt
@@ -404,7 +591,7 @@ export function ChatApp({
         <Composer
           input={input}
           running={running}
-          disabled={running || Boolean(pendingApproval)}
+          disabled={Boolean(pendingApproval)}
           hint={INPUT_HINT}
           onChange={setInput}
           onSubmit={onSubmit}
@@ -414,6 +601,7 @@ export function ChatApp({
       <StatusBar
         running={running}
         status={status}
+        statusLabel={statusLabel}
         sessionId={sessionId}
         elapsedLabel={elapsedLabel}
         turnCount={turnCount}

package/src/chat/components/Composer.tsx

@@ -1,5 +1,6 @@
 import { Box, Text } from "ink";
-import TextInput from "ink-text-input";
+import { PromptInput } from "./PromptInput.tsx";
+import type { PromptSubmission } from "./prompt-input/usePromptInputController.ts";
 
 type ComposerProps = {
   input: string;
@@ -7,7 +8,7 @@ type ComposerProps = {
   disabled: boolean;
   hint: string;
   onChange: (value: string) => void;
-  onSubmit: (value: string) => void;
+  onSubmit: (value: PromptSubmission) => void;
 };
 
 export function Composer({
@@ -22,12 +23,17 @@ export function Composer({
     <>
       <Box borderStyle="round" borderColor="gray" paddingX={1}>
         <Text color="gray">{"> "}</Text>
-        <TextInput
+        <PromptInput
           value={input}
           onChange={onChange}
           onSubmit={onSubmit}
-          placeholder={running ? "Wait for current turn..." : "Type a message"}
+          placeholder={
+            running
+              ? "Type a message (queued after current turn)"
+              : "Type a message"
+          }
           focus={!disabled}
+          maxVisibleLines={4}
         />
       </Box>
 

package/src/chat/components/PromptInput.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+import { Box, Text } from "ink";
+import { splitLineAtCursor } from "./prompt-input/render.ts";
+import {
+  usePromptInputController,
+  type PromptSubmission,
+} from "./prompt-input/usePromptInputController.ts";
+
+export type PromptInputProps = {
+  value: string;
+  onChange: (value: string) => void;
+  onSubmit: (value: PromptSubmission) => void;
+  placeholder?: string;
+  focus?: boolean;
+  maxVisibleLines?: number;
+};
+
+export function PromptInput({
+  value,
+  onChange,
+  onSubmit,
+  placeholder = "",
+  focus = true,
+  maxVisibleLines = 4,
+}: PromptInputProps): React.JSX.Element {
+  const { view } = usePromptInputController({
+    value,
+    onChange,
+    onSubmit,
+    focus,
+    maxVisibleLines,
+  });
+
+  if (view.showPlaceholder) {
+    return (
+      <Text>
+        {focus ? <Text inverse> </Text> : null}
+        {placeholder ? <Text color="gray">{placeholder}</Text> : null}
+      </Text>
+    );
+  }
+
+  return (
+    <Box flexDirection="column">
+      {view.visibleLines.map((line, index) => {
+        const isCursorLine = focus && index === view.cursorLineInView;
+        if (!isCursorLine) {
+          return <Text key={`${view.lineOffset + index}`}>{line}</Text>;
+        }
+        const safeColumn = Math.min(Math.max(0, view.cursorCol), line.length);
+        const parts = splitLineAtCursor(line, safeColumn);
+        return (
+          <Text key={`${view.lineOffset + index}`}>
+            {parts.left}
+            <Text inverse>{parts.at}</Text>
+            {parts.right}
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}