@stigmer/runner 3.0.1

package/dist/shared/skill-relevance.js

@@ -0,0 +1,175 @@
+/**
+ * Skill relevance scoring for smart context filtering.
+ *
+ * Uses a BM25-inspired algorithm to score each skill's relevance
+ * against the user message. When an agent has many skills configured,
+ * low-relevance skills are excluded from the system prompt to improve
+ * signal quality.
+ *
+ * The progressive disclosure model means only skill metadata
+ * (~50-70 tokens per skill) lives in the prompt, so filtering
+ * primarily reduces noise rather than saving tokens.
+ *
+ * BM25 (Best Matching 25) is a lightweight, well-understood ranking
+ * function from information retrieval. It uses term frequency saturation
+ * and document length normalisation — both important when matching a
+ * short user message (query) against short skill metadata (documents of
+ * 5-20 tokens each).
+ *
+ * No external dependencies required.
+ */
+/** Relevance filtering activates only when the agent has at least this many skills. */
+export const SKILL_COUNT_THRESHOLD = 8;
+/** Term-frequency saturation. Higher values weight repeated terms more. */
+const BM25_K1 = 1.5;
+/** Length normalisation. 0 = none, 1 = full relative to average doc length. */
+const BM25_B = 0.75;
+const STOP_WORDS = new Set([
+    "a", "an", "the", "is", "are", "was", "were", "be", "been",
+    "being", "have", "has", "had", "do", "does", "did", "will",
+    "would", "could", "should", "may", "might", "shall", "can",
+    "to", "of", "in", "for", "on", "with", "at", "by", "from",
+    "as", "into", "through", "during", "before", "after", "above",
+    "below", "between", "and", "but", "or", "nor", "not", "so",
+    "yet", "both", "either", "neither", "each", "every", "all",
+    "any", "few", "more", "most", "some", "such", "no", "only",
+    "own", "same", "than", "too", "very", "just", "because",
+    "about", "up", "out", "if", "then", "that", "this", "these",
+    "those", "it", "its", "i", "me", "my", "we", "our", "you",
+    "your", "he", "she", "they", "them", "their", "what", "which",
+    "who", "whom", "how", "when", "where", "why",
+]);
+const TOKEN_PATTERN = /[a-z0-9]+/g;
+// ─── Tokenisation ────────────────────────────────────────────────────────
+/**
+ * Split text into lowercase tokens, dropping stop words and
+ * single-character fragments.
+ */
+export function tokenize(text) {
+    const matches = text.toLowerCase().match(TOKEN_PATTERN);
+    if (!matches)
+        return [];
+    return matches.filter(tok => !STOP_WORDS.has(tok) && tok.length > 1);
+}
+// ─── BM25 scoring ────────────────────────────────────────────────────────
+/**
+ * Score each skill's relevance to the user message using BM25.
+ *
+ * Each skill's name and description are concatenated into a document
+ * and scored against the query terms extracted from the user message.
+ *
+ * Returns ScoredSkill list ordered by descending score (ties broken alphabetically).
+ */
+export function scoreSkills(userMessage, skillNames, skillDescriptions, options) {
+    const k1 = options?.k1 ?? BM25_K1;
+    const b = options?.b ?? BM25_B;
+    const queryTerms = tokenize(userMessage);
+    const n = skillNames.length;
+    if (n === 0)
+        return [];
+    if (queryTerms.length === 0) {
+        return skillNames.map((name, index) => ({ index, name, score: 0.0 }));
+    }
+    // Build per-skill term-frequency maps.
+    const docs = [];
+    const docLengths = [];
+    for (let i = 0; i < n; i++) {
+        const tokens = tokenize(`${skillNames[i]} ${skillDescriptions[i]}`);
+        const tf = new Map();
+        for (const tok of tokens) {
+            tf.set(tok, (tf.get(tok) ?? 0) + 1);
+        }
+        docs.push(tf);
+        docLengths.push(tokens.length);
+    }
+    const avgdl = docLengths.reduce((sum, l) => sum + l, 0) / n;
+    // IDF per unique query term.
+    const uniqueQueryTerms = new Set(queryTerms);
+    const idf = new Map();
+    for (const term of uniqueQueryTerms) {
+        let df = 0;
+        for (const doc of docs) {
+            if (doc.has(term))
+                df++;
+        }
+        idf.set(term, Math.max(0.0, Math.log((n - df + 0.5) / (df + 0.5) + 1.0)));
+    }
+    // Score each document.
+    const results = [];
+    for (let i = 0; i < n; i++) {
+        const docTf = docs[i];
+        const dl = docLengths[i];
+        let score = 0.0;
+        for (const term of queryTerms) {
+            const tfVal = docTf.get(term);
+            if (tfVal === undefined)
+                continue;
+            const numerator = tfVal * (k1 + 1);
+            const denominator = tfVal + k1 * (1 - b + b * dl / avgdl);
+            score += (idf.get(term) ?? 0.0) * numerator / denominator;
+        }
+        results.push({ index: i, name: skillNames[i], score });
+    }
+    results.sort((a, b_) => {
+        if (b_.score !== a.score)
+            return b_.score - a.score;
+        return a.name.localeCompare(b_.name);
+    });
+    return results;
+}
+// ─── Filtering ───────────────────────────────────────────────────────────
+/**
+ * Partition skills into included / excluded based on relevance.
+ *
+ * Below the threshold, every skill is included unconditionally.
+ * Above the threshold, skills whose BM25 score is zero (no query
+ * term overlap at all) are moved to the excluded set.
+ *
+ * A safety floor guarantees that at least half the skills are
+ * always included, regardless of scores.
+ */
+export function filterSkills(userMessage, skillNames, skillDescriptions, options) {
+    const threshold = options?.threshold ?? SKILL_COUNT_THRESHOLD;
+    const n = skillNames.length;
+    const allIndices = Array.from({ length: n }, (_, i) => i);
+    if (n < threshold) {
+        return {
+            includedIndices: allIndices,
+            excludedIndices: [],
+            excludedNames: [],
+        };
+    }
+    const scored = scoreSkills(userMessage, skillNames, skillDescriptions);
+    const included = [];
+    const excluded = [];
+    const excludedNames = [];
+    for (const s of scored) {
+        if (s.score > 0.0) {
+            included.push(s.index);
+        }
+        else {
+            excluded.push(s.index);
+            excludedNames.push(s.name);
+        }
+    }
+    // Safety: always keep at least half the skills.
+    const minIncluded = Math.max(1, Math.floor(n / 2));
+    if (included.length < minIncluded) {
+        const deficit = minIncluded - included.length;
+        const reInclude = excluded.splice(0, deficit);
+        included.push(...reInclude);
+        for (const idx of reInclude) {
+            const nameIdx = excludedNames.indexOf(skillNames[idx]);
+            if (nameIdx !== -1)
+                excludedNames.splice(nameIdx, 1);
+        }
+    }
+    included.sort((a, b) => a - b);
+    excluded.sort((a, b) => a - b);
+    return {
+        includedIndices: included,
+        excludedIndices: excluded,
+        excludedNames: excludedNames.sort(),
+    };
+}
+//# sourceMappingURL=skill-relevance.js.map

package/dist/shared/skill-relevance.js.map

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

package/dist/shared/skill-writer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Skill writing and prompt generation for the deep-agent execution path.
+ *
+ * Follows the Agent Skills specification progressive disclosure model:
+ *
+ * 1. Metadata (startup) — skill name + description injected into
+ *    the system prompt so the agent knows which skills are available.
+ * 2. Instructions (activation) — the agent reads SKILL.md from the
+ *    filesystem when it decides to activate a skill.
+ * 3. Resources (on demand) — scripts, references, and assets are
+ *    loaded by the agent only when required.
+ *
+ * Skills live under `.stigmer/skills/{name}/` relative to the workspace root.
+ * Returned paths are workspace-relative so that the agent's sandbox backend
+ * resolves them correctly regardless of mount strategy.
+ */
+import type { WorkspaceBackend } from "./workspace/types.js";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+export interface SkillPathMap {
+    /** Map from skill metadata ID to workspace-relative directory path. */
+    readonly paths: ReadonlyMap<string, string>;
+}
+/**
+ * Merge skill refs from agent and session specs (union, dedup by slug,
+ * session wins on collision).
+ */
+export declare function mergeSkillRefs(agentRefs: readonly ApiResourceReference[], sessionRefs: readonly ApiResourceReference[]): ApiResourceReference[];
+/**
+ * Fetch all skills by their ApiResourceReference. Failures for individual
+ * skills are logged and skipped (non-fatal).
+ */
+export declare function fetchSkillsByRefs(client: StigmerClient, refs: readonly ApiResourceReference[]): Promise<Skill[]>;
+/**
+ * Write skill artifacts to the workspace. Returns a map of
+ * skill-id -> workspace-relative directory path.
+ *
+ * For each skill:
+ * - If a ZIP artifact is available, extract it to .stigmer/skills/{name}/
+ * - Otherwise, write just the SKILL.md from the spec
+ * - Make scripts executable
+ */
+export declare function writeSkills(skills: readonly Skill[], workspaceBackend: WorkspaceBackend, artifacts: ReadonlyMap<string, Uint8Array>): Promise<SkillPathMap>;
+/**
+ * Compute skill paths without writing anything (for resume integrity checks).
+ */
+export declare function computeSkillPaths(skills: readonly Skill[]): Map<string, string>;
+/**
+ * Check workspace integrity for resume fast-path.
+ * Returns true if the sentinel SKILL.md file exists for the first skill.
+ */
+export declare function checkSkillIntegrity(skills: readonly Skill[], workspaceBackend: WorkspaceBackend): Promise<boolean>;
+/**
+ * Generate the system prompt section following the Agent Skills spec
+ * progressive disclosure model.
+ *
+ * Only metadata (name + description + location) is injected. The agent
+ * reads SKILL.md on demand via filesystem tools.
+ */
+export declare function generatePromptSection(skills: readonly Skill[], skillPaths: ReadonlyMap<string, string>): string;
+/**
+ * Generate a brief note listing skills excluded by relevance filtering.
+ *
+ * The agent can still request these skills by name if it determines
+ * they are needed mid-conversation.
+ */
+export declare function generateAlsoAvailableSection(excludedNames: readonly string[]): string;
+/**
+ * Download skill artifacts for all skills that have a storage key.
+ * Returns a map from skill ID to artifact bytes.
+ */
+export declare function fetchSkillArtifacts(client: StigmerClient, skills: readonly Skill[]): Promise<Map<string, Uint8Array>>;

package/dist/shared/skill-writer.js

@@ -0,0 +1,230 @@
+/**
+ * Skill writing and prompt generation for the deep-agent execution path.
+ *
+ * Follows the Agent Skills specification progressive disclosure model:
+ *
+ * 1. Metadata (startup) — skill name + description injected into
+ *    the system prompt so the agent knows which skills are available.
+ * 2. Instructions (activation) — the agent reads SKILL.md from the
+ *    filesystem when it decides to activate a skill.
+ * 3. Resources (on demand) — scripts, references, and assets are
+ *    loaded by the agent only when required.
+ *
+ * Skills live under `.stigmer/skills/{name}/` relative to the workspace root.
+ * Returned paths are workspace-relative so that the agent's sandbox backend
+ * resolves them correctly regardless of mount strategy.
+ */
+import { extractZipFileEntries } from "./zip-extract.js";
+const SKILLS_RELATIVE_BASE = ".stigmer/skills";
+const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+// ─── Fetch ───────────────────────────────────────────────────────────────
+/**
+ * Merge skill refs from agent and session specs (union, dedup by slug,
+ * session wins on collision).
+ */
+export function mergeSkillRefs(agentRefs, sessionRefs) {
+    const bySlug = new Map();
+    for (const ref of agentRefs) {
+        if (ref.slug)
+            bySlug.set(ref.slug, ref);
+    }
+    for (const ref of sessionRefs) {
+        if (ref.slug)
+            bySlug.set(ref.slug, ref);
+    }
+    return [...bySlug.values()];
+}
+/**
+ * Fetch all skills by their ApiResourceReference. Failures for individual
+ * skills are logged and skipped (non-fatal).
+ */
+export async function fetchSkillsByRefs(client, refs) {
+    if (refs.length === 0)
+        return [];
+    const results = [];
+    const fetches = refs.map(async (ref) => {
+        try {
+            return await client.getSkillByReference(ref);
+        }
+        catch (err) {
+            console.warn(`[skill-writer] Failed to fetch skill ${ref.org}/${ref.slug}: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    });
+    const settled = await Promise.all(fetches);
+    for (const skill of settled) {
+        if (skill)
+            results.push(skill);
+    }
+    return results;
+}
+// ─── Write ───────────────────────────────────────────────────────────────
+/**
+ * Write skill artifacts to the workspace. Returns a map of
+ * skill-id -> workspace-relative directory path.
+ *
+ * For each skill:
+ * - If a ZIP artifact is available, extract it to .stigmer/skills/{name}/
+ * - Otherwise, write just the SKILL.md from the spec
+ * - Make scripts executable
+ */
+export async function writeSkills(skills, workspaceBackend, artifacts) {
+    const paths = new Map();
+    for (const skill of skills) {
+        const name = skill.spec?.name || skill.metadata?.slug || "unknown";
+        const skillId = skill.metadata?.id ?? name;
+        const relativeDir = `${SKILLS_RELATIVE_BASE}/${name}`;
+        paths.set(skillId, relativeDir);
+        const artifactBytes = artifacts.get(skillId);
+        if (skill.spec?.skillMd) {
+            const skillMdPath = `${relativeDir}/SKILL.md`;
+            await workspaceBackend.writeFile(skillMdPath, skill.spec.skillMd);
+            if (artifactBytes && artifactBytes.length > 0) {
+                await extractZipToWorkspaceExcluding(artifactBytes, "SKILL.md", relativeDir, workspaceBackend);
+            }
+        }
+        else if (artifactBytes && artifactBytes.length > 0) {
+            await extractZipToWorkspace(artifactBytes, relativeDir, workspaceBackend);
+        }
+        await makeScriptsExecutable(relativeDir, workspaceBackend);
+    }
+    return { paths };
+}
+/**
+ * Compute skill paths without writing anything (for resume integrity checks).
+ */
+export function computeSkillPaths(skills) {
+    const paths = new Map();
+    for (const skill of skills) {
+        const name = skill.spec?.name || skill.metadata?.slug || "unknown";
+        const skillId = skill.metadata?.id ?? name;
+        paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
+    }
+    return paths;
+}
+/**
+ * Check workspace integrity for resume fast-path.
+ * Returns true if the sentinel SKILL.md file exists for the first skill.
+ */
+export async function checkSkillIntegrity(skills, workspaceBackend) {
+    if (skills.length === 0)
+        return true;
+    const paths = computeSkillPaths(skills);
+    const firstPath = paths.values().next().value;
+    if (!firstPath)
+        return true;
+    const sentinel = `${firstPath}/SKILL.md`;
+    return workspaceBackend.exists(sentinel);
+}
+// ─── ZIP extraction ──────────────────────────────────────────────────────
+async function extractZipToWorkspace(zipBytes, targetDir, backend) {
+    const entries = await extractZipFileEntries(zipBytes);
+    for (const entry of entries) {
+        await backend.writeFile(`${targetDir}/${entry.path}`, entry.content);
+    }
+}
+async function extractZipToWorkspaceExcluding(zipBytes, excludeName, targetDir, backend) {
+    const entries = await extractZipFileEntries(zipBytes, { exclude: [excludeName] });
+    for (const entry of entries) {
+        await backend.writeFile(`${targetDir}/${entry.path}`, entry.content);
+    }
+}
+async function makeScriptsExecutable(relativeDir, backend) {
+    const extensions = [...SCRIPT_EXTENSIONS].map(ext => `-name '*${ext}'`).join(" -o ");
+    const cmd = `find ${relativeDir} -type f \\( ${extensions} \\) -exec chmod +x {} \\; 2>/dev/null || true`;
+    try {
+        await backend.execute(cmd);
+    }
+    catch {
+        // Non-fatal: scripts may not be executable in all environments
+    }
+}
+// ─── Prompt generation ───────────────────────────────────────────────────
+/**
+ * Generate the system prompt section following the Agent Skills spec
+ * progressive disclosure model.
+ *
+ * Only metadata (name + description + location) is injected. The agent
+ * reads SKILL.md on demand via filesystem tools.
+ */
+export function generatePromptSection(skills, skillPaths) {
+    if (skills.length === 0)
+        return "";
+    const lines = [
+        "",
+        "",
+        "## Skills",
+        "",
+        "You have access to the following skills. Each skill provides specialized " +
+            "knowledge or capabilities.",
+        "",
+        "**Activation protocol**: To use a skill, read its SKILL.md file " +
+            "using the `read` tool. The SKILL.md contains detailed instructions, " +
+            "available tools, and usage examples.",
+        "",
+        "**Usage pattern**:",
+        "",
+        "1. Review the skill description below to determine relevance",
+        "2. Read `{location}/SKILL.md` for full instructions",
+        "3. Follow the skill's documented operations:",
+        "",
+        "`read {location}/references/schema.md`",
+        '`execute("python3 {location}/scripts/run.py")`',
+        "",
+    ];
+    for (const skill of skills) {
+        const name = skill.spec?.name || skill.metadata?.slug || "unknown";
+        const skillId = skill.metadata?.id ?? name;
+        const skillDir = skillPaths.get(skillId) ?? `${SKILLS_RELATIVE_BASE}/${name}`;
+        const description = skill.spec?.description || "(no description)";
+        lines.push(`### ${name}`);
+        lines.push(`**Description**: ${description}`);
+        lines.push(`**Location**: \`${skillDir}/\``);
+        lines.push(`**Activate**: \`read ${skillDir}/SKILL.md\``);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Generate a brief note listing skills excluded by relevance filtering.
+ *
+ * The agent can still request these skills by name if it determines
+ * they are needed mid-conversation.
+ */
+export function generateAlsoAvailableSection(excludedNames) {
+    if (excludedNames.length === 0)
+        return "";
+    const namesStr = excludedNames.map(n => `\`${n}\``).join(", ");
+    return ("\n### Also Available\n\n" +
+        `These skills are installed but were not highlighted above: ${namesStr}. ` +
+        "If you determine one of them is relevant to your task, " +
+        "read its SKILL.md at `.stigmer/skills/<name>/SKILL.md` to activate it.\n");
+}
+// ─── Artifact fetching ───────────────────────────────────────────────────
+/**
+ * Download skill artifacts for all skills that have a storage key.
+ * Returns a map from skill ID to artifact bytes.
+ */
+export async function fetchSkillArtifacts(client, skills) {
+    const artifacts = new Map();
+    const fetches = skills
+        .filter(s => s.status?.artifactStorageKey)
+        .map(async (skill) => {
+        const key = skill.status.artifactStorageKey;
+        const skillId = skill.metadata?.id ?? skill.spec?.name ?? "unknown";
+        try {
+            const response = await client.getSkillArtifact(key);
+            if (response.artifact && response.artifact.length > 0) {
+                artifacts.set(skillId, response.artifact);
+            }
+        }
+        catch (err) {
+            console.warn(`[skill-writer] Failed to download artifact for ${skill.spec?.name}: ` +
+                `${err instanceof Error ? err.message : String(err)}. Falling back to SKILL.md only.`);
+        }
+    });
+    await Promise.all(fetches);
+    return artifacts;
+}
+//# sourceMappingURL=skill-writer.js.map

package/dist/shared/skill-writer.js.map

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

package/dist/shared/status.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared status persistence utilities for all runner activities.
+ *
+ * Both ExecuteCursor and ExecuteDeepAgent need to persist execution status
+ * via gRPC, report setup progress phases, produce slim status payloads for
+ * Temporal return values, and generate UTC timestamps. These thin utilities
+ * are harness-agnostic — they operate on the common AgentExecutionStatus
+ * proto without knowledge of Cursor SDK or LangGraph event shapes.
+ */
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+export declare function utcTimestamp(): string;
+/**
+ * Persist execution status via gRPC. Returns the control signal from the
+ * backend (e.g. STOP to abort the execution). Errors are logged and
+ * swallowed — a failed status update should not crash the activity.
+ */
+export declare function persistStatus(client: StigmerClient, executionId: string, status: AgentExecutionStatus): Promise<ExecutionControlSignal>;
+/**
+ * Report a setup progress phase (e.g. "Resolving MCP servers") so the
+ * frontend can display a spinner with context.
+ */
+export declare function reportSetupProgress(client: StigmerClient, executionId: string, phase: string): Promise<void>;
+/**
+ * Strip heavy fields from a full status, keeping only workflow-critical
+ * data for the Temporal return value. Messages and tool calls are already
+ * persisted via gRPC — including them in the Temporal payload would
+ * exceed size limits and cause serialization issues with protobuf bytes.
+ *
+ * Uses toJson() to produce canonical protobuf JSON (base64 bytes, string
+ * enums, omitted defaults) instead of returning a raw @bufbuild/protobuf
+ * message. Temporal's default JsonPayloadConverter calls JSON.stringify,
+ * which serializes Uint8Array bytes fields as {} — invalid protobuf JSON
+ * that the Java workflow's JsonFormat.Parser rejects.
+ */
+export declare function slimStatus(full: AgentExecutionStatus): unknown;

package/dist/shared/status.js

@@ -0,0 +1,73 @@
+/**
+ * Shared status persistence utilities for all runner activities.
+ *
+ * Both ExecuteCursor and ExecuteDeepAgent need to persist execution status
+ * via gRPC, report setup progress phases, produce slim status payloads for
+ * Temporal return values, and generate UTC timestamps. These thin utilities
+ * are harness-agnostic — they operate on the common AgentExecutionStatus
+ * proto without knowledge of Cursor SDK or LangGraph event shapes.
+ */
+import { create, toJson } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema, SetupProgressSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionControlSignal, ExecutionPhase, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+export function utcTimestamp() {
+    return new Date().toISOString().replace("+00:00", "Z");
+}
+/**
+ * Persist execution status via gRPC. Returns the control signal from the
+ * backend (e.g. STOP to abort the execution). Errors are logged and
+ * swallowed — a failed status update should not crash the activity.
+ */
+export async function persistStatus(client, executionId, status) {
+    try {
+        const response = await client.updateStatus(executionId, status);
+        return response.signal;
+    }
+    catch (err) {
+        console.error(`Failed to persist status for ${executionId}:`, err);
+        return ExecutionControlSignal.UNSPECIFIED;
+    }
+}
+/**
+ * Report a setup progress phase (e.g. "Resolving MCP servers") so the
+ * frontend can display a spinner with context.
+ */
+export async function reportSetupProgress(client, executionId, phase) {
+    const status = create(AgentExecutionStatusSchema, {
+        phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+        setupProgress: create(SetupProgressSchema, { currentPhase: phase }),
+    });
+    await persistStatus(client, executionId, status);
+}
+/**
+ * Strip heavy fields from a full status, keeping only workflow-critical
+ * data for the Temporal return value. Messages and tool calls are already
+ * persisted via gRPC — including them in the Temporal payload would
+ * exceed size limits and cause serialization issues with protobuf bytes.
+ *
+ * Uses toJson() to produce canonical protobuf JSON (base64 bytes, string
+ * enums, omitted defaults) instead of returning a raw @bufbuild/protobuf
+ * message. Temporal's default JsonPayloadConverter calls JSON.stringify,
+ * which serializes Uint8Array bytes fields as {} — invalid protobuf JSON
+ * that the Java workflow's JsonFormat.Parser rejects.
+ */
+export function slimStatus(full) {
+    const slim = create(AgentExecutionStatusSchema, {
+        phase: full.phase,
+        error: full.error,
+        startedAt: full.startedAt,
+        completedAt: full.completedAt,
+        pendingApprovals: full.pendingApprovals,
+        structuredOutput: full.structuredOutput,
+    });
+    const json = toJson(AgentExecutionStatusSchema, slim);
+    if (full.structuredOutput) {
+        const jsonObj = json;
+        const hasField = "structuredOutput" in jsonObj;
+        console.log(`[slimStatus] structuredOutput serialization: ` +
+            `inputPresent=true, outputFieldPresent=${hasField}, ` +
+            `outputKeys=${Object.keys(jsonObj).join(",")}`);
+    }
+    return json;
+}
+//# sourceMappingURL=status.js.map

package/dist/shared/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/shared/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,6DAA6D,CAAC;AAErE,OAAO,EACL,sBAAsB,EACtB,cAAc,GACf,MAAM,8DAA8D,CAAC;AAGtE,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAqB,EACrB,WAAmB,EACnB,MAA4B;IAE5B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAChE,OAAO,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,gCAAgC,WAAW,GAAG,EAAE,GAAG,CAAC,CAAC;QACnE,OAAO,sBAAsB,CAAC,WAAW,CAAC;IAC5C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAqB,EACrB,WAAmB,EACnB,KAAa;IAEb,MAAM,MAAM,GAAG,MAAM,CAAC,0BAA0B,EAAE;QAChD,KAAK,EAAE,cAAc,CAAC,qBAAqB;QAC3C,aAAa,EAAE,MAAM,CAAC,mBAAmB,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;KACpE,CAAC,CAAC;IACH,MAAM,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,IAA0B;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,0BAA0B,EAAE;QAC9C,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;KACxC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,CAAC,0BAA0B,EAAE,IAAI,CAAC,CAAC;IACtD,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,IAA+B,CAAC;QAChD,MAAM,QAAQ,GAAG,kBAAkB,IAAI,OAAO,CAAC;QAC/C,OAAO,CAAC,GAAG,CACT,+CAA+C;YAC/C,yCAAyC,QAAQ,IAAI;YACrD,cAAc,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC/C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/shared/subagent-gate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Concurrency limiter for sub-agent execution.
+ *
+ * Wraps sub-agent runnables with a Promise-based semaphore that
+ * limits the number of concurrent sub-agent invocations. When the
+ * limit is reached, new invocations are rejected immediately with
+ * an error-shaped message (non-blocking) rather than queuing.
+ *
+ * This matches the Python `SubAgentGate` behavior: protect the
+ * parent agent's resources by hard-capping concurrency, and let
+ * the LLM adapt when a sub-agent cannot be started.
+ */
+import { RunnableLambda, type RunnableConfig } from "@langchain/core/runnables";
+export interface SubAgentGateOptions {
+    readonly maxConcurrent?: number;
+}
+export declare class SubAgentGate {
+    private readonly max;
+    private active;
+    constructor(options?: SubAgentGateOptions);
+    get activeCount(): number;
+    get maxConcurrent(): number;
+    get hasCapacity(): boolean;
+    /**
+     * Wrap a sub-agent's invoke function with concurrency gating.
+     *
+     * Returns a new function that checks capacity before invoking.
+     * If no capacity, returns an error-shaped response immediately.
+     */
+    wrap<TInput, TOutput>(invoke: (input: TInput, config?: Record<string, unknown>) => Promise<TOutput>, name: string): (input: TInput, config?: Record<string, unknown>) => Promise<TOutput>;
+    /**
+     * Wrap a sub-agent Runnable for use as `CompiledSubAgent.runnable`.
+     *
+     * Returns a `RunnableLambda` that checks capacity before delegating
+     * to the underlying runnable. When at capacity, returns an error-shaped
+     * response that deepagents surfaces to the parent agent as the task result.
+     */
+    wrapRunnable<TInput = Record<string, unknown>, TOutput = Record<string, unknown>>(runnable: {
+        invoke: (input: TInput, config?: RunnableConfig) => Promise<TOutput>;
+    }, name: string): RunnableLambda<TInput, TOutput>;
+}