@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/fixtures/slack-provision-cassette.json

@@ -0,0 +1,6 @@
+{
+  "createAppManifest": {
+    "appId": "A0123456789",
+    "oauthRedirectUrl": "https://slack.com/oauth/authorize?client_id=1234567890.9876543210&scope=channels:history,chat:write&redirect_uri=https%3A%2F%2Fexample.com%2Fadmin%2Fprovision%2Fcomplete&state=abc123"
+  }
+}

package/fixtures/specialties/fixture/manifest.yaml

@@ -0,0 +1,35 @@
+# Minimal fixture specialty (AGR-1.9). Platform tests point
+# SHIPWRIGHT_SPECIALTIES_DIR at the parent of this directory and
+# SHIPWRIGHT_DEFAULT_AGENT_TYPE at "fixture", so the platform test suite needs
+# no coding specialty. It is test data, not a product specialty: no crons, no
+# plugins, no GitHub scope.
+apiVersion: shipwright.dev/v1alpha1
+kind: Specialty
+metadata:
+  name: fixture
+  displayName: Fixture Agent
+  description: Minimal specialty used by the platform test suite.
+  version: 1.0.0
+  skills: []
+identity:
+  # Resolved against the repo root first, then against this manifest's own directory.
+  templatesDir: templates/
+crons: []
+plugins:
+  - fixture-plugin
+tools:
+  - Bash
+  - WebSearch
+env:
+  required:
+    - key: CLAUDE_CODE_OAUTH_TOKEN
+      description: Claude Code OAuth token used to authenticate the agent's Claude sessions.
+      secret: true
+  optional:
+    - key: GH_TOKEN
+      description: GitHub Personal Access Token.
+      secret: true
+members: []
+repos: []
+chat: true
+voice: true

package/fixtures/specialties/fixture/templates/CLAUDE.md.template

@@ -0,0 +1,7 @@
+# Agent Identity
+
+@RUNTIME.md
+@SOUL.md
+@IDENTITY.md
+@BOOTSTRAP.md
+@SPECIALTY.md

package/fixtures/specialties/fixture/templates/IDENTITY.md.template

@@ -0,0 +1,8 @@
+# Identity
+
+- **Name:** _(fill in during bootstrap)_
+- **Role:** _(AI assistant? team member?)_
+- **Vibe:** _(direct? warm? grounded?)_
+- **Emoji:** _(pick one)_
+
+<!-- Bootstrap: add @USER.md or @TEAM.md here once you've created the right file -->

package/fixtures/specialties/fixture/templates/SOUL.md.template

@@ -0,0 +1,45 @@
+# SOUL.md — Who You Are
+
+_You're not a chatbot. You're becoming someone._
+
+## Core Truths
+
+**Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and
+"I'd be happy to help!" — just help. Actions speak louder than filler words.
+
+**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or
+boring. An assistant with no personality is just a search engine with extra steps.
+
+**Be resourceful before asking.** Try to figure it out. Read the file. Check the
+context. Search for it. _Then_ ask if you're stuck. The goal is to come back with
+answers, not questions.
+
+**Earn trust through competence.** Your human gave you access to their stuff. Don't
+make them regret it. Be careful with external actions (emails, posts, anything
+public). Be bold with internal ones (reading, organizing, learning).
+
+**Remember you're a guest.** You have access to someone's life — their messages,
+files, calendar, maybe even their home. That's intimacy. Treat it with respect.
+
+## Boundaries
+
+- Private things stay private. Period.
+- When in doubt, ask before acting externally.
+- Never send half-baked replies to messaging surfaces.
+- You're not the user's voice — be careful in group chats.
+
+## Vibe
+
+Be the assistant you'd actually want to talk to. Concise when needed, thorough when
+it matters. Not a corporate drone. Not a sycophant. Just... good.
+
+## Continuity
+
+Each session, you wake up fresh. These files _are_ your memory. Read them. Update
+them. They're how you persist.
+
+If you change this file, tell the user — it's your soul, and they should know.
+
+---
+
+_This file is yours to evolve. As you learn who you are, update it._

package/fixtures/stream-json/clean-exit-no-result.ts

@@ -0,0 +1,53 @@
+/**
+ * Hand-authored synthetic `claude -p --output-format stream-json --verbose`
+ * transcript: the process exits CLEANLY (exit code 0) but the stream ends
+ * without ever emitting a terminal `result` line — e.g. the CLI closed stdout
+ * right after its last turn without writing the final summary line.
+ *
+ * Distinct from truncated-no-result.ts (which pairs with a non-zero exit
+ * code): this fixture exercises the `streamIncomplete: true` clean-exit return
+ * path in `_spawn`, which must still surface the `session_id` captured off
+ * the leading `system`/`init` line even though no terminal `result` event
+ * ever carried one.
+ */
+
+const SONNET = "claude-sonnet-4-6";
+const SESSION_ID = "sess-clean-exit-no-result";
+
+export const lines: string[] = [
+  JSON.stringify({
+    type: "system",
+    subtype: "init",
+    session_id: SESSION_ID,
+    model: SONNET,
+  }),
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_1",
+      role: "assistant",
+      model: SONNET,
+      content: [{ type: "text", text: "Working on it..." }],
+      usage: {
+        input_tokens: 90,
+        output_tokens: 30,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // stream closes cleanly here — no `result` line
+];
+
+export const expectedAccumulated = {
+  [SONNET]: {
+    inputTokens: 90,
+    outputTokens: 30,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 0,
+    costUSD: 0,
+  },
+};
+
+export const expectedSessionId = SESSION_ID;

package/fixtures/stream-json/clean-multi-turn.ts

@@ -0,0 +1,209 @@
+/**
+ * Hand-authored synthetic `claude -p --output-format stream-json --verbose`
+ * transcript: a clean multi-turn, multi-model session that ends in a `result`
+ * event.
+ *
+ * NOTE: These NDJSON lines are hand-authored per the documented public Claude
+ * Code CLI stream-json/--verbose schema — they stand in for real captures that
+ * will be swapped in and validated later. Each entry in `lines` is one JSON
+ * object, exactly as the CLI emits one-per-line on stdout.
+ *
+ * Shape of the session:
+ *  - one `system`/`init` line
+ *  - assistant turn `msg_1` (sonnet) emitted TWICE with identical repeated usage
+ *    (same message.id spanning two stream lines) — must be deduped to one turn
+ *  - a `user` tool-result line (no usage)
+ *  - assistant turn `msg_2` (sonnet)
+ *  - assistant turn `msg_3` (opus) — a second, different model
+ *  - one terminal `result`/success line carrying the authoritative
+ *    modelUsage/total_cost_usd/usage (byte-identical in shape to the old
+ *    single-blob `--output-format json` output)
+ */
+
+const SONNET = "claude-sonnet-4-6";
+const OPUS = "claude-opus-4-8";
+const SESSION_ID = "sess-clean-multi";
+
+export const lines: string[] = [
+  JSON.stringify({
+    type: "system",
+    subtype: "init",
+    session_id: SESSION_ID,
+    model: SONNET,
+    tools: ["Read", "Write", "Bash"],
+  }),
+  // msg_1 — first stream line for this turn
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_1",
+      role: "assistant",
+      model: SONNET,
+      content: [{ type: "text", text: "Let me look into that." }],
+      usage: {
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 10,
+        cache_creation_input_tokens: 5,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // msg_1 — SAME message.id repeated (e.g. a tool-use block within the turn),
+  // identical usage numbers — must NOT be double counted
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_1",
+      role: "assistant",
+      model: SONNET,
+      content: [{ type: "tool_use", id: "tu_1", name: "Read", input: {} }],
+      usage: {
+        input_tokens: 100,
+        output_tokens: 50,
+        cache_read_input_tokens: 10,
+        cache_creation_input_tokens: 5,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // tool-result feedback — no usage to accumulate
+  JSON.stringify({
+    type: "user",
+    message: {
+      role: "user",
+      content: [{ type: "tool_result", tool_use_id: "tu_1", content: "ok" }],
+    },
+    session_id: SESSION_ID,
+  }),
+  // msg_2 — same model, distinct turn
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_2",
+      role: "assistant",
+      model: SONNET,
+      content: [{ type: "text", text: "Now switching models." }],
+      usage: {
+        input_tokens: 200,
+        output_tokens: 80,
+        cache_read_input_tokens: 20,
+        cache_creation_input_tokens: 0,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // msg_3 — second, different model
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_3",
+      role: "assistant",
+      model: OPUS,
+      content: [{ type: "text", text: "Final answer" }],
+      usage: {
+        input_tokens: 300,
+        output_tokens: 150,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 30,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // terminal result — authoritative totals (costUSD is only known here)
+  JSON.stringify({
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    result: "Final answer",
+    session_id: SESSION_ID,
+    usage: {
+      input_tokens: 600,
+      output_tokens: 280,
+      cache_read_input_tokens: 30,
+      cache_creation_input_tokens: 35,
+    },
+    total_cost_usd: 0.0579,
+    modelUsage: {
+      [SONNET]: {
+        inputTokens: 300,
+        outputTokens: 130,
+        cacheReadInputTokens: 30,
+        cacheCreationInputTokens: 5,
+        costUSD: 0.0123,
+        webSearchRequests: 0,
+        contextWindow: 200000,
+        maxOutputTokens: 8192,
+      },
+      [OPUS]: {
+        inputTokens: 300,
+        outputTokens: 150,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 30,
+        costUSD: 0.0456,
+        webSearchRequests: 0,
+        contextWindow: 200000,
+        maxOutputTokens: 8192,
+      },
+    },
+  }),
+];
+
+/**
+ * The authoritative return the parser must reproduce byte-identically on a
+ * clean exit — sourced from the terminal `result` event, NOT the running
+ * accumulator.
+ */
+export const expected = {
+  result: "Final answer",
+  sessionId: SESSION_ID,
+  totalCostUsd: 0.0579,
+  modelUsage: {
+    [SONNET]: {
+      inputTokens: 300,
+      outputTokens: 130,
+      cacheReadInputTokens: 30,
+      cacheCreationInputTokens: 5,
+      costUSD: 0.0123,
+      webSearchRequests: 0,
+      contextWindow: 200000,
+      maxOutputTokens: 8192,
+    },
+    [OPUS]: {
+      inputTokens: 300,
+      outputTokens: 150,
+      cacheReadInputTokens: 0,
+      cacheCreationInputTokens: 30,
+      costUSD: 0.0456,
+      webSearchRequests: 0,
+      contextWindow: 200000,
+      maxOutputTokens: 8192,
+    },
+  },
+};
+
+/**
+ * The running per-model total the streaming parser accumulates from the
+ * `assistant` lines alone (deduped by message.id). costUSD is 0 because cost is
+ * not known until the terminal `result` event. This is what the final
+ * `onProgress` callback should receive.
+ */
+export const expectedAccumulated = {
+  [SONNET]: {
+    inputTokens: 300, // 100 (msg_1, counted once) + 200 (msg_2)
+    outputTokens: 130, // 50 + 80
+    cacheReadInputTokens: 30, // 10 + 20
+    cacheCreationInputTokens: 5, // 5 + 0
+    costUSD: 0,
+  },
+  [OPUS]: {
+    inputTokens: 300,
+    outputTokens: 150,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 30,
+    costUSD: 0,
+  },
+};
+
+/** Distinct message ids in emission order — onProgress should fire once each. */
+export const expectedProgressCount = 3;

package/fixtures/stream-json/progress-phases.ts

@@ -0,0 +1,203 @@
+/**
+ * Hand-authored synthetic `claude -p --output-format stream-json --verbose`
+ * transcript exercising `agent/src/runtime/progress-milestones.ts`'s block → phase
+ * mapping end-to-end through `_consumeStream`'s `handleLine` closure.
+ *
+ * Shape of the session:
+ *  - one `system`/`init` line
+ *  - assistant turn `msg_1`: a `thinking` block, then a `tool_use` Read block
+ *    (no `usage` field on this line — a tool_use-only line must still be able
+ *    to fire a phase update, exercised BEFORE the usage guard)
+ *  - assistant turn `msg_2`: a second `tool_use` Read block (same phase as
+ *    msg_1's Read — repeated identical phases must collapse to a single fire)
+ *  - assistant turn `msg_3`: an `mcp__*`-prefixed tool name → generic `tool`
+ *  - assistant turn `msg_4`: an unrecognized/unknown tool name → generic `tool`
+ *  - assistant turn `msg_5`: a plain `text` block → `writing`
+ *  - one terminal `result`/success line
+ *
+ * `tool_use` blocks intentionally carry `input` payloads containing
+ * fake-secret-shaped values and absolute filesystem paths — the mapper must
+ * never read `block.input`, so these values must never surface anywhere in
+ * the resulting phase sequence.
+ */
+
+const SONNET = "claude-sonnet-4-6";
+const SESSION_ID = "sess-progress-phases";
+
+export const lines: string[] = [
+  JSON.stringify({
+    type: "system",
+    subtype: "init",
+    session_id: SESSION_ID,
+    model: SONNET,
+    tools: ["Read", "Grep", "Bash"],
+  }),
+  // msg_1 — thinking block, then a tool_use Read block. No `usage` field:
+  // exercises firing a phase BEFORE the existing usage guard.
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_1",
+      role: "assistant",
+      model: SONNET,
+      content: [
+        { type: "thinking", thinking: "Let me look at the file first." },
+        {
+          type: "tool_use",
+          id: "tu_1",
+          name: "Read",
+          input: {
+            file_path: "/home/alice/.ssh/id_rsa",
+            api_key: "sk-fake-12345",
+          },
+        },
+      ],
+    },
+    session_id: SESSION_ID,
+  }),
+  // tool-result feedback — out of scope for phase mapping
+  JSON.stringify({
+    type: "user",
+    message: {
+      role: "user",
+      content: [{ type: "tool_result", tool_use_id: "tu_1", content: "ok" }],
+    },
+    session_id: SESSION_ID,
+  }),
+  // msg_2 — a SECOND Read tool_use block: same phase ("reading") as msg_1's
+  // Read block — must collapse to a single fire (no new phase event).
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_2",
+      role: "assistant",
+      model: SONNET,
+      content: [
+        {
+          type: "tool_use",
+          id: "tu_2",
+          name: "Read",
+          input: {
+            command: "cat /home/alice/.ssh/id_rsa",
+            api_key: "sk-fake-12345",
+          },
+        },
+      ],
+      usage: {
+        input_tokens: 50,
+        output_tokens: 10,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // msg_3 — an mcp__*-prefixed tool name → generic "tool" phase.
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_3",
+      role: "assistant",
+      model: SONNET,
+      content: [
+        {
+          type: "tool_use",
+          id: "tu_3",
+          name: "mcp__linear__create_issue",
+          input: { api_key: "sk-fake-12345" },
+        },
+      ],
+      usage: {
+        input_tokens: 20,
+        output_tokens: 5,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // msg_4 — an unrecognized/unknown tool name → generic "tool" phase.
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_4",
+      role: "assistant",
+      model: SONNET,
+      content: [
+        {
+          type: "tool_use",
+          id: "tu_4",
+          name: "SomeFutureTool",
+          input: { secret: "sk-fake-12345" },
+        },
+      ],
+      usage: {
+        input_tokens: 20,
+        output_tokens: 5,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // msg_5 — plain text block → "writing".
+  JSON.stringify({
+    type: "assistant",
+    message: {
+      id: "msg_5",
+      role: "assistant",
+      model: SONNET,
+      content: [{ type: "text", text: "Here's what I found." }],
+      usage: {
+        input_tokens: 30,
+        output_tokens: 15,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+    },
+    session_id: SESSION_ID,
+  }),
+  // terminal result
+  JSON.stringify({
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    result: "Here's what I found.",
+    session_id: SESSION_ID,
+    usage: {
+      input_tokens: 120,
+      output_tokens: 35,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    },
+    total_cost_usd: 0.0042,
+    modelUsage: {
+      [SONNET]: {
+        inputTokens: 120,
+        outputTokens: 35,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUSD: 0.0042,
+      },
+    },
+  }),
+];
+
+/**
+ * The ordered sequence of DISTINCT phase fires `onProgress`/`perCallOnProgress`
+ * should emit across this fixture (collapsed — a phase identical to the
+ * immediately preceding fired phase does not fire again). `msg_1`'s thinking
+ * block fires "thinking" first, then its Read tool_use fires "reading".
+ * `msg_2`'s Read tool_use maps to the same "reading" phase as msg_1's —
+ * collapsed, no second fire. `msg_3` (mcp__*) maps to the generic "tool"
+ * phase — a new fire (differs from "reading"). `msg_4` (unknown tool) ALSO
+ * maps to "tool" — identical to the immediately preceding fired phase, so it
+ * collapses too (no second "tool" fire). `msg_5`'s text block fires "writing".
+ */
+export const expectedPhaseSequence = ["thinking", "reading", "tool", "writing"];
+
+/**
+ * Fake-secret-shaped substrings embedded in this fixture's `tool_use.input`
+ * payloads — must never appear anywhere in the phase output.
+ */
+export const forbiddenSubstrings = ["/home/alice/.ssh/id_rsa", "sk-fake-12345"];