newmark-agent 0.3.12 → 0.4.0

package/dist/tools/index.js

@@ -349,9 +349,9 @@ class ToolExecutor {
             t('subagent_result', 'Return the persisted transcript, mailbox summary, status, and latest result for a peer agent. Target by exact id (preferred) or name.', { id: { type: 'string', description: 'Exact peer id from subagent_list.' }, name: { type: 'string', description: 'Convenience peer name.' } }, []),
             t('subagent_close', 'Close a same-conversation peer. Root can close any peer; a peer can close only itself. Target by exact id (preferred) or name.', { id: { type: 'string', description: 'Exact peer id from subagent_list.' }, name: { type: 'string', description: 'Convenience peer name.' } }, []),
             t('linked_plan', 'Read or update the current conversation linked Markdown plan. Update requires the current expected_revision.', { action: { type: 'string', enum: ['get', 'update'] }, markdown: { type: 'string' }, expected_revision: { type: 'number' } }, ['action']),
-            t('build_history_query', 'Read the concrete public work details of one historical Build Block. The prompt already exposes user input, final summary, and completion status; call this read-only tool only when the user asks what specifically happened. Select by newest-to-oldest history_index, or by run_id returned from an earlier query.', { history_index: { type: 'number', minimum: 1, description: '1-based historical Build Block index from the request ledger; 1 is the newest previous task.' }, run_id: { type: 'string', description: 'Exact run id returned by an earlier build_history_query result.' }, max_events: { type: 'number', minimum: 1, maximum: 200, description: 'Maximum trailing public work events; defaults to 80.' } }, []),
+            t('build_history_query', 'Read the concrete public work details of one historical Build Block. The prompt already exposes user input, final summary, and completion status; call this read-only tool only when the user asks what specifically happened. Select by newest-to-oldest history_index, or by run_id returned from an earlier query. Every activity/guide content is bounded to max_chars (default 2000) to keep the read lean and cache-friendly.', { history_index: { type: 'number', minimum: 1, description: '1-based historical Build Block index from the request ledger; 1 is the newest previous task.' }, run_id: { type: 'string', description: 'Exact run id returned by an earlier build_history_query result.' }, max_events: { type: 'number', minimum: 1, maximum: 200, description: 'Maximum trailing public work events; defaults to 80.' }, max_chars: { type: 'number', minimum: 100, maximum: 4000, description: 'Per-event/per-guide content character bound; defaults to 2000.' } }, []),
             t('context_compress', 'Actively compress the LLM context history for this conversation. This collapses older history entries into a concise summary while preserving the recent tail, which reduces context tokens and cost. IMPORTANT: it affects only the LLM context (what the model sees); the displayed conversation history shown to the user is never altered. Call this when the conversation is long, token pressure is high, or you judge that older turns are no longer needed in full. Idempotent and safe: repeated calls produce incremental summaries.', { keep_recent: { type: 'number', minimum: 2, maximum: 60, description: 'Recent message count to keep uncompressed at the tail. Defaults to the configured keep_recent_messages.' }, force: { type: 'boolean', description: 'Compress even if the context is not yet over the automatic threshold. Defaults to false.' } }, []),
-            t('context_history_manage', 'Manage the LLM context history for this conversation without affecting the displayed conversation history. This is the active context-management surface. The hot cache stays bounded; evicted folded segments remain in a conversation-isolated append-only cold archive and are loaded only by explicit search/read/restore calls. Actions: list returns a bounded index of current context entries; remove deletes one current entry; summarize folds a contiguous current range; restore reinserts a folded segment when its summary marker is still present; search finds matching hot or archived segments; read returns one bounded segment without injecting the whole archive; status reports budgets, hot cache, cold archive, and the protected recent zone. The recent context tail and last user message are protected from remove/summarize unless dangerous is true.', {
+            t('context_history_manage', 'Manage the LLM context history for this conversation without affecting the displayed conversation history. This is the active context-management surface. The hot cache stays bounded; evicted folded segments remain in a conversation-isolated append-only cold archive and are loaded only by explicit search/read/restore calls. Actions: list returns a bounded index of current context entries; remove declares one long-term entry for unload (see below); summarize folds a contiguous current range; restore reinserts a folded segment when its summary marker is still present; search finds matching hot or archived segments; read returns one bounded segment without injecting the whole archive; status reports budgets, hot cache, cold archive, the protected recent zone, and pending removals. The recent context tail and last user message are protected from remove/summarize unless dangerous is true. For cache-optimization, remove ONLY targets long-term history (never the protected recent tail or last user message) and does NOT unload immediately: the declared entry stays in context for the rest of the current Build Block so the provider prefix cache stays stable, then is physically removed when the Block ends — applying to subsequent Blocks only.', {
                 action: { type: 'string', enum: ['list', 'remove', 'summarize', 'restore', 'search', 'read', 'status'], description: 'list current entries; remove one; summarize a range; restore by restore_id; search hot/cold folded segments; read one bounded folded segment; status report context budgets and storage.' },
                 position: { type: 'number', minimum: 0, description: '0-based context entry index for remove, or the start of the range for summarize.' },
                 to: { type: 'number', minimum: 0, description: '0-based inclusive end of the range for summarize. Defaults to position.' },
@@ -363,6 +363,15 @@ class ToolExecutor {
                 max_chars: { type: 'number', minimum: 1000, maximum: 60000, description: 'Maximum message-content characters returned by read (default 12000).' },
                 dangerous: { type: 'boolean', description: 'Set true to override the protected recent-message zone and allow removing/summarizing entries that include the recent context tail or the last user message.' },
             }, ['action']),
+            t('branch_list', 'List all branches in this conversation and their mailbox/activity status. Only available when the conversation was created with "允许分支交流" (allow branch communication) enabled. Returns each branch id, active flag, source message index, message/history/workRun counts, and unread mailbox counts so you can decide who to message or read next.', {}, []),
+            t('branch_send', 'Send a message to another branch in this conversation. Only available when branch communication is enabled. The message is persisted to the target branch mailbox and becomes visible to that branch on its next branch_read. Use this to coordinate work across concurrently running branches. A branch cannot message itself.', { to_branch: { type: 'string', description: 'Target branch id (from branch_list).' }, message: { type: 'string', description: 'Message body to deliver.' }, kind: { type: 'string', enum: ['message', 'directive', 'result'], description: 'Message kind; defaults to message.' }, correlation_id: { type: 'string', description: 'Optional correlation id for reply tracking.' }, reply_to: { type: 'string', description: 'Optional message id this message replies to.' } }, ['to_branch', 'message']),
+            t('branch_read', 'Read inbound messages and recent activity from another branch in this conversation. Only available when branch communication is enabled. Marks inbound messages read. Returns the branch metadata, inbound messages, and recent Build Block activity (final results and recent events).', { branch: { type: 'string', description: 'Branch id to read (from branch_list).' }, max_chars: { type: 'number', minimum: 100, maximum: 16000, description: 'Maximum characters for final-result text; defaults to 8000.' } }, ['branch']),
+            t('branch_create', 'Create a new conversation branch at a historical block position (a user message index) with a new initial instruction. Only available when branch communication is enabled. The new branch becomes an additional running branch. Use this to spin off alternative work from a past point without disturbing existing branches.', { message_index: { type: 'number', minimum: 0, description: '0-based index of a user message in the conversation history (the historical block position to branch from).' }, prompt: { type: 'string', description: 'The new branch initial instruction (becomes the branch user message).' }, message_id: { type: 'string', description: 'Optional exact message id to anchor the branch target.' }, guide_id: { type: 'string', description: 'Optional guide id to anchor the branch target.' } }, ['message_index', 'prompt']),
+            t('compress_tool_result', 'Compress ONE oversized tool result into a concise, format-preserving summary using the model, instead of hard truncation. Pass the artifact_id returned inline by an oversized tool result (the full raw content stays out of context, on disk). Use this when a read/grep/bash result reported an oversized_tool_result marker and you want to recover its structure (JSON arrays, table rows, code blocks, identifiers, error strings) as a compact summary. This runs an isolated compression call whose system prefix does not touch the conversation prompt cache, so it does not disturb cache hit rate.', { artifact_id: { type: 'string', description: 'The artifact_id from the oversized_tool_result marker returned inline by an oversized tool result.' }, content: { type: 'string', description: 'Optional fallback: a SHORT raw result text to compress directly when no artifact_id exists.' }, format_hint: { type: 'string', description: 'Optional description of the structure to preserve verbatim (e.g. "keep JSON arrays and file paths", "keep table columns and error strings").' } }, []),
+            t('background_tool', 'Run a tool call in the background WITHOUT blocking the conversation turn. Pass the target tool name and its arguments; this tool returns a background_id IMMEDIATELY, and the real tool keeps running in the background. The result is persisted and can be retrieved later with read_tool_result. Use this for long-running or non-critical tools (bash, web_fetch, long read/grep) so the conversation continues without waiting. The background result stays OUT of context until you explicitly read it, preserving prompt-cache hit rate. Orchestration/flow/subagent/question tools cannot be backgrounded.', { tool: { type: 'string', description: 'The tool name to run in the background (e.g. bash, web_fetch, read, grep).' }, args: { type: 'object', description: 'The arguments object for the target tool, matching its normal schema.' } }, ['tool']),
+            t('read_tool_result', 'Read the result of a background tool. Pass the background_id returned by background_tool. When status is running, returns a running marker; when done, returns the persisted result (optionally release it from storage after reading); when error, returns the failure. Background results are released from storage only when you set release=true.', { background_id: { type: 'string', description: 'The background_id returned by background_tool.' }, release: { type: 'boolean', description: 'Set true to release the persisted result from storage after reading it.' } }, ['background_id']),
+            t('goal_manage', 'Actively manage the persistent Goal state for this conversation. You may enter Goal mode, update (edit) its objective, mark it complete, or exit Goal mode yourself. Call this when the user asks you to pursue a persistent objective, when the objective changes, when you have verified the objective is genuinely achieved, or when you judge the Goal is no longer needed and should be cleared. This is the agent-side state control that mirrors the GUI goal panel controls. enter/update require objective; complete marks the objective verified and exits Goal mode; exit clears the Goal (and returns to Build mode) without claiming completion.', { action: { type: 'string', enum: ['enter', 'update', 'complete', 'exit'], description: 'enter=enter Goal mode and set the objective; update=edit the objective (records a change); complete=mark the objective verified-achieved and exit Goal mode; exit=clear the Goal and return to Build mode without claiming completion.' }, objective: { type: 'string', description: 'The Goal objective text. Required for enter and update.' }, reason: { type: 'string', description: 'Optional one-line reason for the state change, recorded for audit.' } }, ['action']),
+            t('conversation_rename', 'Rename the CURRENT conversation to a concise, descriptive title you choose. On the FIRST Build Block of a NEW conversation the runtime asks you to call this once so the conversation list shows a meaningful name instead of an auto-generated one. Keep the title short (a few words) and cache-friendly: a concrete noun phrase describing the task, never a sentence or quoted prompt.', { title: { type: 'string', description: 'The new conversation title (a short noun phrase, e.g. "Fix TUI color leak", "Add goal_manage tool").' } }, ['title']),
             t('question', 'Ask user a multiple-choice question', { questions: { type: 'array' } }, ['questions']),
             t('skill_download', 'Download a skill', { name: { type: 'string' }, source: { type: 'string' } }, ['name', 'source']),
             t('skill', 'Search enabled skill metadata or load one exact skill body on demand. Use query when unsure, then name to load the selected skill.', { query: { type: 'string', maxLength: 200 }, name: { type: 'string', maxLength: 200 } }, []),

package/dist/tools/nativeTools.js

@@ -38,10 +38,14 @@ exports.NATIVE_TOOL_CATALOG = [
     { name: 'subagent_send', label: 'Subagent send', description: 'Persist a message to a peer mailbox.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
     { name: 'subagent_result', label: 'Subagent result', description: 'Read peer transcript and result.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
     { name: 'subagent_close', label: 'Subagent close', description: 'Close a same-conversation peer agent.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
+    { name: 'branch_list', label: 'Branch list', description: 'List all conversation branches and their mailbox/activity status. Only available when branch communication is enabled.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
+    { name: 'branch_send', label: 'Branch send', description: 'Send a message to another conversation branch. Only available when branch communication is enabled.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
+    { name: 'branch_read', label: 'Branch read', description: 'Read inbound messages and recent activity from another conversation branch. Only available when branch communication is enabled.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
+    { name: 'branch_create', label: 'Branch create', description: 'Create a new conversation branch at a historical block position. Only available when branch communication is enabled.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
     { name: 'linked_plan', label: 'Linked plan', description: 'Read or conservatively update the conversation-linked Markdown plan.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
     { name: 'build_history_query', label: 'Build history query', description: 'Read concrete public work details for one historical Build Block.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
     { name: 'context_compress', label: 'Context compress', description: 'Actively compress the LLM context history, leaving the displayed conversation history unchanged.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
-    { name: 'context_history_manage', label: 'Context history manage', description: 'Inspect, search, restore, or fold LLM context history without touching the displayed conversation history.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
+    { name: 'context_history_manage', label: 'Context history manage', description: 'Inspect, search, restore, fold, or unload LLM context history without touching the displayed conversation history. Unload (remove) targets long-term entries only and takes effect after the current Build Block, for subsequent Blocks only.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
     { name: 'question', label: 'Ask question', description: 'Ask the user for structured option feedback.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },
     { name: 'skill_download', label: 'Skill download', description: 'Download and install a skill.', category: 'agent', defaultEnabled: true },
     { name: 'skill', label: 'Skill', description: 'Search enabled skill metadata or load one skill body on demand.', category: 'agent', defaultEnabled: true, protected: true, availability: 'mode-scoped' },