xcoder-jarvis-agent 0.0.0-stage → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neural Node Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,244 @@
-# Temporary Holding Version
+<!-- xcoder:version 7 | xcoder:task task-691585 | xcoder:updated 2026-11-05T05:50:24.571Z | xcoder:subtask code-st-b5251b -->
+# xcoder-jarvis-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+allowlist of read-only tools, remembers short notes across sessions, and
+assembles its system prompt at runtime from versioned policy plus skill packs.
+
+It is built on `xcoder-dna` and follows the same workspace conventions: ESM,
+TypeScript, npm workspaces, vitest.
+
+## Install and run
+
+```bash
+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 |
+|---|---|---|
+| `--skill NAME` | load only this skill pack (repeatable) | all discovered packs |
+| `--max-iterations N` | reasoning steps, clamped to 1..8 | 8 |
+| `--chat` | multi-turn mode: read turns from stdin until `exit`/`quit`/`bye` or EOF | off |
+| `--max-turns N` | chat turns, clamped to 1..200 | 50 |
+| `--no-memory` | skip loading and writing memory | memory on |
+| `--session ID` | session label | generated |
+| `--user ID` | memory scope label | OS user |
+| `--json` | emit one line of JSON | off |
+| `--help` | usage, exit 0 | |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | answered |
+| 1 | error (bad flags, no task, model failure) |
+| 2 | iteration limit reached |
+| 3 | budget exceeded (in chat: also `--max-turns` reached) |
+| 4 | aborted by the kill switch |
+
+Code 2 is always a per-turn outcome in chat mode: a turn that hits its
+iteration limit is reported and the conversation continues.
+
+## Chat mode
+
+```bash
+node packages/jarvis-agent/dist/program.js --chat
+```
+
+Each line you type is one turn. The session ends when you type `exit`, `quit`
+or `bye` on a line by itself (case-insensitive, surrounding spaces ignored) or
+send EOF (Ctrl-D / Ctrl-Z). A line that merely *contains* one of those words —
+`exit now`, `how do I quit a program?` — is an ordinary turn.
+
+- **Continuity comes from memory, not from a growing transcript.** Every turn
+  re-reads the same memory session and re-assembles the prompt from it, so the
+  agent can recall earlier turns up to the memory window limit (~20 entries).
+  A very long chat therefore forgets its distant past; use `--session` to name
+  a conversation you want to return to.
+- **Each turn is one ordinary run.** It gets its own budget, its own `runId` and
+  exactly one provenance record, and the shared `session` label ties the turns
+  together. A turn that fails is reported and the loop continues.
+- **Blank lines are inert** — no model call, no memory write, no provenance.
+- **Lines over 8 KiB are rejected before the model sees them**, and only the
+  byte count is echoed, never the text.
+- **Ctrl-C and the kill switch still work.** `XCODER_JARVIS_KILL=1` or a
+  `.xcoder/jarvis/STOP` file is re-checked at every turn boundary and exits 4.
+- **`--json` emits one JSON object per executed turn** on stdout, so the stream
+  stays machine-readable; the session banner goes to stderr only.
+- **`--chat` plus a positional task is an error**, not a seed: a silently
+  discarded task looks like a model bug.
+
+A tool that needs confirmation prompts on stdin through the same reader the
+loop uses, so a prompt can never swallow a turn. Typing a terminator at a
+confirmation prompt denies that tool and ends the session at the next turn
+boundary — quitting is never blocked by a pending approval.
+
+## How it is built
+
+```
+argv -> runJarvisAgent
+          |-- discoverSkills -> skill packs (data, not instructions)
+          |-- assembleSystemPrompt -> trusted policy + delimited data blocks
+          |-- runReactLoop
+          |     |-- createLlmClient (xcoder-dna)
+          |     |-- parseDecision (zod)
+          |     `-- ToolRegistry (allowlist enforced in code)
+          |-- MemoryStore (scoped JSONL, redacted at write)
+          `-- writeProvenance (.xcoder/jarvis/runs/[runId].jsonl)
+```
+
+The ReAct loop is owned in-package rather than reusing
+`GenesisReActOrchestrator`, because that orchestrator's tool registry is
+internal and cannot be constrained to Jarvis's allowlist — reusing it would
+mean shipping an agent whose tool surface we do not control.
+
+### Tools
+
+Only six tools exist, and the list is enforced in code:
+
+| Tool | Risk | Notes |
+|---|---|---|
+| `read_file` | read | workspace-confined, symlink-resolved, secret-path denylist, 256 KiB cap |
+| `glob` | read | `*`, `**`, `?`, `{a,b}` only; 200 results |
+| `grep` | read | regex, 200 chars max; 100 matches; binary skipped |
+| `search_workspace` | read | path substring search |
+| `remember` | write | through `MemoryStore`, redacted before write |
+| `recall` | read | current scope's window |
+
+Deliberately absent: shell/exec, file write or delete, network fetch, git
+push, and any SQL. There is no irreversible tool in this build, so nothing
+needs human approval to run. The confirmation seam exists anyway and fails
+closed (deny) when stdin is not a TTY, so adding an irreversible tool later
+cannot silently skip approval.
+
+## Security model
+
+Jarvis is designed against the OWASP LLM Top 10. The controls that matter:
+
+**Prompt injection (LLM01).** The instruction region is a versioned constant,
+`POLICY`, in `src/jarvis/prompt/policy.ts`. Its sha256 is recorded in every
+run's provenance. Skill packs, memory entries and tool observations are
+treated as untrusted data: they are normalised (zero-width and bidi controls
+stripped), placed in `<untrusted-skill>` / `<untrusted-memory>` /
+`<untrusted-observation>` blocks, and any literal closing delimiter inside
+them is entity-escaped so it cannot end its own block.
+
+**Policy is enforced in code, not prose (PRM-09).** A prompt instruction is
+not a security boundary. The tool allowlist lives in `ToolRegistry.get()`,
+which returns `undefined` for any name that is not both registered and
+allowed. Iteration, token and wall-clock caps live in `RunBudget`. Model
+output is validated by a zod discriminated union before it can reach any
+tool.
+
+**Insecure output handling (LLM02).** Parsed decisions are the only thing
+that leaves `parseDecision`; raw model text is never passed to a shell, SQL,
+eval, HTML or a file path. There is no `eval` or `Function` constructor in the
+package.
+
+**Sensitive information (LLM06).** `read_file` refuses a denylist of
+secret-bearing paths (dotenv files, PEM/key files, ssh identities, npmrc,
+credential files). Anything read is run through `redactSecrets` before it
+enters the transcript, and memory values are redacted before they are
+written to disk.
+
+**Excessive agency (LLM08).** At most 8 iterations, one request in flight, a
+read-mostly tool surface, and a kill switch.
+
+**Cost and DoS (LLM10).** `RunBudget` caps input/output tokens, iterations and
+wall-clock time. A run over any cap returns exit 3 with no partial answer.
+
+### Kill switch
+
+Either signal aborts the run, checked before every LLM call and every tool
+dispatch, and failing closed:
+
+```bash
+export XCODER_JARVIS_KILL=1          # environment
+touch .xcoder/jarvis/STOP           # file in the workspace
+```
+
+An aborted run writes no memory entry and still records provenance with
+outcome `aborted`.
+
+### What is logged
+
+`.xcoder/jarvis/runs/[runId].jsonl` — one record per run, mode 0600 where the
+platform supports it. The schema holds identifiers, hashes and counts only:
+no prompt text, no model replies, no file contents, no tokens. The one
+free-text field is `error`, which is redacted and capped at 500 characters.
+Records older than 90 days are pruned off the hot path. Set `JARVIS_DEBUG=1`
+to print a stack trace to stderr on an unexpected error (never to the run
+log).
+
+## Memory
+
+Memory is append-only JSONL at
+`.xcoder/jarvis/memory/[workspaceId]/[userId].jsonl`, scoped by a hash of the
+resolved workspace path and a sanitised user label. Compaction is
+deterministic and never calls a model: it keeps the newest entry per key,
+then fills remaining capacity newest-first. A torn final line is dropped on
+read rather than throwing, so a killed process cannot corrupt the store.
+
+> **Accepted risk — scope is a label, not authentication.** `--user` selects
+> which memory file to use; it does not authenticate anyone. Anyone who can
+> run the CLI can read their own memory file, and anyone with filesystem
+> access can read the others. Real isolation requires separate OS accounts,
+> which is out of scope for a local CLI. Owner: platform team.
+
+> **File modes are best-effort on Windows.** The store requests mode 0700/0600
+> but Windows ignores POSIX permission bits; the protections there come from
+the user profile directory's ACLs.
+
+## Skill packs
+
+Packs are `SKILL.md` files with YAML frontmatter (`name`, `role`,
+`description`, `triggers`, `version`, `requires_tools`, `composes_with`).
+Discovery searches, first match wins: `$XCODER_SKILLS_DIR`, then
+`.xcoder/skills` in the workspace, then `~/.xcoder/skills` (seeded from the
+shipped packs on first run), then the bundled `xcoder-dna` packs.
+
+The frontmatter parser is a line-based YAML subset — no generic YAML
+dependency and no code execution. A pack that fails to parse is skipped and
+recorded in provenance; it never aborts a run. Unknown frontmatter keys are
+dropped rather than reaching the prompt.
+
+Because user-level packs are writable by the user, treat pack text as
+untrusted: review a pack before enabling it, exactly as you would review a
+script you were about to run.
+
+## Development
+
+```bash
+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
+```
+
+Tests live in `packages/*/src/**/*.test.ts` — the workspace vitest config only
+discovers that pattern.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public barrel for `@xcoder/jarvis-agent`.
+ *
+ * The CLI is the primary consumer, but everything the agent does is
+ * importable so a test (or a future orchestrator) can drive the loop, the
+ * memory store and the prompt assembler directly without spawning a process.
+ */
+export { JARVIS_AGENT_NAME, EXIT, runJarvisAgent, type JarvisDeps, type JarvisResult, } from "./jarvis/agent.js";
+export { MAX_ITERATIONS, runReactLoop, type LlmCompleter, type ReactLoopInput, type ReactLoopOutput, } from "./jarvis/react-loop.js";
+export { ActionDecision, FinalDecision, MAX_ARGS, MAX_ANSWER, MAX_THOUGHT, ReactDecision, ReactParseError, TOOL_NAME_RE, extractJsonObject, isValidToolName, parseDecision, type ReactDecision as ReactDecisionValue, } from "./jarvis/decision.js";
+export { BudgetExceeded, DEFAULT_CAPS, RunBudget, clampIterations, type BudgetCaps, type BudgetSnapshot } from "./jarvis/budget.js";
+export { ArgvError, MAX_TURNS_CEILING, MAX_TURNS_DEFAULT, USAGE, parseArgv, type JarvisRunRequest, } from "./jarvis/argv.js";
+export { MAX_LINE_BYTES, createArrayLineSource, createStdinLineSource, type LineResult, type LineSource, } from "./jarvis/chat/lines.js";
+export { TERMINATORS, isIgnorable, isTerminator, type TerminatorWord } from "./jarvis/chat/terminator.js";
+export { createChatConfirm, type ChatConfirm } from "./jarvis/chat/confirm.js";
+export { CHAT_DIRECTIVE } from "./jarvis/chat/prompt.js";
+export { runChatSession, runChatSessionDetailed, turnArgv, type ChatResult, type StopReason, } from "./jarvis/chat/session.js";
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, DEFAULT_WINDOW_ENTRIES, MemoryStore, resolveUserId, workspaceScopeId, type MemoryEntry, type MemoryKind, type MemoryScope, type MemorySource, } from "./jarvis/memory/store.js";
+export { assembleSystemPrompt, wrapObservation, JARVIS_ROLE, UNTRUSTED_MEMORY_TAG, UNTRUSTED_OBSERVATION_TAG, UNTRUSTED_SKILL_TAG, type AssembledPrompt, type PromptProvenance, } from "./jarvis/prompt/assemble.js";
+export { POLICY_VERSION, POLICY, REFUSAL_RULES, renderPolicy } from "./jarvis/prompt/policy.js";
+export { DEFAULT_MAX_PACKS, DEFAULT_MAX_PACK_BYTES, DEFAULT_MAX_TOTAL_BYTES, discoverSkills, parseFrontmatter, type DiscoverSkillsOptions, type DiscoverSkillsResult, type SkillPack, type SkippedSkill, } from "./jarvis/prompt/skills.js";
+export { ALLOWED_TOOLS, DEFAULT_LIMITS, createToolRegistry, type AllowedToolName, type ToolContext, type ToolDescriptor, type ToolLimits, type ToolObservation, type ToolRegistry, } from "./jarvis/tools/registry.js";
+export { FS_TOOLS, globToRegExp, isSecretPath } from "./jarvis/tools/fs-tools.js";
+export { MEMORY_TOOLS } from "./jarvis/tools/memory-tools.js";
+export { RETENTION_DAYS, pruneProvenance, writeProvenance, type JarvisOutcome, type ProvenanceRecord, } from "./jarvis/telemetry/provenance.js";
+export { createConfirm, denyWhenNotTty, requireConfirmation, type ConfirmFn, type ConfirmRequest, type ToolRisk } from "./jarvis/util/confirm.js";
+export { createKillProbe, readKillState, stopFilePath, type KillState } from "./jarvis/util/kill.js";

package/dist/index.js

@@ -0,0 +1,28 @@
+// xcoder:version 2 | xcoder:task task-482677 | xcoder:updated 2026-11-05T03:49:01.166Z | xcoder:subtask code-st-729fd8
+/**
+ * Public barrel for `@xcoder/jarvis-agent`.
+ *
+ * The CLI is the primary consumer, but everything the agent does is
+ * importable so a test (or a future orchestrator) can drive the loop, the
+ * memory store and the prompt assembler directly without spawning a process.
+ */
+export { JARVIS_AGENT_NAME, EXIT, runJarvisAgent, } from "./jarvis/agent.js";
+export { MAX_ITERATIONS, runReactLoop, } from "./jarvis/react-loop.js";
+export { ActionDecision, FinalDecision, MAX_ARGS, MAX_ANSWER, MAX_THOUGHT, ReactDecision, ReactParseError, TOOL_NAME_RE, extractJsonObject, isValidToolName, parseDecision, } from "./jarvis/decision.js";
+export { BudgetExceeded, DEFAULT_CAPS, RunBudget, clampIterations } from "./jarvis/budget.js";
+export { ArgvError, MAX_TURNS_CEILING, MAX_TURNS_DEFAULT, USAGE, parseArgv, } from "./jarvis/argv.js";
+export { MAX_LINE_BYTES, createArrayLineSource, createStdinLineSource, } from "./jarvis/chat/lines.js";
+export { TERMINATORS, isIgnorable, isTerminator } from "./jarvis/chat/terminator.js";
+export { createChatConfirm } from "./jarvis/chat/confirm.js";
+export { CHAT_DIRECTIVE } from "./jarvis/chat/prompt.js";
+export { runChatSession, runChatSessionDetailed, turnArgv, } from "./jarvis/chat/session.js";
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, DEFAULT_WINDOW_ENTRIES, MemoryStore, resolveUserId, workspaceScopeId, } from "./jarvis/memory/store.js";
+export { assembleSystemPrompt, wrapObservation, JARVIS_ROLE, UNTRUSTED_MEMORY_TAG, UNTRUSTED_OBSERVATION_TAG, UNTRUSTED_SKILL_TAG, } from "./jarvis/prompt/assemble.js";
+export { POLICY_VERSION, POLICY, REFUSAL_RULES, renderPolicy } from "./jarvis/prompt/policy.js";
+export { DEFAULT_MAX_PACKS, DEFAULT_MAX_PACK_BYTES, DEFAULT_MAX_TOTAL_BYTES, discoverSkills, parseFrontmatter, } from "./jarvis/prompt/skills.js";
+export { ALLOWED_TOOLS, DEFAULT_LIMITS, createToolRegistry, } from "./jarvis/tools/registry.js";
+export { FS_TOOLS, globToRegExp, isSecretPath } from "./jarvis/tools/fs-tools.js";
+export { MEMORY_TOOLS } from "./jarvis/tools/memory-tools.js";
+export { RETENTION_DAYS, pruneProvenance, writeProvenance, } from "./jarvis/telemetry/provenance.js";
+export { createConfirm, denyWhenNotTty, requireConfirmation } from "./jarvis/util/confirm.js";
+export { createKillProbe, readKillState, stopFilePath } from "./jarvis/util/kill.js";

package/dist/jarvis/agent.d.ts

@@ -0,0 +1,50 @@
+import type { LineSource } from "./chat/lines.js";
+import { type LlmCompleter } from "./react-loop.js";
+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";
+export { EXIT, type ExitCode } from "./exit.js";
+export interface JarvisDeps {
+    createClient?: () => LlmCompleter;
+    now?: () => Date;
+    workspaceRoot?: string;
+    memoryRoot?: string;
+    runLogRoot?: string;
+    tools?: readonly ToolDescriptor<any>[];
+    confirm?: ConfirmFn;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    /** Injected for tests, so skill discovery never reads the real home dir. */
+    env?: NodeJS.ProcessEnv;
+    /** Chat seam: replaces process.stdin. Production builds a LineSource from it. */
+    stdin?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    /** Chat seam: an explicit LineSource, so loop tests need no process or TTY. */
+    lines?: LineSource;
+    /** Chat seam: overrides TTY detection for the confirmation gate. */
+    isInteractive?: boolean;
+    /** Set by the chat loop: record this turn's user line before the run (T4). */
+    chatTurn?: boolean;
+}
+export interface JarvisResult {
+    outcome: JarvisOutcome;
+    answer?: string;
+    exitCode: number;
+    iterations: number;
+    runId: string;
+    session: string;
+    skills: string[];
+    provenancePath?: string;
+    error?: string;
+}
+/**
+ * Runs one Jarvis invocation and returns a process exit code.
+ *
+ * Never throws for expected conditions: a bad flag, a missing key, a model
+ * failure, a tripped kill switch and an exhausted budget all become a number
+ * plus a redacted message (T7). Provenance is written in a `finally` so an
+ * aborted run still leaves an audit record.
+ */
+export declare function runJarvisAgent(argv: readonly string[], deps?: JarvisDeps): Promise<number>;