@archmax-ai/harness 0.0.0

package/dist/core/listing-redact.js

@@ -0,0 +1,88 @@
+/**
+ * The line-oriented listing filter both governed-capability redactions run on.
+ *
+ * The kernel refuses a path the state may not reach, which is enforcement — but
+ * a scoped tool asks about a *directory*, not a file: `ls skills/`, `glob
+ * catalogs/**\/*.csv`, and `grep` over the root all name a scope the state may
+ * legitimately reach and would hand back everything in it. Blocking those calls
+ * outright is the wrong trade (a state with one enabled capability could then
+ * not list it), so the result is filtered instead.
+ *
+ * This is the only place governance touches a tool **result** rather than a
+ * call, and it exists because invisibility is a requirement of governance in its
+ * own right: a name the model never sees is a capability it never tries.
+ *
+ * Filtering is line-oriented because the upstream filesystem tools render
+ * line-oriented text: `ls` one entry per line, `glob` one path per line, `grep`
+ * a `<path>:` header followed by indented `  <line>: <text>` matches. A header
+ * for a hidden owner therefore suppresses its continuation lines too —
+ * otherwise the matched *content* would survive its filename.
+ */
+/** Whether a line carries no path of its own (a grep match under a header). */
+function isContinuation(line) {
+    return /^\s/.test(line) && line.trim() !== "";
+}
+/**
+ * The path a result line is about, or null when it names none. Takes the leading
+ * token up to the first whitespace or `:` — enough for every shape the upstream
+ * tools emit (`/skills/x (directory)`, `/skills/x/SKILL.md`,
+ * `/skills/x/SKILL.md:`) without trying to parse arbitrary prose.
+ */
+function pathOfLine(line) {
+    const token = line.trim().split(/[\s:]/, 1)[0] ?? "";
+    return token === "" ? null : token;
+}
+/**
+ * Drop from `text` every line about an owner `isHidden` refuses.
+ *
+ * `ownerOf` maps a result line's path to the governed thing that owns it (a
+ * skill slug, a mount name) or `null` when it owns none — a line no owner claims
+ * is always kept, since the state's other rules govern it.
+ *
+ * Returns the text unchanged when nothing was hidden, so a result the filter has
+ * no opinion about is passed through by identity rather than rebuilt.
+ */
+export function redactListing(text, ownerOf, isHidden) {
+    const out = [];
+    let suppressing = false;
+    let hid = false;
+    for (const line of text.split("\n")) {
+        if (isContinuation(line)) {
+            // A grep match line belongs to whichever header preceded it.
+            if (!suppressing)
+                out.push(line);
+            continue;
+        }
+        if (line.trim() === "") {
+            // A blank line separates grep's file groups; keep it only outside a
+            // suppressed group, so a hidden owner leaves no gap where it was.
+            if (!suppressing)
+                out.push(line);
+            continue;
+        }
+        const path = pathOfLine(line);
+        const owner = path == null ? null : ownerOf(path);
+        if (owner == null) {
+            suppressing = false;
+            out.push(line);
+            continue;
+        }
+        suppressing = isHidden(owner);
+        if (suppressing) {
+            hid = true;
+            // Drop the blank separator this group's header would have followed.
+            if (out.length > 0 && out[out.length - 1]?.trim() === "")
+                out.pop();
+            continue;
+        }
+        out.push(line);
+    }
+    return hid ? out.join("\n") : text;
+}
+/**
+ * The scoped file tools whose results are filtered. `read_file` is absent on
+ * purpose: it names one path, which the kernel already refuses, and filtering a
+ * file's *contents* would hand the model a silently truncated document.
+ */
+export const REDACTED_TOOLS = new Set(["ls", "glob", "grep"]);
+//# sourceMappingURL=listing-redact.js.map

package/dist/core/listing-redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing-redact.js","sourceRoot":"","sources":["../../src/core/listing-redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,+EAA+E;AAC/E,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrD,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AACrC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,OAAwC,EACxC,QAAoC;IAEpC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,GAAG,GAAG,KAAK,CAAC;IAEhB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,6DAA6D;YAC7D,IAAI,CAAC,WAAW;gBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjC,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACvB,oEAAoE;YACpE,kEAAkE;YAClE,IAAI,CAAC,WAAW;gBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;YAClB,WAAW,GAAG,KAAK,CAAC;YACpB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,WAAW,EAAE,CAAC;YAChB,GAAG,GAAG,IAAI,CAAC;YACX,oEAAoE;YACpE,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE;gBAAE,GAAG,CAAC,GAAG,EAAE,CAAC;YACpE,SAAS;QACX,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC"}

package/dist/core/match.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one partial-match vocabulary for a *declared* value against an *observed*
+ * one. Case assertions (`calledTool.input`, `blockedTool.input`, …) and tool
+ * mocks (`whenInput`) both read it, so a matcher an author writes means the same
+ * thing whichever side of a tool call it sits on:
+ *
+ * - a mapping matches when every declared key is present and matches — nested
+ *   mappings partially, so undeclared keys are ignored at every depth;
+ * - an array matches element-wise: same length, each element by these rules;
+ * - a string of the form `/pattern/flags` is a regular expression, tested
+ *   against the stringified observed value;
+ * - every other scalar (and `null`) matches by strict equality.
+ *
+ * Runtime-owned (`core/`) because the tool-mock gateway is runtime code and the
+ * runtime never imports from the testing modules.
+ */
+/**
+ * Compile a `/pattern/flags` string to a regex; `null` when the string is not
+ * regex-shaped. Throws on a malformed pattern, so a schema can reject it
+ * statically rather than let it match as a literal at run time.
+ */
+export declare function regexFromString(raw: string): RegExp | null;
+/** Structural equality over JSON-shaped values. */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** Whether `actual` satisfies the declared `expected` shape (see module docs). */
+export declare function partialMatch(expected: unknown, actual: unknown): boolean;

package/dist/core/match.js

@@ -0,0 +1,75 @@
+/**
+ * The one partial-match vocabulary for a *declared* value against an *observed*
+ * one. Case assertions (`calledTool.input`, `blockedTool.input`, …) and tool
+ * mocks (`whenInput`) both read it, so a matcher an author writes means the same
+ * thing whichever side of a tool call it sits on:
+ *
+ * - a mapping matches when every declared key is present and matches — nested
+ *   mappings partially, so undeclared keys are ignored at every depth;
+ * - an array matches element-wise: same length, each element by these rules;
+ * - a string of the form `/pattern/flags` is a regular expression, tested
+ *   against the stringified observed value;
+ * - every other scalar (and `null`) matches by strict equality.
+ *
+ * Runtime-owned (`core/`) because the tool-mock gateway is runtime code and the
+ * runtime never imports from the testing modules.
+ */
+/**
+ * Compile a `/pattern/flags` string to a regex; `null` when the string is not
+ * regex-shaped. Throws on a malformed pattern, so a schema can reject it
+ * statically rather than let it match as a literal at run time.
+ */
+export function regexFromString(raw) {
+    const match = /^\/(.*)\/([a-z]*)$/s.exec(raw);
+    if (!match)
+        return null;
+    return new RegExp(match[1], match[2]);
+}
+/** Structural equality over JSON-shaped values. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null || typeof a !== typeof b || typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    const objA = a;
+    const objB = b;
+    const keysA = Object.keys(objA);
+    return (keysA.length === Object.keys(objB).length && keysA.every((k) => deepEqual(objA[k], objB[k])));
+}
+function isPlainObject(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function scalarMatches(expected, actual) {
+    if (typeof expected === "string") {
+        let regex = null;
+        try {
+            regex = regexFromString(expected);
+        }
+        catch {
+            // A malformed pattern is a schema error upstream; here it can only be a literal.
+        }
+        if (regex)
+            return regex.test(String(actual ?? ""));
+    }
+    return expected === actual;
+}
+/** Whether `actual` satisfies the declared `expected` shape (see module docs). */
+export function partialMatch(expected, actual) {
+    if (Array.isArray(expected)) {
+        return (Array.isArray(actual) &&
+            expected.length === actual.length &&
+            expected.every((v, i) => partialMatch(v, actual[i])));
+    }
+    if (isPlainObject(expected)) {
+        if (!isPlainObject(actual))
+            return false;
+        return Object.entries(expected).every(([k, v]) => k in actual && partialMatch(v, actual[k]));
+    }
+    return scalarMatches(expected, actual);
+}
+//# sourceMappingURL=match.js.map

package/dist/core/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../src/core/match.ts"],"names":[],"mappings":"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"}

package/dist/core/message-readers.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Reading a transcript: what kind a message is, who wrote it, what the agent
+ * last said, and where a turn begins. Every reader is duck-typed over the shapes
+ * a message takes at runtime — a LangChain class instance, a serialized object,
+ * a raw `{ role, content }` — and never `instanceof`, so this module imports
+ * nothing and a host can read a checkpointed transcript without the runtime.
+ * The writers (`runtimeNote`, `humanNote`) live in `messages.ts`.
+ */
+export declare const ROLE_BY_TYPE: Record<string, string>;
+/**
+ * The LangChain message kind (`ai`, `human`, `tool`, `system`, …), read
+ * robustly across the shapes a message can take at runtime: a class instance
+ * (`_getType()`/`getType()`), a serialized object (`type`), or a raw role
+ * (`role`). One definition, shared by the workflow graph, session-artifact
+ * serialization, and history building, so message classification cannot drift.
+ */
+export declare function messageTypeOf(message: unknown): string;
+/** Whether a message is an assistant/AI message (`ai` or `assistant`). */
+export declare function isAiMessage(message: unknown): boolean;
+/** Whether a message is a human/user message (`human` or `user`). */
+export declare function isHumanMessage(message: unknown): boolean;
+/**
+ * What the agent last *said*: the final assistant message carrying text. Tool
+ * results — the `archmax_advance` confirmation is routinely the literal last
+ * message — and the runtime's own notes are skipped, so this is the session's
+ * answer as a person would read it.
+ */
+export declare function lastAgentText(messages: unknown[]): string;
+/**
+ * What the runtime wrote into a transcript, and why.
+ *
+ *  - `decision` — a person picked an edge at a human state and the session was routed
+ *  - `event` — a trigger firing was delivered to a parked session
+ *  - `error` — a failed state was routed to its `on_error` target
+ *  - `after` — a terminal state's completion check asked for a revision
+ *  - `sub-workflow` — a resumed child's result, handed back to its caller
+ *  - `opening` — the fixed line a child session's own transcript opens with
+ */
+export type RuntimeNoteKind = "decision" | "event" | "error" | "after" | "sub-workflow" | "opening";
+/** Where the marker lives on a message: `additional_kwargs.archmax.note`. */
+export declare const NOTE_KEY = "archmax";
+/**
+ * The kind of runtime note a message is, or `null` if a person wrote it. Read
+ * from `additional_kwargs` across the shapes a message takes at runtime, the way
+ * {@link messageTypeOf} reads a message's kind.
+ */
+export declare function runtimeNoteKind(message: unknown): RuntimeNoteKind | null;
+/** Whether the runtime wrote this message rather than a person. */
+export declare function isRuntimeNote(message: unknown): boolean;
+/**
+ * Whether a message opens a turn: something the session was **told**, by a person
+ * or by the runtime. A runtime note opens one too — an arrival, a decision, a
+ * correction is news the session has to answer for. Evaluated per message, so a
+ * transcript mixing human-role notes (checkpointed before notes became tool-call
+ * pairs) with marked notes decides identically for each.
+ */
+export declare function opensTurn(message: unknown): boolean;
+/** Whether the last thing in the transcript is something the session was told. */
+export declare function lastMessageIsHuman(messages: unknown[]): boolean;
+/**
+ * Whether the agent has said anything since the last thing it was told — any
+ * assistant message carrying non-empty text, including one that also made a tool
+ * call. The window is closed by a turn-opening message: a person's, or the
+ * runtime's own narration, which closes it exactly as a real message does.
+ */
+export declare function spokeSinceLastHumanMessage(messages: unknown[]): boolean;
+/**
+ * The messages appended since `cursor` — a message count read before a turn
+ * (`agent.sessions.messageCount(sessionId)`), so a host slices exactly what one
+ * `invoke` added without knowing how many seeds or notes opened it. A cursor past
+ * the end yields nothing.
+ */
+export declare function messagesSince<T>(messages: readonly T[], cursor: number): T[];
+/**
+ * The trailing turn of a transcript: from the last thing the session was told to
+ * the end. What the session was told may be several adjacent messages — a
+ * delivered firing is a note pair followed by the person's message — so the
+ * turn starts at the first of the last unbroken run of turn-opening messages.
+ * For everything one `invoke` appended, use a cursor and {@link messagesSince}:
+ * a child's result note lands mid-turn and opens a reply window of its own.
+ */
+export declare function lastTurn<T>(messages: readonly T[]): T[];
+/** Flatten LangChain message content (string or multimodal parts) to plain text. */
+export declare function contentToString(content: unknown): string;

package/dist/core/message-readers.js

@@ -0,0 +1,159 @@
+/**
+ * Reading a transcript: what kind a message is, who wrote it, what the agent
+ * last said, and where a turn begins. Every reader is duck-typed over the shapes
+ * a message takes at runtime — a LangChain class instance, a serialized object,
+ * a raw `{ role, content }` — and never `instanceof`, so this module imports
+ * nothing and a host can read a checkpointed transcript without the runtime.
+ * The writers (`runtimeNote`, `humanNote`) live in `messages.ts`.
+ */
+export const ROLE_BY_TYPE = {
+    human: "user",
+    ai: "assistant",
+    system: "system",
+    tool: "tool",
+    function: "tool",
+};
+/**
+ * The LangChain message kind (`ai`, `human`, `tool`, `system`, …), read
+ * robustly across the shapes a message can take at runtime: a class instance
+ * (`_getType()`/`getType()`), a serialized object (`type`), or a raw role
+ * (`role`). One definition, shared by the workflow graph, session-artifact
+ * serialization, and history building, so message classification cannot drift.
+ */
+export function messageTypeOf(message) {
+    const msg = message;
+    const t = msg._getType?.() ??
+        msg.getType?.() ??
+        msg.type ??
+        msg.role ??
+        "";
+    return String(t);
+}
+/** Whether a message is an assistant/AI message (`ai` or `assistant`). */
+export function isAiMessage(message) {
+    const t = messageTypeOf(message);
+    return t === "ai" || t === "assistant";
+}
+/** Whether a message is a human/user message (`human` or `user`). */
+export function isHumanMessage(message) {
+    const t = messageTypeOf(message);
+    return t === "human" || t === "user";
+}
+/**
+ * What the agent last *said*: the final assistant message carrying text. Tool
+ * results — the `archmax_advance` confirmation is routinely the literal last
+ * message — and the runtime's own notes are skipped, so this is the session's
+ * answer as a person would read it.
+ */
+export function lastAgentText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (!isAiMessage(message) || isRuntimeNote(message))
+            continue;
+        const text = contentToString(message.content).trim();
+        if (text)
+            return text;
+    }
+    return "";
+}
+/** Where the marker lives on a message: `additional_kwargs.archmax.note`. */
+export const NOTE_KEY = "archmax";
+/**
+ * The kind of runtime note a message is, or `null` if a person wrote it. Read
+ * from `additional_kwargs` across the shapes a message takes at runtime, the way
+ * {@link messageTypeOf} reads a message's kind.
+ */
+export function runtimeNoteKind(message) {
+    const msg = message;
+    // A class instance and a plain message-like object both carry
+    // `additional_kwargs` at the top; LangChain's own serialized-constructor form
+    // (what a checkpoint holds on disk) nests it under `kwargs`.
+    const kwargs = (msg?.additional_kwargs ?? msg?.kwargs?.additional_kwargs);
+    const marker = kwargs?.[NOTE_KEY];
+    const note = marker?.note;
+    return typeof note === "string" ? note : null;
+}
+/** Whether the runtime wrote this message rather than a person. */
+export function isRuntimeNote(message) {
+    return runtimeNoteKind(message) !== null;
+}
+/**
+ * Whether a message opens a turn: something the session was **told**, by a person
+ * or by the runtime. A runtime note opens one too — an arrival, a decision, a
+ * correction is news the session has to answer for. Evaluated per message, so a
+ * transcript mixing human-role notes (checkpointed before notes became tool-call
+ * pairs) with marked notes decides identically for each.
+ */
+export function opensTurn(message) {
+    return isHumanMessage(message) || isRuntimeNote(message);
+}
+/** Whether the last thing in the transcript is something the session was told. */
+export function lastMessageIsHuman(messages) {
+    const last = messages[messages.length - 1];
+    return last !== undefined && opensTurn(last);
+}
+/**
+ * Whether the agent has said anything since the last thing it was told — any
+ * assistant message carrying non-empty text, including one that also made a tool
+ * call. The window is closed by a turn-opening message: a person's, or the
+ * runtime's own narration, which closes it exactly as a real message does.
+ */
+export function spokeSinceLastHumanMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message === undefined)
+            continue;
+        if (opensTurn(message))
+            return false;
+        if (!isAiMessage(message))
+            continue;
+        if (contentToString(message.content).trim() !== "")
+            return true;
+    }
+    return false;
+}
+/**
+ * The messages appended since `cursor` — a message count read before a turn
+ * (`agent.sessions.messageCount(sessionId)`), so a host slices exactly what one
+ * `invoke` added without knowing how many seeds or notes opened it. A cursor past
+ * the end yields nothing.
+ */
+export function messagesSince(messages, cursor) {
+    const from = Math.max(0, Math.floor(cursor));
+    return from >= messages.length ? [] : messages.slice(from);
+}
+/**
+ * The trailing turn of a transcript: from the last thing the session was told to
+ * the end. What the session was told may be several adjacent messages — a
+ * delivered firing is a note pair followed by the person's message — so the
+ * turn starts at the first of the last unbroken run of turn-opening messages.
+ * For everything one `invoke` appended, use a cursor and {@link messagesSince}:
+ * a child's result note lands mid-turn and opens a reply window of its own.
+ */
+export function lastTurn(messages) {
+    let end = messages.length - 1;
+    while (end >= 0 && !opensTurn(messages[end]))
+        end--;
+    if (end < 0)
+        return [];
+    let start = end;
+    while (start > 0 && opensTurn(messages[start - 1]))
+        start--;
+    return messages.slice(start);
+}
+/** Flatten LangChain message content (string or multimodal parts) to plain text. */
+export function contentToString(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => typeof part === "string"
+            ? part
+            : typeof part?.text === "string"
+                ? part.text
+                : "")
+            .join("");
+    }
+    return "";
+}
+//# sourceMappingURL=message-readers.js.map

package/dist/core/message-readers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-readers.js","sourceRoot":"","sources":["../../src/core/message-readers.ts"],"names":[],"mappings":"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"}

package/dist/core/messages.d.ts

@@ -0,0 +1,49 @@
+import { HumanMessage } from "@langchain/core/messages";
+import type { BaseMessage } from "@langchain/core/messages";
+import { type RuntimeNoteKind } from "./message-readers.js";
+export { contentToString, isAiMessage, isHumanMessage, isRuntimeNote, lastAgentText, lastMessageIsHuman, lastTurn, messagesSince, messageTypeOf, opensTurn, runtimeNoteKind, spokeSinceLastHumanMessage, type RuntimeNoteKind, } from "./message-readers.js";
+/**
+ * A message the runtime wrote into a session's transcript on its own behalf, shaped
+ * as a **tool call and its result**: an assistant message carrying one
+ * {@link NOTE_TOOL} call, and the note itself as that call's result.
+ *
+ * Role is the only authorship signal a model reads; a human-role note gets
+ * treated as a request, and a mid-thread system message is rejected by Anthropic
+ * after assistant text, so notes are tool-call pairs. The pair is a transcript
+ * shape, not an invocation: the model never made the call, it is answered the
+ * instant it appears, nothing runs, and {@link NOTE_TOOL} is registered nowhere.
+ *
+ * Both messages carry the marker in `additional_kwargs` (round-trips through
+ * checkpointed serialization), so a host can hide the synthetic call and label
+ * the note without parsing content. The `[bracket]` prefix stays in the text for
+ * people to read; it is not the signal.
+ */
+export declare function runtimeNote(kind: RuntimeNoteKind, text: string): BaseMessage[];
+/**
+ * The one runtime-authored message that stays human-role: a child session's
+ * opening line, which is that session's *entire* transcript at that moment. A
+ * session has to open with a request, so it is marked rather than reshaped.
+ */
+export declare function humanNote(kind: RuntimeNoteKind, text: string): HumanMessage;
+export interface HistoryEntry {
+    role: string;
+    content: string;
+    toolCalls?: {
+        name: string;
+        args: unknown;
+    }[];
+}
+export interface RunContext {
+    history: HistoryEntry[];
+    userRequest: string;
+}
+/**
+ * Build the compact view a lifecycle hook and a rubric grader read: the last
+ * {@link HISTORY_WINDOW} messages plus the request that opened the session.
+ *
+ * `userRequest` is derived from the **whole** list, not the window: a grader
+ * asked whether the reply satisfies the request must see the request, and a
+ * session of more than a couple of tool-calling turns pushes the opening message
+ * out of any fixed window (issue #61).
+ */
+export declare function runContextFromMessages(messages: unknown[]): RunContext;

package/dist/core/messages.js

@@ -0,0 +1,85 @@
+import { randomUUID } from "node:crypto";
+import { AIMessage, HumanMessage, ToolMessage } from "@langchain/core/messages";
+import { NOTE_TOOL } from "../machine/tool-names.js";
+import { contentToString, messageTypeOf, NOTE_KEY, ROLE_BY_TYPE } from "./message-readers.js";
+// The readers are pure and live in `message-readers.ts` (the `@archmax-ai/harness/messages`
+// subpath); re-exported so every runtime importer keeps one module for both halves.
+export { contentToString, isAiMessage, isHumanMessage, isRuntimeNote, lastAgentText, lastMessageIsHuman, lastTurn, messagesSince, messageTypeOf, opensTurn, runtimeNoteKind, spokeSinceLastHumanMessage, } from "./message-readers.js";
+/** The marker every message of a runtime note carries. */
+function marker(kind) {
+    return { [NOTE_KEY]: { note: kind } };
+}
+/**
+ * A message the runtime wrote into a session's transcript on its own behalf, shaped
+ * as a **tool call and its result**: an assistant message carrying one
+ * {@link NOTE_TOOL} call, and the note itself as that call's result.
+ *
+ * Role is the only authorship signal a model reads; a human-role note gets
+ * treated as a request, and a mid-thread system message is rejected by Anthropic
+ * after assistant text, so notes are tool-call pairs. The pair is a transcript
+ * shape, not an invocation: the model never made the call, it is answered the
+ * instant it appears, nothing runs, and {@link NOTE_TOOL} is registered nowhere.
+ *
+ * Both messages carry the marker in `additional_kwargs` (round-trips through
+ * checkpointed serialization), so a host can hide the synthetic call and label
+ * the note without parsing content. The `[bracket]` prefix stays in the text for
+ * people to read; it is not the signal.
+ */
+export function runtimeNote(kind, text) {
+    const callId = `note_${randomUUID()}`;
+    return [
+        new AIMessage({
+            content: "",
+            tool_calls: [{ id: callId, name: NOTE_TOOL, args: { note: kind } }],
+            additional_kwargs: marker(kind),
+        }),
+        new ToolMessage({
+            content: text,
+            tool_call_id: callId,
+            name: NOTE_TOOL,
+            additional_kwargs: marker(kind),
+        }),
+    ];
+}
+/**
+ * The one runtime-authored message that stays human-role: a child session's
+ * opening line, which is that session's *entire* transcript at that moment. A
+ * session has to open with a request, so it is marked rather than reshaped.
+ */
+export function humanNote(kind, text) {
+    return new HumanMessage({ content: text, additional_kwargs: marker(kind) });
+}
+/** How many trailing messages a hook's compact `history` carries. */
+const HISTORY_WINDOW = 24;
+/** One message as a hook reads it: its role, its text, and any tool calls it made. */
+function historyEntry(m) {
+    const msg = m;
+    const type = messageTypeOf(m) || "?";
+    const role = ROLE_BY_TYPE[type] ?? type;
+    const entry = { role, content: contentToString(msg.content) };
+    const toolCalls = msg.tool_calls;
+    if (Array.isArray(toolCalls) && toolCalls.length > 0) {
+        entry.toolCalls = toolCalls.map((c) => {
+            const call = c;
+            return { name: String(call.name ?? ""), args: call.args ?? {} };
+        });
+    }
+    return entry;
+}
+/**
+ * Build the compact view a lifecycle hook and a rubric grader read: the last
+ * {@link HISTORY_WINDOW} messages plus the request that opened the session.
+ *
+ * `userRequest` is derived from the **whole** list, not the window: a grader
+ * asked whether the reply satisfies the request must see the request, and a
+ * session of more than a couple of tool-calling turns pushes the opening message
+ * out of any fixed window (issue #61).
+ */
+export function runContextFromMessages(messages) {
+    const all = Array.isArray(messages) ? messages : [];
+    const history = all.slice(-HISTORY_WINDOW).map(historyEntry);
+    const opening = all.find((m) => (ROLE_BY_TYPE[messageTypeOf(m) || "?"] ?? "") === "user");
+    const userRequest = opening !== undefined ? contentToString(opening.content) : "";
+    return { history, userRequest };
+}
+//# sourceMappingURL=messages.js.map

package/dist/core/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/core/messages.ts"],"names":[],"mappings":"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"}

package/dist/core/mount-prompt.d.ts

@@ -0,0 +1,28 @@
+import type { MountPrefixes } from "./zones.js";
+/**
+ * The model-facing account of the governed mounts a state may reach — the mount
+ * twin of `renderSkillsSection`, and in the **volatile** system block for the
+ * same reason: what varies with the state cannot live in the cacheable prefix.
+ *
+ * The static "Workspace zones" section therefore names ungoverned mounts only
+ * (see {@link renderWorkspaceZones}), and this names what this state was given.
+ * A state that reaches none gets no heading rather than an empty one, and
+ * therefore no invitation to go looking.
+ */
+/** Heading of the rendered section, also the marker tests assert on. */
+export declare const MOUNTS_SECTION_HEADING = "Mounts available in this state";
+/**
+ * Render the section for one state's enabled governed mounts, or `null` when the
+ * set is empty.
+ *
+ * `enabled` is the resolved name order (see `WorkflowMachine.enabledMounts`),
+ * sorted here so the text is stable under a spec edit that only reorders a
+ * list — a prompt section that reordered itself would churn the transcript for
+ * no reason. Each name is printed as the agent addresses it: a directory mount
+ * with a trailing slash, a file mount by its exact path, read-only or read/write
+ * per `writable` — the state's own posture (`WorkflowMachine.mountWritable`),
+ * which a grant's `access: read` may have narrowed below the host's. A mount the
+ * host declared unsearchable gets a browse-only note, so the model lists and
+ * reads it rather than searching it; every other line is unchanged.
+ */
+export declare function renderMountsSection(enabled: readonly string[], mounts: MountPrefixes, writable: (name: string) => boolean): string | null;