xcoder-jarvis-agent 1.3.0 → 1.4.0

package/README.md

@@ -1,5 +1,5 @@
-<!-- xcoder:version 3 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:54:36.038Z | xcoder:subtask code-st-729fd8 -->
-# @xcoder/jarvis-agent
+<!-- xcoder:version 7 | xcoder:task task-691585 | xcoder:updated 2026-11-05T05:50:24.571Z | xcoder:subtask code-st-b5251b -->
+# xcoder-jarvis-agent
 
 Jarvis is a ReAct agent that runs as a local CLI inside a developer's
 workspace. It reasons in a bounded loop, reads the workspace through a small
@@ -12,12 +12,31 @@ TypeScript, npm workspaces, vitest.
 ## Install and run
 
 ```bash
-npm run build -w @xcoder/jarvis-agent
+npm run build -w xcoder-jarvis-agent
 node packages/jarvis-agent/dist/program.js "summarise how the llm client picks a transport"
 ```
 
 Once published, the binaries are `jarvis`.
 
+### Reaching jarvis through `xcoder`
+
+`xcoder` forwards a `jarvis` command to this binary, so you do not have to
+leave it or remember a dist path:
+
+```bash
+xcoder jarvis --chat
+```
+
+Every argument is handed over verbatim, stdio is inherited (a chat session
+keeps your terminal), and the exit code is jarvis's own — `xcoder` adds only
+`127` when the binary cannot be found and `130` when the run was interrupted.
+No jarvis flag is re-documented there: run `xcoder jarvis --help` for the
+authoritative list. `jarvis` is one of only three delegable targets, alongside
+`litebro` and `bugfinder`; anything else is refused. Jarvis keeps its own
+environment variables, kill switch and run budget — delegation adds none.
+See [DELEGATION.md](https://github.com/org/xcoder-sdlc/blob/main/docs/DELEGATION.md)
+and [LICENSE](./LICENSE).
+
 ### Flags
 
 | Flag | Meaning | Default |
@@ -215,7 +234,7 @@ script you were about to run.
 ## Development
 
 ```bash
-npm run typecheck -w @xcoder/jarvis-agent
+npm run typecheck -w xcoder-jarvis-agent
 npm test                                  # full workspace suite
 npx vitest run packages/jarvis-agent      # just this package
 npm run check:boundaries                  # dependency rules

package/dist/jarvis/agent.d.ts

@@ -4,14 +4,7 @@ import { type JarvisOutcome } from "./telemetry/provenance.js";
 import { type ConfirmFn } from "./util/confirm.js";
 import { type ToolDescriptor } from "./tools/registry.js";
 export declare const JARVIS_AGENT_NAME: "jarvis-agent";
-/** Exit codes are the CLI contract (design §2.3, tradeoff T7). */
-export declare const EXIT: {
-    readonly answered: 0;
-    readonly error: 1;
-    readonly iteration_limit: 2;
-    readonly budget_exceeded: 3;
-    readonly aborted: 4;
-};
+export { EXIT, type ExitCode } from "./exit.js";
 export interface JarvisDeps {
     createClient?: () => LlmCompleter;
     now?: () => Date;

package/dist/jarvis/agent.js

@@ -1,4 +1,4 @@
-// xcoder:version 13 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:48:53.483Z | xcoder:subtask code-st-729fd8
+// xcoder:version 16 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:51:32.763Z | xcoder:subtask code-st-729fd8
 import fsp from "node:fs/promises";
 import path from "node:path";
 import { createLlmClient, requestScope, shortId, XCODER_VERSION } from "xcoder-dna";
@@ -6,6 +6,7 @@ import { ArgvError, parseArgv, USAGE } from "./argv.js";
 import { BudgetExceeded, clampIterations, DEFAULT_CAPS, RunBudget } from "./budget.js";
 import { CHAT_DIRECTIVE } from "./chat/prompt.js";
 import { runChatSession } from "./chat/session.js";
+import { EXIT } from "./exit.js";
 import { MemoryStore, resolveUserId, workspaceScopeId } from "./memory/store.js";
 import { assembleSystemPrompt } from "./prompt/assemble.js";
 import { POLICY_VERSION, renderPolicy } from "./prompt/policy.js";
@@ -19,14 +20,9 @@ import { DEFAULT_LIMITS, createToolRegistry } from "./tools/registry.js";
 import { FS_TOOLS } from "./tools/fs-tools.js";
 import { MEMORY_TOOLS } from "./tools/memory-tools.js";
 export const JARVIS_AGENT_NAME = "jarvis-agent";
-/** Exit codes are the CLI contract (design §2.3, tradeoff T7). */
-export const EXIT = {
-    answered: 0,
-    error: 1,
-    iteration_limit: 2,
-    budget_exceeded: 3,
-    aborted: 4,
-};
+// Re-exported so `EXIT` keeps its documented public path (design §2.3, T7),
+// even though the table itself now lives in a leaf module.
+export { EXIT } from "./exit.js";
 function emit(stream, text) {
     try {
         stream.write(text);
@@ -70,8 +66,11 @@ export async function runJarvisAgent(argv, deps = {}) {
         return EXIT.answered;
     }
     // Chat runs many turns over one stdin/stdout pair; it owns its own loop.
+    // `runJarvisAgent` is injected rather than imported by the loop, so the two
+    // modules stay a DAG instead of a cycle (the loop calls back into this
+    // function once per turn, inheriting the same validation gate).
     if (request.chat) {
-        return await runChatSession(request, deps);
+        return await runChatSession(request, runJarvisAgent, deps);
     }
     if (request.task.length === 0) {
         emit(stderr, `jarvis: no task given\n\n${USAGE}\n`);

package/dist/jarvis/chat/session.d.ts

@@ -1,4 +1,4 @@
-import { type JarvisDeps } from "../agent.js";
+import type { JarvisDeps } from "../agent.js";
 import type { JarvisRunRequest } from "../argv.js";
 import { CHAT_DIRECTIVE } from "./prompt.js";
 /**
@@ -21,6 +21,14 @@ import { CHAT_DIRECTIVE } from "./prompt.js";
  *    session (K6/AC16/AC17).
  */
 export type StopReason = "terminator" | "eof" | "max_turns" | "killed";
+/**
+ * Executes one single-shot run and returns its exit code.
+ *
+ * Injected rather than imported: `agent.ts` imports this module, so importing
+ * `agent.ts` back would make the two a runtime cycle. Inverting the dependency
+ * keeps the graph a DAG and makes the loop trivially fakeable in a test.
+ */
+export type AgentRunner = (argv: readonly string[], deps: JarvisDeps) => Promise<number>;
 export interface ChatResult {
     exitCode: number;
     stopReason: StopReason;
@@ -32,7 +40,7 @@ export interface ChatResult {
  * gate instead of a second, divergent parser.
  */
 export declare function turnArgv(request: JarvisRunRequest, session: string, text: string): string[];
-export declare function runChatSession(request: JarvisRunRequest, deps?: JarvisDeps): Promise<number>;
-export declare function runChatSessionDetailed(request: JarvisRunRequest, deps?: JarvisDeps): Promise<ChatResult>;
+export declare function runChatSession(request: JarvisRunRequest, runAgent: AgentRunner, deps?: JarvisDeps): Promise<number>;
+export declare function runChatSessionDetailed(request: JarvisRunRequest, runAgent: AgentRunner, deps?: JarvisDeps): Promise<ChatResult>;
 /** Re-exported so a prompt test can pin the constant directive (AC15). */
 export { CHAT_DIRECTIVE };

package/dist/jarvis/chat/session.js

@@ -1,5 +1,4 @@
-// xcoder:version 2 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:48:55.859Z | xcoder:subtask code-st-729fd8
-import { EXIT, runJarvisAgent } from "../agent.js";
+import { EXIT } from "../exit.js";
 import { readKillState } from "../util/kill.js";
 import { createChatConfirm } from "./confirm.js";
 import { createStdinLineSource } from "./lines.js";
@@ -27,18 +26,18 @@ export function turnArgv(request, session, text) {
     argv.push("--", text);
     return argv;
 }
-export async function runChatSession(request, deps = {}) {
+export async function runChatSession(request, runAgent, deps = {}) {
     const stderr = deps.stderr ?? process.stderr;
     const workspaceRoot = deps.workspaceRoot ?? process.cwd();
-    const result = await driveChat(request, deps, workspaceRoot, stderr);
+    const result = await driveChat(request, runAgent, deps, workspaceRoot, stderr);
     return result.exitCode;
 }
-export async function runChatSessionDetailed(request, deps = {}) {
+export async function runChatSessionDetailed(request, runAgent, deps = {}) {
     const stderr = deps.stderr ?? process.stderr;
     const workspaceRoot = deps.workspaceRoot ?? process.cwd();
-    return await driveChat(request, deps, workspaceRoot, stderr);
+    return await driveChat(request, runAgent, deps, workspaceRoot, stderr);
 }
-async function driveChat(request, deps, workspaceRoot, stderr) {
+async function driveChat(request, runAgent, deps, workspaceRoot, stderr) {
     // A stable session label is what makes the turns one conversation.
     const session = request.session ?? `jarvis-chat-${Date.now().toString(36)}`;
     const lines = deps.lines ?? createStdinLineSource({ stdin: deps.stdin });
@@ -90,7 +89,7 @@ async function driveChat(request, deps, workspaceRoot, stderr) {
             if (isTerminator(next.text)) {
                 return { exitCode: EXIT.answered, stopReason: "terminator", turns };
             }
-            const code = await runJarvisAgent(turnArgv(request, session, next.text), turnDeps);
+            const code = await runAgent(turnArgv(request, session, next.text), turnDeps);
             turns += 1;
             if (code === EXIT.aborted) {
                 return { exitCode: EXIT.aborted, stopReason: "killed", turns };

package/dist/jarvis/exit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The CLI exit-code contract (design 2.3, tradeoff T7).
+ *
+ * These live in their own leaf module so the chat loop can name a code without
+ * importing `agent.ts`, which itself imports the chat loop. That keeps the
+ * module graph a DAG: a cycle would work under ESM only by accident of
+ * evaluation order and would break the first time a value were read at module
+ * scope.
+ */
+export declare const EXIT: {
+    readonly answered: 0;
+    readonly error: 1;
+    readonly iteration_limit: 2;
+    readonly budget_exceeded: 3;
+    readonly aborted: 4;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];

package/dist/jarvis/exit.js

@@ -0,0 +1,17 @@
+// xcoder:version 1 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:51:06.005Z | xcoder:subtask code-st-729fd8
+/**
+ * The CLI exit-code contract (design 2.3, tradeoff T7).
+ *
+ * These live in their own leaf module so the chat loop can name a code without
+ * importing `agent.ts`, which itself imports the chat loop. That keeps the
+ * module graph a DAG: a cycle would work under ESM only by accident of
+ * evaluation order and would break the first time a value were read at module
+ * scope.
+ */
+export const EXIT = {
+    answered: 0,
+    error: 1,
+    iteration_limit: 2,
+    budget_exceeded: 3,
+    aborted: 4,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xcoder-jarvis-agent",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Jarvis — a ReAct agent with scoped memory, skill-pack prompt assembly and a code-enforced tool allowlist, built on xcoder-dna.",
   "license": "MIT",
   "author": "Neural Node Labs",
@@ -32,7 +32,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "xcoder-dna": "^1.3.0",
+    "xcoder-dna": "^1.4.0",
     "zod": "^4.4.3"
   }
 }