contextos-mcp 0.4.0

package/dist/contextos/loader.js

@@ -0,0 +1,120 @@
+/** Assemble complete selected instructions with inspectable provenance and limits. */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { assertWithinRepository } from "../security/repository-boundary.js";
+import { selectContext } from "./selector.js";
+/** Soft compatibility budget; selected bodies are never sliced. */
+export const MAX_TOTAL_SKILLS_CHARS = 14000;
+export function findAgentsDir(projectRoot) {
+    const root = path.resolve(projectRoot);
+    if (path.basename(root) === ".agents" && existsSync(root))
+        return root;
+    for (const candidate of [path.join(root, ".agents"), path.join(root, "..", ".agents")]) {
+        if (existsSync(candidate))
+            return path.resolve(candidate);
+    }
+    return null;
+}
+export class ContextAssemblyError extends Error {
+    code;
+    report;
+    constructor(code, message, report) {
+        super(message);
+        this.code = code;
+        this.report = report;
+        this.name = "ContextAssemblyError";
+    }
+}
+export function assembleContextPrompt(projectRoot, task, options = {}) {
+    for (const limit of [options.maxTotalSkillsChars, options.hardLimitChars]) {
+        if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0))
+            throw new Error("Context character limits must be positive integers");
+    }
+    const report = {
+        sources: [],
+        warnings: [],
+        omissions: [],
+        totalChars: 0,
+        skillChars: 0,
+        estimatedTokens: 0,
+        softSkillLimitChars: options.maxTotalSkillsChars ?? MAX_TOTAL_SKILLS_CHARS,
+        hardLimitChars: options.hardLimitChars,
+    };
+    const agentsDir = findAgentsDir(projectRoot);
+    if (!agentsDir)
+        return { prompt: "", report };
+    const repositoryRoot = assertWithinRepository(path.dirname(agentsDir), path.dirname(agentsDir));
+    const selection = selectContext(task, { ...options, rootDir: repositoryRoot });
+    report.warnings.push(...(selection.warnings || []));
+    report.omissions.push(...(selection.excluded || []));
+    const sections = [];
+    function load(file, kind, id) {
+        const safePath = assertWithinRepository(file, repositoryRoot);
+        if (!existsSync(safePath))
+            throw new ContextAssemblyError("CTX_PROMPT_MISSING_SOURCE", `Selected ${kind} source is missing: ${id}`, report);
+        const bytes = readFileSync(safePath);
+        const content = bytes.toString("utf8");
+        report.sources.push({
+            kind,
+            id,
+            path: path.relative(repositoryRoot, safePath).replace(/\\/g, "/"),
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            bytes: bytes.length,
+            chars: content.length,
+        });
+        return content;
+    }
+    const bootstrap = path.join(agentsDir, "AGENTS.md");
+    if (existsSync(bootstrap))
+        sections.push(load(bootstrap, "bootstrap", "AGENTS.md").trim());
+    for (const rule of selection.rules)
+        sections.push(`# Rule: ${rule}\n\n${load(path.join(agentsDir, "rules", rule), "rule", rule)}`);
+    for (const id of [...new Set(selection.skills)]) {
+        const source = selection.skillSources?.[id];
+        const entrypoint = selection.skillEntrypoints?.[id] || "SKILL.md";
+        let directory;
+        if (source) {
+            const manifest = assertWithinRepository(path.resolve(repositoryRoot, source), repositoryRoot);
+            directory = path.dirname(manifest);
+        }
+        else {
+            // Compatibility with older selectors; overrides precede generated projections.
+            directory = ["project/skills", "core/skills", "plugins", "skills", "generated/gemini/skills"]
+                .map((base) => path.join(agentsDir, base, id))
+                .find((candidate) => existsSync(path.join(candidate, entrypoint)));
+        }
+        if (!directory)
+            throw new ContextAssemblyError("CTX_PROMPT_MISSING_SOURCE", `Selected skill source is missing: ${id}`, report);
+        const raw = load(path.join(directory, entrypoint), "skill", id);
+        const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim();
+        const relativeDirectory = path.relative(repositoryRoot, directory).replace(/\\/g, "/");
+        const formatted = `# Skill: ${id}\n\nResolve references relative to ${relativeDirectory}. Read them only when needed.\n\n${body}`;
+        report.skillChars += formatted.length;
+        sections.push(formatted);
+    }
+    const prompt = sections.length
+        ? [
+            "Follow these project instructions within the user's authorized task and the instruction hierarchy.",
+            ...sections,
+        ].join("\n\n")
+        : "";
+    report.totalChars = prompt.length;
+    report.estimatedTokens = Math.ceil(prompt.length / 4);
+    if (report.skillChars > report.softSkillLimitChars)
+        report.warnings.push({
+            code: "CTX_PROMPT_SOFT_BUDGET_EXCEEDED",
+            message: `Selected full skill bodies occupy ${report.skillChars} characters; soft limit is ${report.softSkillLimitChars}.`,
+        });
+    if (options.hardLimitChars !== undefined && prompt.length > options.hardLimitChars) {
+        throw new ContextAssemblyError("CTX_PROMPT_HARD_BUDGET_EXCEEDED", `Complete prompt needs ${prompt.length} characters; hard limit is ${options.hardLimitChars}.`, report);
+    }
+    for (const warning of report.warnings)
+        process.stderr.write(`[contextos-loader] ${warning.code}: ${warning.message}\n`);
+    return { prompt, report };
+}
+/** Compatibility wrapper for existing agent call sites. */
+export function buildContextPrompt(projectRoot, task, options = {}) {
+    return assembleContextPrompt(projectRoot, task, options).prompt;
+}
+//# sourceMappingURL=loader.js.map

package/dist/contextos/loader.js.map

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

package/dist/contextos/selector.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ContextOS Selector — determines which rules and skills are relevant for a task.
+ *
+ * Unified with CanonicalResolver (.agents/resolver/canonical-resolver.js) for 100%
+ * parity between CLI and MCP runtimes:
+ *   - Evidence-based scoring (aliases, keywords, file globs, nearest package)
+ *   - Direct query to compiled registry (registry.v2.json)
+ *   - Transitive dependency closure
+ *   - Token budget planner and intent precedence
+ */
+export interface SelectedContext {
+    /** Always-loaded rules (e.g., AGENTS.md core principles). */
+    coreRules: string[];
+    /** Task-relevant rule files from rules/. */
+    rules: string[];
+    /** Task-relevant skill directories from core/skills/. */
+    skills: string[];
+    skillSources?: Record<string, string>;
+    skillEntrypoints?: Record<string, string>;
+    warnings?: Array<{
+        code: string;
+        message: string;
+    }>;
+    excluded?: Array<{
+        id: string;
+        reasonCode: string;
+    }>;
+}
+export interface SelectorOptions {
+    /** Root directory of the repository. */
+    rootDir?: string;
+    /** File paths touched or relevant to task for file-pattern boosting. */
+    files?: string[];
+    /** Custom soft token budget; defaults to the canonical resolver risk tier. */
+    contextBudgetTokens?: number;
+    maxSkills?: number;
+    explicitPhase?: string;
+}
+/**
+ * Select relevant rules and skills for a given task description using the unified CanonicalResolver.
+ *
+ * @param task - The task description text
+ * @param options - Optional configuration (touched files and token budget)
+ * @returns SelectedContext with lists of relevant rule/skill identifiers
+ */
+export declare function selectContext(task: string, options?: SelectorOptions): SelectedContext;

package/dist/contextos/selector.js

@@ -0,0 +1,80 @@
+/**
+ * ContextOS Selector — determines which rules and skills are relevant for a task.
+ *
+ * Unified with CanonicalResolver (.agents/resolver/canonical-resolver.js) for 100%
+ * parity between CLI and MCP runtimes:
+ *   - Evidence-based scoring (aliases, keywords, file globs, nearest package)
+ *   - Direct query to compiled registry (registry.v2.json)
+ *   - Transitive dependency closure
+ *   - Token budget planner and intent precedence
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+const require = createRequire(import.meta.url);
+/**
+ * Lazily loads the canonical resolver instance from .agents.
+ */
+function getCanonicalResolver(rootDir) {
+    const cwd = rootDir || process.cwd();
+    const candidatePaths = [
+        path.join(cwd, ".agents", "resolver", "canonical-resolver.js"),
+        path.join(cwd, "..", ".agents", "resolver", "canonical-resolver.js"),
+    ];
+    for (const p of candidatePaths) {
+        if (existsSync(p)) {
+            try {
+                const mod = require(p);
+                if (mod?.CanonicalResolver) {
+                    const resolvedRoot = path.dirname(path.dirname(path.dirname(p)));
+                    return new mod.CanonicalResolver({ rootDir: resolvedRoot });
+                }
+            }
+            catch {
+                // fall through to fallback
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Select relevant rules and skills for a given task description using the unified CanonicalResolver.
+ *
+ * @param task - The task description text
+ * @param options - Optional configuration (touched files and token budget)
+ * @returns SelectedContext with lists of relevant rule/skill identifiers
+ */
+export function selectContext(task, options = {}) {
+    const canonical = getCanonicalResolver(options.rootDir);
+    if (!canonical) {
+        throw new Error("ContextOS CanonicalResolver is unavailable; refusing to produce incomplete context");
+    }
+    const res = canonical.resolve({
+        task,
+        files: options.files || [],
+        contextBudgetTokens: options.contextBudgetTokens,
+        maxSkills: options.maxSkills,
+        explicitPhase: options.explicitPhase,
+    });
+    const domainSkills = (res.selected || []).map((s) => s.id);
+    const skillSources = {};
+    const skillEntrypoints = {};
+    for (const id of domainSkills) {
+        const skill = canonical.registry?.skills?.[id];
+        const source = skill?.source;
+        if (source)
+            skillSources[id] = source;
+        if (skill?.entrypoint)
+            skillEntrypoints[id] = skill.entrypoint;
+    }
+    return {
+        coreRules: ["AGENTS.md"],
+        rules: [],
+        skills: domainSkills,
+        skillSources,
+        skillEntrypoints,
+        warnings: res.warnings || [],
+        excluded: res.excluded || [],
+    };
+}
+//# sourceMappingURL=selector.js.map

package/dist/contextos/selector.js.map

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

package/dist/core/action-dispatcher.d.ts

@@ -0,0 +1,15 @@
+import { type FinishAction, type InspectDiffAction, type MergeAction, type ReviewAction, type SpawnAction, type WaitAction } from "./action-schema.js";
+export interface ActionHandlers {
+    spawn(action: SpawnAction): Promise<unknown>;
+    wait(action: WaitAction): Promise<unknown>;
+    inspectDiff(action: InspectDiffAction): Promise<unknown>;
+    review(action: ReviewAction): Promise<unknown>;
+    merge(action: MergeAction): Promise<unknown>;
+    finish(action: FinishAction): Promise<unknown>;
+}
+export declare class ActionDispatcher {
+    private readonly handlers;
+    constructor(handlers: ActionHandlers);
+    dispatch(input: unknown): Promise<unknown>;
+    private dispatchValidated;
+}

package/dist/core/action-dispatcher.js

@@ -0,0 +1,28 @@
+import { parseAction, } from "./action-schema.js";
+export class ActionDispatcher {
+    handlers;
+    constructor(handlers) {
+        this.handlers = handlers;
+    }
+    async dispatch(input) {
+        const action = parseAction(input);
+        return this.dispatchValidated(action);
+    }
+    async dispatchValidated(action) {
+        switch (action.action) {
+            case "spawn":
+                return this.handlers.spawn(action);
+            case "wait":
+                return this.handlers.wait(action);
+            case "inspect_diff":
+                return this.handlers.inspectDiff(action);
+            case "review":
+                return this.handlers.review(action);
+            case "merge":
+                return this.handlers.merge(action);
+            case "finish":
+                return this.handlers.finish(action);
+        }
+    }
+}
+//# sourceMappingURL=action-dispatcher.js.map

package/dist/core/action-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-dispatcher.js","sourceRoot":"","sources":["../../src/core/action-dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAKN,WAAW,GAIX,MAAM,oBAAoB,CAAC;AAW5B,MAAM,OAAO,gBAAgB;IACC;IAA7B,YAA6B,QAAwB;QAAxB,aAAQ,GAAR,QAAQ,CAAgB;IAAG,CAAC;IAEzD,KAAK,CAAC,QAAQ,CAAC,KAAc;QAC5B,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAEO,KAAK,CAAC,iBAAiB,CAAC,MAAc;QAC7C,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;YACvB,KAAK,OAAO;gBACX,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACpC,KAAK,MAAM;gBACV,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnC,KAAK,cAAc;gBAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YAC1C,KAAK,QAAQ;gBACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACrC,KAAK,OAAO;gBACX,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACpC,KAAK,QAAQ;gBACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;IACF,CAAC;CACD"}

package/dist/core/action-schema.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const SpawnActionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"spawn">;
+    task: z.ZodString;
+    writeScope: z.ZodArray<z.ZodString>;
+    focusFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowRepositoryWide: z.ZodOptional<z.ZodBoolean>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const WaitActionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"wait">;
+    threadIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const InspectDiffActionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"inspect_diff">;
+    threadId: z.ZodString;
+}, z.core.$strict>;
+export declare const ReviewActionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"review">;
+    threadId: z.ZodString;
+}, z.core.$strict>;
+export declare const MergeActionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"merge">;
+    threadId: z.ZodString;
+}, z.core.$strict>;
+export declare const FinishActionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"finish">;
+    summary: z.ZodString;
+}, z.core.$strict>;
+export declare const ActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"spawn">;
+    task: z.ZodString;
+    writeScope: z.ZodArray<z.ZodString>;
+    focusFiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowRepositoryWide: z.ZodOptional<z.ZodBoolean>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"wait">;
+    threadIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"inspect_diff">;
+    threadId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"review">;
+    threadId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"merge">;
+    threadId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    action: z.ZodLiteral<"finish">;
+    summary: z.ZodString;
+}, z.core.$strict>], "action">;
+export type SpawnAction = z.infer<typeof SpawnActionSchema>;
+export type WaitAction = z.infer<typeof WaitActionSchema>;
+export type InspectDiffAction = z.infer<typeof InspectDiffActionSchema>;
+export type ReviewAction = z.infer<typeof ReviewActionSchema>;
+export type MergeAction = z.infer<typeof MergeActionSchema>;
+export type FinishAction = z.infer<typeof FinishActionSchema>;
+export type Action = z.infer<typeof ActionSchema>;
+export declare function parseAction(input: unknown): Action;

package/dist/core/action-schema.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { z } from "zod";
+const version = z.literal(1);
+const threadId = z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[A-Za-z0-9._:-]+$/);
+const repositoryRelativePath = z
+    .string()
+    .min(1)
+    .max(1024)
+    .refine((value) => !value.includes("\0"), "Path cannot contain null bytes")
+    .refine((value) => !path.posix.isAbsolute(value) && !path.win32.isAbsolute(value), "Path must be relative")
+    .refine((value) => !value.replaceAll("\\", "/").split("/").includes(".."), "Path cannot traverse outside the repository");
+export const SpawnActionSchema = z
+    .object({
+    version,
+    action: z.literal("spawn"),
+    task: z.string().min(1).max(20_000),
+    writeScope: z.array(repositoryRelativePath).min(1).max(200),
+    focusFiles: z.array(repositoryRelativePath).max(200).optional(),
+    allowRepositoryWide: z.boolean().optional(),
+    model: z.string().min(1).max(200).optional(),
+})
+    .strict()
+    .refine((data) => {
+    if (data.writeScope.includes(".")) {
+        return data.allowRepositoryWide === true;
+    }
+    return true;
+}, "Repository-wide write scope ('.') requires allowRepositoryWide to be true");
+export const WaitActionSchema = z
+    .object({
+    version,
+    action: z.literal("wait"),
+    threadIds: z.array(threadId).min(1).max(100),
+})
+    .strict();
+export const InspectDiffActionSchema = z
+    .object({
+    version,
+    action: z.literal("inspect_diff"),
+    threadId,
+})
+    .strict();
+export const ReviewActionSchema = z
+    .object({
+    version,
+    action: z.literal("review"),
+    threadId,
+})
+    .strict();
+export const MergeActionSchema = z
+    .object({
+    version,
+    action: z.literal("merge"),
+    threadId,
+})
+    .strict();
+export const FinishActionSchema = z
+    .object({
+    version,
+    action: z.literal("finish"),
+    summary: z.string().min(1).max(100_000),
+})
+    .strict();
+export const ActionSchema = z.discriminatedUnion("action", [
+    SpawnActionSchema,
+    WaitActionSchema,
+    InspectDiffActionSchema,
+    ReviewActionSchema,
+    MergeActionSchema,
+    FinishActionSchema,
+]);
+export function parseAction(input) {
+    const result = ActionSchema.safeParse(input);
+    if (!result.success) {
+        const details = result.error.issues
+            .map((issue) => `${issue.path.join(".") || "payload"}: ${issue.message}`)
+            .join("; ");
+        throw new Error(`Invalid action payload: ${details}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=action-schema.js.map

package/dist/core/action-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-schema.js","sourceRoot":"","sources":["../../src/core/action-schema.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC7B,MAAM,QAAQ,GAAG,CAAC;KAChB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CAAC,oBAAoB,CAAC,CAAC;AAC9B,MAAM,sBAAsB,GAAG,CAAC;KAC9B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,IAAI,CAAC;KACT,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,gCAAgC,CAAC;KAC1E,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,uBAAuB,CAAC;KAC1G,MAAM,CACN,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EACjE,6CAA6C,CAC7C,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAChC,MAAM,CAAC;IACP,OAAO;IACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IACnC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3D,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC/D,mBAAmB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC3C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CAC5C,CAAC;KACD,MAAM,EAAE;KACR,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;IAChB,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,mBAAmB,KAAK,IAAI,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC,EAAE,2EAA2E,CAAC,CAAC;AAEjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACP,OAAO;IACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACzB,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;CAC5C,CAAC;KACD,MAAM,EAAE,CAAC;AAEX,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACtC,MAAM,CAAC;IACP,OAAO;IACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;IACjC,QAAQ;CACR,CAAC;KACD,MAAM,EAAE,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KACjC,MAAM,CAAC;IACP,OAAO;IACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC3B,QAAQ;CACR,CAAC;KACD,MAAM,EAAE,CAAC;AAEX,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAChC,MAAM,CAAC;IACP,OAAO;IACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC1B,QAAQ;CACR,CAAC;KACD,MAAM,EAAE,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KACjC,MAAM,CAAC;IACP,OAAO;IACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;CACvC,CAAC;KACD,MAAM,EAAE,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE;IAC1D,iBAAiB;IACjB,gBAAgB;IAChB,uBAAuB;IACvB,kBAAkB;IAClB,iBAAiB;IACjB,kBAAkB;CAClB,CAAC,CAAC;AAUH,MAAM,UAAU,WAAW,CAAC,KAAc;IACzC,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aACjC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;aACxE,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/core/repl-interface.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Common REPL interface and execution primitives for ContextOS / Swarm.
+ */
+/** Result of executing a code snippet in the REPL. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    hasFinal: boolean;
+    finalValue: string | null;
+}
+/** Callback the host provides to handle llm_query() calls. */
+export type LlmQueryHandler = (subContext: string, instruction: string) => Promise<string>;
+/** Callback the host provides to handle thread() calls. */
+export type ThreadHandler = (task: string, context: string, agentBackend: string, model: string, files: string[]) => Promise<{
+    result: string;
+    success: boolean;
+    filesChanged: string[];
+    durationMs: number;
+}>;
+/** Callback the host provides to handle merge_threads() calls. */
+export type MergeHandler = () => Promise<{
+    result: string;
+    success: boolean;
+}>;
+/**
+ * Common execution engine interface implemented by PythonRepl (legacy/optional Python subprocess).
+ */
+export interface Repl {
+    readonly isAlive: boolean;
+    /** Start/initialize the execution runtime. */
+    start(signal?: AbortSignal): Promise<void>;
+    /** Gracefully shut down and release resources. */
+    shutdown(): void;
+    /** Register callback for llm_query() calls. */
+    setLlmQueryHandler(handler: LlmQueryHandler): void;
+    /** Register callback for thread() calls. */
+    setThreadHandler(handler: ThreadHandler): void;
+    /** Register callback for merge_threads() calls. */
+    setMergeHandler(handler: MergeHandler): void;
+    /** Inject context string into the execution environment. */
+    setContext(text: string): Promise<void>;
+    /** Reset the FINAL sentinel flag. */
+    resetFinal(): Promise<void>;
+    /** Execute a code snippet and return captured output. */
+    execute(code: string): Promise<ExecResult>;
+    /** Execution language target ('javascript' or 'python'). */
+    getLanguage(): "javascript" | "python";
+}

package/dist/core/repl-interface.js

@@ -0,0 +1,5 @@
+/**
+ * Common REPL interface and execution primitives for ContextOS / Swarm.
+ */
+export {};
+//# sourceMappingURL=repl-interface.js.map

package/dist/core/repl-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl-interface.js","sourceRoot":"","sources":["../../src/core/repl-interface.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/core/repl.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persistent Python REPL manager for swarm-code.
+ *
+ * Spawns a single Python subprocess running `runtime.py` and keeps it alive
+ * across multiple RLM iterations. Communication uses line-delimited JSON
+ * over stdin/stdout.
+ *
+ * Extended from rlm-cli with thread_request and merge_request handlers.
+ */
+import type { ExecResult, LlmQueryHandler, MergeHandler, Repl, ThreadHandler } from "./repl-interface.js";
+export * from "./repl-interface.js";
+export declare class PythonRepl implements Repl {
+    private proc;
+    private rl;
+    private llmQueryHandler;
+    private threadHandler;
+    private mergeHandler;
+    /**
+     * Pending resolvers for messages we're waiting on from Python.
+     * Each entry maps a unique key (requestId or message type) to a one-shot resolve/reject pair.
+     * Using requestId prevents collisions when two messages of the same type are in-flight.
+     */
+    private pending;
+    /** Whether the REPL subprocess is alive. */
+    get isAlive(): boolean;
+    getLanguage(): "javascript" | "python";
+    /**
+     * Start the Python subprocess and wait for it to signal readiness.
+     */
+    start(signal?: AbortSignal): Promise<void>;
+    /** Register the callback that handles llm_query() calls from Python. */
+    setLlmQueryHandler(handler: LlmQueryHandler): void;
+    /** Register the callback that handles thread() calls from Python. */
+    setThreadHandler(handler: ThreadHandler): void;
+    /** Register the callback that handles merge_threads() calls from Python. */
+    setMergeHandler(handler: MergeHandler): void;
+    /** Inject the full context string into the Python REPL. */
+    setContext(text: string): Promise<void>;
+    /** Reset the Final sentinel variable. */
+    resetFinal(): Promise<void>;
+    /** Execute a code snippet and return the result. */
+    execute(code: string): Promise<ExecResult>;
+    /** Gracefully shut down the Python subprocess. */
+    shutdown(): void;
+    private send;
+    private handleLine;
+    private handleLlmQueryMessage;
+    private handleThreadRequestMessage;
+    private handleMergeRequestMessage;
+    /**
+     * Wait for an inbound message from Python.
+     * @param type - Message type to wait for.
+     * @param requestId - Optional unique key for request-response pairs.
+     *   Prevents collisions when multiple in-flight messages share the same type.
+     *   Falls back to `type` when omitted (safe for singleton messages like "ready").
+     */
+    private waitForMessage;
+    private cleanup;
+}