@archmax-ai/harness 0.0.0

package/dist/sessions/resume.js

@@ -0,0 +1,288 @@
+/**
+ * Resuming a parked session — the one path behind `decide`, `reply` and
+ * `deliver`, and the `Outcome` every way of entering a session settles to.
+ *
+ * A park is two facts: the checkpointed status and a live suspension. Every
+ * resume reads both, validates its payload **before** the graph is touched (a
+ * rejected resume leaves the park untouched), hands the payload to the suspended
+ * `interrupt()` through `Command({ resume })`, and reads the settled state off
+ * the invoke result — the same shape a turn produces.
+ */
+import { Command } from "@langchain/langgraph";
+import { mergeConfigs } from "@langchain/core/runnables";
+import { lastAgentText } from "../core/messages.js";
+import { hasUsage } from "../core/usage.js";
+import { InvalidVariableNameError, VARIABLE_NAME_PATTERN, } from "../machine/variables.js";
+import { parkedStateOf, readAuditTrail, readRunUsage, readVariables, WORKFLOW_STATUSES, } from "../workflow/state.js";
+import { childSessionId } from "./scope.js";
+/**
+ * Whether a resume payload is a message rather than a decision or a delivery.
+ * Told apart **structurally** — a `target` routes, a `trigger` is delivered (and
+ * may carry a message with it), a `message` alone is answered — never by reading
+ * the words: "yes, approve it" typed into the chat is not a decision.
+ */
+export function isMessageResume(resume) {
+    const payload = resume;
+    if (payload?.trigger !== undefined && payload.trigger !== null)
+        return false;
+    const message = payload?.message;
+    return typeof message === "string" && message.trim() !== "";
+}
+// --- Errors --------------------------------------------------------------------
+/** Thrown when a decision or reply targets a session that is not parked at a human state. */
+export class SessionNotParkedError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Session '${sessionId}' is not parked at a human state; there is nothing to decide.`);
+        this.sessionId = sessionId;
+        this.name = "SessionNotParkedError";
+    }
+}
+/** Thrown when a decision names a target that is not one of the parked state's transitions. */
+export class InvalidDecisionTargetError extends Error {
+    sessionId;
+    target;
+    validTargets;
+    constructor(sessionId, target, validTargets) {
+        super((target
+            ? `'${target}' is not a valid decision target for session '${sessionId}'. `
+            : `A decision target is required for session '${sessionId}'. `) +
+            `Choose one of: ${validTargets.join(", ")}.`);
+        this.sessionId = sessionId;
+        this.target = target;
+        this.validTargets = validTargets;
+        this.name = "InvalidDecisionTargetError";
+    }
+}
+/** Thrown when a reply is sent to a parked session without any content. */
+export class EmptyMessageError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`A message is required to reply to session '${sessionId}': there is nothing to answer, and ` +
+            `a parked session is not moved by an empty turn.`);
+        this.sessionId = sessionId;
+        this.name = "EmptyMessageError";
+    }
+}
+/** Thrown when a delivery targets a session that is not parked awaiting input. */
+export class SessionNotAwaitingInputError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Session '${sessionId}' is not parked awaiting an event; there is nothing to deliver to. ` +
+            `A session awaiting a human decision resumes through a decision instead.`);
+        this.sessionId = sessionId;
+        this.name = "SessionNotAwaitingInputError";
+    }
+}
+/** Thrown when a delivery carries no trigger id to record as the session's current one. */
+export class MissingDeliveryTriggerError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`A trigger id is required to deliver to session '${sessionId}': it becomes the session's ` +
+            `current trigger, which its hooks and guards read. Any id is accepted — a park ` +
+            `awaits no particular one.`);
+        this.sessionId = sessionId;
+        this.name = "MissingDeliveryTriggerError";
+    }
+}
+// --- Reading parked state ------------------------------------------------------
+/**
+ * Read a session that must be parked in `status`, or `null`. "Parked" is two
+ * conditions — the checkpointed status *and* a pending interrupt — so every
+ * resume asks it here.
+ */
+export async function readParkedSession(graph, sessionId, status) {
+    const snapshot = await graph.getState({ configurable: { thread_id: sessionId } });
+    const values = (snapshot?.values ?? {});
+    const suspensions = (snapshot?.tasks ?? []).flatMap((t) => t.interrupts ?? []);
+    if (suspensions.length === 0)
+        return null;
+    return values.status === status ? values : null;
+}
+/** The park a settled state presents, on whichever channel, or nothing. */
+function parkOf(values) {
+    const deciding = values.pendingDecision;
+    const waiting = values.pendingInput;
+    if (values.status === WORKFLOW_STATUSES.awaitingDecision && deciding) {
+        return { channel: "decision", pending: deciding };
+    }
+    if (values.status === WORKFLOW_STATUSES.awaitingInput && waiting) {
+        return { channel: "input", pending: waiting };
+    }
+    return undefined;
+}
+/**
+ * The delegated child a decision park belongs to, read from the head of the
+ * `pendingDelegations` queue — the record the runtime presents as the session's
+ * pending decision. Only a decision park can be delegated; a wait park is always
+ * the session's own.
+ */
+function delegationOf(values, channel, sessionId) {
+    if (channel !== "decision")
+        return undefined;
+    const queue = values.pendingDelegations;
+    const head = Array.isArray(queue) ? queue[0] : undefined;
+    if (!head)
+        return undefined;
+    return {
+        workflow: head.workflow,
+        ...(sessionId ? { sessionId: childSessionId(sessionId, head.identity) } : {}),
+        identity: head.identity,
+        dispatchId: head.dispatchId,
+        toolCallId: head.toolCallId,
+        state: parkedStateOf(head),
+    };
+}
+/**
+ * The settled values of a turn or a resume, read into a {@link ResumeOutcome}.
+ * `sessionId` is the session the values belong to, when the caller knows it; it
+ * lets a delegated park name the child's session id.
+ */
+export function settle(result, sessionId) {
+    const messages = Array.isArray(result.messages) ? result.messages : [];
+    const park = parkOf(result);
+    const parkedAt = park ? parkedStateOf(park.pending) : undefined;
+    const delegation = delegationOf(result, park?.channel, sessionId);
+    const usage = readRunUsage(result);
+    return {
+        status: typeof result.status === "string" ? result.status : undefined,
+        workflowState: typeof result.workflowState === "string" ? result.workflowState : undefined,
+        reparked: park !== undefined,
+        ...(park ? { parkedChannel: park.channel, pending: park.pending } : {}),
+        ...(parkedAt ? { state: parkedAt, node: parkedAt } : {}),
+        ...(delegation ? { delegation } : {}),
+        reply: lastAgentText(messages),
+        messages,
+        auditTrail: readAuditTrail(result),
+        variables: readVariables(result),
+        ...(hasUsage(usage) ? { usage } : {}),
+    };
+}
+/** The {@link Outcome} a settled {@link ResumeOutcome} amounts to. */
+export function outcomeOf(settled, disposition) {
+    const kind = settled.reparked
+        ? "parked"
+        : settled.status === WORKFLOW_STATUSES.rejected
+            ? "rejected"
+            : "completed";
+    const state = settled.state ?? settled.workflowState;
+    return {
+        kind,
+        disposition,
+        ...(settled.status ? { status: settled.status } : {}),
+        ...(state ? { state } : {}),
+        ...(settled.parkedChannel ? { parkedChannel: settled.parkedChannel } : {}),
+        ...(settled.pending ? { pending: settled.pending } : {}),
+        ...(settled.delegation ? { delegation: settled.delegation } : {}),
+        reply: settled.reply,
+        messages: settled.messages,
+        auditTrail: settled.auditTrail,
+        variables: settled.variables,
+        ...(settled.usage ? { usage: settled.usage } : {}),
+    };
+}
+// --- The one resume path ---------------------------------------------------------
+/**
+ * Validate a payload against the parked session and produce the value the
+ * suspended `interrupt()` receives — before the graph is touched. Also returns
+ * the state the session is parked at, which a reply (never routing) reports as its own.
+ */
+async function validate(graph, sessionId, payload) {
+    if ("decision" in payload) {
+        const values = await readParkedSession(graph, sessionId, WORKFLOW_STATUSES.awaitingDecision);
+        if (!values)
+            throw new SessionNotParkedError(sessionId);
+        const pending = values.pendingDecision;
+        // A decision routes only to a target the session can actually leave for: a
+        // self-targeted transition would end the session as `completed`. Refused
+        // with the options that do lead somewhere.
+        const parkedAt = parkedStateOf(pending);
+        const validTargets = (pending?.transitions ?? []).map((t) => t.to).filter((to) => to !== parkedAt);
+        const target = (payload.decision?.target ?? "").trim();
+        if (!target || !validTargets.includes(target)) {
+            throw new InvalidDecisionTargetError(sessionId, target || undefined, validTargets);
+        }
+        return { value: payload.decision, parkedAt };
+    }
+    if ("delivery" in payload) {
+        const values = await readParkedSession(graph, sessionId, WORKFLOW_STATUSES.awaitingInput);
+        if (!values)
+            throw new SessionNotAwaitingInputError(sessionId);
+        const requested = (payload.delivery?.trigger?.id ?? "").trim();
+        if (requested === "")
+            throw new MissingDeliveryTriggerError(sessionId);
+        // The same rule host seeds obey at assembly, and the same error.
+        for (const name of Object.keys(payload.delivery.variables ?? {})) {
+            if (!VARIABLE_NAME_PATTERN.test(name)) {
+                throw new InvalidVariableNameError(name, `delivered to session '${sessionId}'`);
+            }
+        }
+        const message = (payload.delivery.message ?? "").trim();
+        return {
+            value: {
+                trigger: { id: requested },
+                variables: payload.delivery.variables ?? {},
+                ...(message ? { message } : {}),
+            },
+            parkedAt: parkedStateOf(values.pendingInput),
+        };
+    }
+    const values = await readParkedSession(graph, sessionId, WORKFLOW_STATUSES.awaitingDecision);
+    if (!values)
+        throw new SessionNotParkedError(sessionId);
+    const text = (payload.message ?? "").trim();
+    if (!text)
+        throw new EmptyMessageError(sessionId);
+    return {
+        value: { message: text },
+        parkedAt: parkedStateOf(values.pendingDecision),
+    };
+}
+/**
+ * Resume a parked session with a decision, a reply or a delivery. Everything is
+ * validated before the graph is touched; the invoke result *is* the resumed state.
+ */
+export async function resume(graph, sessionId, payload, config) {
+    const { value, parkedAt } = await validate(graph, sessionId, payload);
+    // A resumed turn is a turn: the caller's config carries that turn's tool mocks
+    // and its abort signal, so it merges here exactly as it does on a fresh turn.
+    // The thread id is applied last, so no caller can redirect the resume.
+    const result = await graph.invoke(new Command({ resume: value }), mergeConfigs(config, { configurable: { thread_id: sessionId } }));
+    const outcome = settle(result, sessionId);
+    if ("message" in payload) {
+        // A message never routes: the session is parked where it was. The resumed
+        // record is preferred only so the two cannot disagree.
+        const state = outcome.state || parkedAt || "";
+        return { ...outcome, reparked: true, parkedChannel: "decision", state, node: state };
+    }
+    return outcome;
+}
+// --- Conveniences ----------------------------------------------------------------
+/**
+ * Resume a session parked at a human state with the person's decision. Throws
+ * {@link SessionNotParkedError} when the session is not awaiting a decision, and
+ * {@link InvalidDecisionTargetError} when `target` is not a declared transition.
+ */
+export function decide(graph, sessionId, resolution, config) {
+    return resume(graph, sessionId, { decision: resolution }, config);
+}
+/**
+ * Reply to a session parked at a human state and get its answer: a turn with no
+ * tools, after which the session stays parked at the same state with the same
+ * pending decision. Throws {@link SessionNotParkedError} and {@link EmptyMessageError}.
+ */
+export async function reply(graph, sessionId, message, config) {
+    return (await resume(graph, sessionId, { message }, config));
+}
+/** @deprecated Older spelling of {@link reply}; kept for one release. */
+export const respond = reply;
+/**
+ * Resume a parked session with a delivered firing: the session continues in the
+ * state it parked in, the delivered id becomes its current trigger, and the
+ * variables seed what the event carried. Throws {@link SessionNotAwaitingInputError}
+ * and {@link MissingDeliveryTriggerError}.
+ */
+export function deliver(graph, sessionId, delivery, config) {
+    return resume(graph, sessionId, { delivery }, config);
+}
+//# sourceMappingURL=resume.js.map

package/dist/sessions/resume.js.map

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

package/dist/sessions/scope.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The **session scope** — the unit every per-session resource is keyed by (the
+ * sandbox REPL session, the middleware's per-session context, the PTC budget).
+ * A sub-workflow's child is an ordinary session with its own id
+ * (`<parent>~<dispatch identity>`); only the dispatch **chain** (cycle and depth
+ * refusals) and the **dispatch id** (event attribution) ride the config.
+ */
+import type { RunnableConfig } from "@langchain/core/runnables";
+/** The session id assumed when a config carries no `thread_id`; every per-session map keys on this spelling. */
+export declare const DEFAULT_SESSION_ID = "__default__";
+/**
+ * Where the dispatch chain of workflow slugs rides between a parent session and
+ * its child; what makes depth and cycle refusals possible without a shared registry.
+ */
+export declare const SUB_WORKFLOW_CHAIN_KEY = "archmax_sub_workflow_chain";
+/** Where a child session's dispatch id rides, so events emitted inside it can be nested. */
+export declare const SUB_WORKFLOW_DISPATCH_KEY = "archmax_sub_workflow_dispatch";
+/**
+ * Where the slug of the state a **script's** tool call is made from rides. The
+ * PTC gateway is refreshed with the state in force on every model call and hands
+ * the tool only a `RunnableConfig`; an agent-initiated delegation never needs it.
+ */
+export declare const CALLING_STATE_KEY = "archmax_calling_state";
+/** The state a script's call is made from, read from its config. */
+export declare function callingStateFrom(config: {
+    configurable?: Configurable;
+}): string | undefined;
+/**
+ * Where **per-invocation** variable seeds ride. A child's seeds differ per
+ * dispatch while the composed child is shared, and the graph input cannot carry
+ * them (the turn boundary rewrites the `variables` channel); the config is the
+ * one per-invocation, never-checkpointed channel.
+ */
+export declare const SEED_VARIABLES_KEY = "archmax_seed_variables";
+/** The `configurable` bag of a runnable config, however partially typed the caller has it. */
+type Configurable = Record<string, unknown> | undefined;
+/** A turn's execution scope: which session, and how it was reached. */
+export interface SessionScope {
+    /** The LangGraph `thread_id` — the session whose zone and store this turn uses. */
+    sessionId: string;
+    /** Workflow slugs from the outermost session down to and including this one. */
+    chain: readonly string[];
+    /** How many delegations deep this session is; `0` at the top level. */
+    depth: number;
+    /** The dispatch this child session belongs to, for event nesting; absent at the top level. */
+    dispatchId?: string;
+}
+/** The dispatch chain carried by a config, or an empty chain at the top level. */
+export declare function subWorkflowChain(configurable: Configurable): readonly string[];
+/** The dispatch id of the child session this config belongs to, if it is one. */
+export declare function subWorkflowDispatchId(configurable: Configurable): string | undefined;
+/**
+ * Variable seeds this invocation carries, layered **over** the assembly's own at
+ * the turn boundary. Absent for an ordinary turn.
+ */
+export declare function seedVariablesFrom(configurable: Configurable): Record<string, unknown> | undefined;
+/** Read the session scope from a config; a config with no `thread_id` is {@link DEFAULT_SESSION_ID}. */
+export declare function sessionScopeFrom(config: {
+    configurable?: Record<string, unknown>;
+} | undefined, fallbackSessionId?: string): SessionScope;
+/**
+ * Drop `sessionId`'s entry and every child session's entry from a session-keyed
+ * map. Disposal is requested per session, so it must reach the children nested
+ * under it or a delegating session leaks a REPL per dispatch. Returns the ids
+ * released, so a caller holding several parallel maps can release the same set.
+ */
+export declare function releaseScopes<V>(map: Map<string, V>, sessionId: string): string[];
+/**
+ * The child identity for one dispatch: `<state>:<workflow>:<ordinal>`. The
+ * ordinal keeps a second visit to the same state (an `on_error` loop, a retried
+ * turn) and concurrently dispatched children of one state apart.
+ */
+export declare function subRunIdentity(state: string, workflow: string, ordinal: number): string;
+/**
+ * The session id one child gets: `<parent>~<state>:<workflow>:<ordinal>` — an
+ * ordinary session with its own checkpoints and zone. Derived rather than minted
+ * at random, so a re-dispatch of the same call resolves to the same child and a
+ * resumed parent finds the child it parked on.
+ */
+export declare function childSessionId(parentSessionId: string, identity: string): string;
+/**
+ * The session that dispatched `sessionId`, or `undefined` for a top-level
+ * session. Derived from the id, so there is no index to drift.
+ */
+export declare function parentSessionIdOf(sessionId: string): string | undefined;
+/** Whether `sessionId` is a session dispatched by `parentSessionId`, at any depth. */
+export declare function isChildSessionOf(sessionId: string, parentSessionId: string): boolean;
+/**
+ * The config a child session is invoked with: its **own** `thread_id` (see
+ * {@link childSessionId}), the extended dispatch chain and the dispatch id.
+ * `checkpoint_id` and `checkpoint_ns` are cleared: each pins a position in the
+ * *caller's* thread, which the child's thread has never written.
+ */
+export declare function childRunConfig(parentConfig: RunnableConfig, child: {
+    identity: string;
+    workflow: string;
+    dispatchId: string;
+}): RunnableConfig;
+export {};

package/dist/sessions/scope.js

@@ -0,0 +1,145 @@
+/** The session id assumed when a config carries no `thread_id`; every per-session map keys on this spelling. */
+export const DEFAULT_SESSION_ID = "__default__";
+/**
+ * Where the dispatch chain of workflow slugs rides between a parent session and
+ * its child; what makes depth and cycle refusals possible without a shared registry.
+ */
+export const SUB_WORKFLOW_CHAIN_KEY = "archmax_sub_workflow_chain";
+/** Where a child session's dispatch id rides, so events emitted inside it can be nested. */
+export const SUB_WORKFLOW_DISPATCH_KEY = "archmax_sub_workflow_dispatch";
+/**
+ * Where the slug of the state a **script's** tool call is made from rides. The
+ * PTC gateway is refreshed with the state in force on every model call and hands
+ * the tool only a `RunnableConfig`; an agent-initiated delegation never needs it.
+ */
+export const CALLING_STATE_KEY = "archmax_calling_state";
+/** The state a script's call is made from, read from its config. */
+export function callingStateFrom(config) {
+    const slug = config?.configurable?.[CALLING_STATE_KEY];
+    return typeof slug === "string" && slug ? slug : undefined;
+}
+/**
+ * Where **per-invocation** variable seeds ride. A child's seeds differ per
+ * dispatch while the composed child is shared, and the graph input cannot carry
+ * them (the turn boundary rewrites the `variables` channel); the config is the
+ * one per-invocation, never-checkpointed channel.
+ */
+export const SEED_VARIABLES_KEY = "archmax_seed_variables";
+/** The dispatch chain carried by a config, or an empty chain at the top level. */
+export function subWorkflowChain(configurable) {
+    const chain = configurable?.[SUB_WORKFLOW_CHAIN_KEY];
+    return Array.isArray(chain) ? chain : [];
+}
+/** The dispatch id of the child session this config belongs to, if it is one. */
+export function subWorkflowDispatchId(configurable) {
+    const id = configurable?.[SUB_WORKFLOW_DISPATCH_KEY];
+    return typeof id === "string" && id !== "" ? id : undefined;
+}
+/**
+ * Variable seeds this invocation carries, layered **over** the assembly's own at
+ * the turn boundary. Absent for an ordinary turn.
+ */
+export function seedVariablesFrom(configurable) {
+    const seeds = configurable?.[SEED_VARIABLES_KEY];
+    return seeds && typeof seeds === "object" && !Array.isArray(seeds)
+        ? seeds
+        : undefined;
+}
+/** Read the session scope from a config; a config with no `thread_id` is {@link DEFAULT_SESSION_ID}. */
+export function sessionScopeFrom(config, fallbackSessionId = DEFAULT_SESSION_ID) {
+    const configurable = config?.configurable;
+    const sessionId = configurable?.thread_id ?? fallbackSessionId;
+    const chain = subWorkflowChain(configurable);
+    const dispatchId = subWorkflowDispatchId(configurable);
+    return {
+        sessionId,
+        chain,
+        depth: chain.length,
+        ...(dispatchId ? { dispatchId } : {}),
+    };
+}
+/**
+ * Drop `sessionId`'s entry and every child session's entry from a session-keyed
+ * map. Disposal is requested per session, so it must reach the children nested
+ * under it or a delegating session leaks a REPL per dispatch. Returns the ids
+ * released, so a caller holding several parallel maps can release the same set.
+ */
+export function releaseScopes(map, sessionId) {
+    const released = [];
+    for (const key of map.keys()) {
+        if (key === sessionId || isChildSessionOf(key, sessionId))
+            released.push(key);
+    }
+    for (const key of released)
+        map.delete(key);
+    return released;
+}
+/**
+ * The child identity for one dispatch: `<state>:<workflow>:<ordinal>`. The
+ * ordinal keeps a second visit to the same state (an `on_error` loop, a retried
+ * turn) and concurrently dispatched children of one state apart.
+ */
+export function subRunIdentity(state, workflow, ordinal) {
+    return `${state}:${workflow}:${ordinal}`;
+}
+/**
+ * Separator between a parent's session id and a child's dispatch identity. A
+ * session id becomes a directory name in the filesystem store, so it must be
+ * legal on every platform: `~` is, LangGraph's `|` is not.
+ */
+const CHILD_SESSION_SEPARATOR = "~";
+/**
+ * The session id one child gets: `<parent>~<state>:<workflow>:<ordinal>` — an
+ * ordinary session with its own checkpoints and zone. Derived rather than minted
+ * at random, so a re-dispatch of the same call resolves to the same child and a
+ * resumed parent finds the child it parked on.
+ */
+export function childSessionId(parentSessionId, identity) {
+    return `${parentSessionId}${CHILD_SESSION_SEPARATOR}${identity}`;
+}
+/**
+ * The shape a dispatch identity takes: `<state>:<workflow>:<ordinal>`. Matched
+ * rather than assumed, so a host id like `tenant~conversation` is not read as a
+ * child of `tenant` (and disposed with it); only ids this module minted count.
+ */
+const CHILD_IDENTITY = /^[^~:]+:[^~:]+:\d+$/;
+/**
+ * The session that dispatched `sessionId`, or `undefined` for a top-level
+ * session. Derived from the id, so there is no index to drift.
+ */
+export function parentSessionIdOf(sessionId) {
+    const at = sessionId.lastIndexOf(CHILD_SESSION_SEPARATOR);
+    if (at <= 0)
+        return undefined;
+    return CHILD_IDENTITY.test(sessionId.slice(at + 1)) ? sessionId.slice(0, at) : undefined;
+}
+/** Whether `sessionId` is a session dispatched by `parentSessionId`, at any depth. */
+export function isChildSessionOf(sessionId, parentSessionId) {
+    if (!sessionId.startsWith(`${parentSessionId}${CHILD_SESSION_SEPARATOR}`))
+        return false;
+    const descent = sessionId.slice(parentSessionId.length + 1).split(CHILD_SESSION_SEPARATOR);
+    return descent.every((segment) => CHILD_IDENTITY.test(segment));
+}
+/**
+ * The config a child session is invoked with: its **own** `thread_id` (see
+ * {@link childSessionId}), the extended dispatch chain and the dispatch id.
+ * `checkpoint_id` and `checkpoint_ns` are cleared: each pins a position in the
+ * *caller's* thread, which the child's thread has never written.
+ */
+export function childRunConfig(parentConfig, child) {
+    const configurable = { ...(parentConfig.configurable ?? {}) };
+    delete configurable.checkpoint_id;
+    delete configurable.checkpoint_ns;
+    const parentScope = sessionScopeFrom(parentConfig, "");
+    const parentSessionId = configurable.thread_id ?? "";
+    return {
+        ...parentConfig,
+        configurable: {
+            ...configurable,
+            thread_id: childSessionId(parentSessionId, child.identity),
+            [SUB_WORKFLOW_CHAIN_KEY]: [...parentScope.chain, child.workflow],
+            [SUB_WORKFLOW_DISPATCH_KEY]: child.dispatchId,
+        },
+    };
+}
+//# sourceMappingURL=scope.js.map

package/dist/sessions/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/sessions/scope.ts"],"names":[],"mappings":"AASA,gHAAgH;AAChH,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAEnE,4FAA4F;AAC5F,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC;AAEzD,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,MAAuC;IACtE,MAAM,IAAI,GAAG,MAAM,EAAE,YAAY,EAAE,CAAC,iBAAiB,CAAC,CAAC;IACvD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;AAiB3D,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,YAA0B;IACzD,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC,sBAAsB,CAAC,CAAC;IACrD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CAAC,YAA0B;IAC9D,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC,yBAAyB,CAAC,CAAC;IACrD,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAA0B;IAC1D,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC,kBAAkB,CAAC,CAAC;IACjD,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAChE,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,gBAAgB,CAC9B,MAA8D,EAC9D,oBAA4B,kBAAkB;IAE9C,MAAM,YAAY,GAAG,MAAM,EAAE,YAAY,CAAC;IAC1C,MAAM,SAAS,GAAI,YAAY,EAAE,SAAgC,IAAI,iBAAiB,CAAC;IACvF,MAAM,KAAK,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACvD,OAAO;QACL,SAAS;QACT,KAAK;QACL,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAI,GAAmB,EAAE,SAAiB;IACrE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7B,IAAI,GAAG,KAAK,SAAS,IAAI,gBAAgB,CAAC,GAAG,EAAE,SAAS,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChF,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,QAAQ;QAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,QAAgB,EAAE,OAAe;IAC7E,OAAO,GAAG,KAAK,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,eAAuB,EAAE,QAAgB;IACtE,OAAO,GAAG,eAAe,GAAG,uBAAuB,GAAG,QAAQ,EAAE,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,EAAE,GAAG,SAAS,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;IAC1D,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9B,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3F,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,eAAuB;IACzE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,eAAe,GAAG,uBAAuB,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IACxF,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3F,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,YAA4B,EAC5B,KAAiE;IAEjE,MAAM,YAAY,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,YAAY,IAAI,EAAE,CAAC,EAAE,CAAC;IAC9D,OAAO,YAAY,CAAC,aAAa,CAAC;IAClC,OAAO,YAAY,CAAC,aAAa,CAAC;IAClC,MAAM,WAAW,GAAG,gBAAgB,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IACvD,MAAM,eAAe,GAAI,YAAY,CAAC,SAAgC,IAAI,EAAE,CAAC;IAC7E,OAAO;QACL,GAAG,YAAY;QACf,YAAY,EAAE;YACZ,GAAG,YAAY;YACf,SAAS,EAAE,cAAc,CAAC,eAAe,EAAE,KAAK,CAAC,QAAQ,CAAC;YAC1D,CAAC,sBAAsB,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;YAChE,CAAC,yBAAyB,CAAC,EAAE,KAAK,CAAC,UAAU;SAC9C;KACF,CAAC;AACJ,CAAC"}

package/dist/sessions/summary.d.ts

@@ -0,0 +1,65 @@
+/**
+ * One session's projection, read by key from its latest checkpoint — and the
+ * listing built from it. A reading of checkpointed state rather than part of the
+ * saver, so it works for any `BaseCheckpointSaver`, an in-memory one included.
+ */
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+import { type UsageSummary } from "../core/usage.js";
+import type { Workspace } from "../core/workspace.js";
+import type { VariableStore } from "../machine/variables.js";
+import { type SessionClassification, type WorkflowStatus } from "../workflow/state.js";
+/** Coarse projection of a durable session, derived from its latest checkpoint. */
+export interface SessionSummary {
+    /** The conversation this summary describes — the only id there is. */
+    sessionId: string;
+    status?: WorkflowStatus;
+    /** Which side of the open/finished partition {@link status} falls on — a parked session is open, never finished. */
+    classification?: SessionClassification;
+    /** The state the session currently occupies — where its next turn continues. */
+    workflowState?: string;
+    /** The definition the session's latest turn ran under (metadata, never a guard). */
+    specHash?: string;
+    /** For parked sessions, the state awaiting a human decision or an external event. */
+    state?: string;
+    /** @deprecated Older spelling of {@link state}; kept for one release. */
+    node?: string;
+    /**
+     * For a session the agent parked with `archmax_wait`, its own stated reason. A
+     * park declares no awaited trigger ids (any firing resumes it), so this is
+     * what a surface shows instead.
+     */
+    waitReason?: string;
+    /**
+     * When such a park asked to be resumed (absolute), when it declared an `until`.
+     * A host's scheduler is a query over this listing; the runtime schedules nothing.
+     */
+    resumeAt?: string;
+    /**
+     * The session's variables as the checkpoint holds them — `name → { value, locked }`,
+     * omitted when the session has none. `locked` marks a host-established entry;
+     * an unlocked one came from the agent's own `archmax_set_variables`.
+     */
+    variables?: VariableStore;
+    /**
+     * What the session has cost so far: cumulative token counts, plus `costUsd`
+     * when pricing is configured; omitted when nothing has been spent. Read from
+     * the checkpoint, so a session resumed in another process reports the whole.
+     */
+    usage?: UsageSummary;
+    /** The session that dispatched this one, when it is a child session (see `isChildSessionOf`). */
+    parentSessionId?: string;
+}
+/**
+ * Project a session's latest checkpoint into a {@link SessionSummary} using only
+ * `getTuple`, so it works for **any** `BaseCheckpointSaver`. Session resolution
+ * depends on this answer being real: `null` means "this session has not run yet".
+ */
+export declare function summarizeCheckpointedSession(checkpointer: BaseCheckpointSaver, sessionId: string): Promise<SessionSummary | null>;
+/**
+ * Enumerate durable sessions by listing the session store's root (one
+ * `<sessionId>/` folder per session) and projecting each latest checkpoint.
+ * Runs outside any bound session, so the listing is the raw store root: reserved
+ * root names (authored mounts, `_specs/`, session areas) and sessions without a
+ * readable checkpoint are skipped.
+ */
+export declare function listSessions(workspace: Workspace, checkpointer: BaseCheckpointSaver): Promise<SessionSummary[]>;