constructor-research-mcp 0.0.0-stage → 0.3.0

package/dist/location.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/** Where a tool acts: a desk (project + desk), a project only, or a deployment-shaped input whose schema already allows a missing project_id. */
+export type Scope = "desk" | "project" | "deploy";
+/** Tool-facing schema: the engine schema plus desk_url, with the IDs it supplies made optional. */
+export declare function located(schema: z.ZodObject<any>, scope: Exclude<Scope, "deploy">): z.ZodObject<{
+    [x: string]: any;
+    project_id: z.ZodOptional<z.ZodString>;
+    desk_id?: z.ZodOptional<z.ZodString> | undefined;
+    desk_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Project and desk IDs from a desk link; the host must be the Constructor this MCP uses. */
+export declare function parseDeskUrl(link: string, baseUrl: string, fixed?: boolean): {
+    project_id: string;
+    desk_id: string;
+};
+/** Replace desk_url with the IDs it carries; explicit IDs must agree with it. */
+export declare function resolveDeskUrl(args: any, baseUrl: string, scope: Scope, fixed?: boolean): any;

package/dist/location.js

@@ -0,0 +1,60 @@
+import { ToolError } from "./api.js";
+import { id, deskUrl } from "./schemas.js";
+/** Tool-facing schema: the engine schema plus desk_url, with the IDs it supplies made optional. */
+export function located(schema, scope) {
+    return schema
+        .extend({
+        project_id: id.optional(),
+        ...("desk_id" in schema.shape ? { desk_id: id.optional() } : {}),
+        desk_url: deskUrl.optional(),
+    })
+        .refine((x) => !!x.desk_url ||
+        (!!x.project_id &&
+            (scope !== "desk" ||
+                !!x.desk_id ||
+                schema.shape.desk_id.safeParse(undefined).success)), scope === "desk"
+        ? "Provide desk_url (the desk link from the browser) or project_id and desk_id."
+        : "Provide desk_url (the desk link from the browser) or project_id.");
+}
+function bad(code, message) {
+    throw new ToolError(code, message);
+}
+/** Project and desk IDs from a desk link; the host must be the Constructor this MCP uses. */
+export function parseDeskUrl(link, baseUrl, fixed = false) {
+    let url;
+    try {
+        url = new URL(link.trim());
+    }
+    catch {
+        bad("invalid_input", "desk_url is not a valid link.");
+    }
+    const m = url.pathname.match(/\/projects\/([a-zA-Z0-9_-]{4,128})\/desks\/([a-zA-Z0-9_-]{4,128})(?:\/|$)/);
+    if (!m)
+        bad("invalid_input", "desk_url must contain /projects/<project>/desks/<desk>. Ask the user to open the desk in Constructor and copy the address bar.");
+    const base = new URL(baseUrl).origin;
+    if (url.origin !== base)
+        bad("wrong_environment", fixed
+            ? `The link is for ${url.origin}, but this MCP is fixed to ${base} by CONSTRUCTOR_BASE_URL. Ask the user for a link from ${base}.`
+            : `The link is for ${url.origin}, but the user is signed in to ${base}. If they work on ${url.origin}, tell them a sign-in window is about to open, then call sign_in with url set to this link; that replaces the sign-in to ${base}.`);
+    return { project_id: m[1], desk_id: m[2] };
+}
+/** Replace desk_url with the IDs it carries; explicit IDs must agree with it. */
+export function resolveDeskUrl(args, baseUrl, scope, fixed = false) {
+    if (!args?.desk_url)
+        return args;
+    const { desk_url, ...rest } = args;
+    const at = parseDeskUrl(desk_url, baseUrl, fixed);
+    if (rest.project_id && rest.project_id !== at.project_id)
+        bad("invalid_input", "project_id does not match the project in desk_url.");
+    rest.project_id = at.project_id;
+    if (scope === "desk") {
+        if (rest.desk_id && rest.desk_id !== at.desk_id)
+            bad("invalid_input", "desk_id does not match the desk in desk_url.");
+        rest.desk_id = at.desk_id;
+    }
+    if (scope === "deploy" && rest.services)
+        rest.services = rest.services.map((s) => s.build && !s.build.desk_id
+            ? { ...s, build: { ...s.build, desk_id: at.desk_id } }
+            : s);
+    return rest;
+}

package/dist/login.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/login.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Sign in from a terminal; the MCP's sign_in tool does the same from an agent session.
+// Usage: npx -y -p constructor-research-mcp constructor-research-login [--url <any link to your Constructor>] --for claude-code|codex|opencode   (or --to <session file>)
+import { configFromEnv, HARNESSES, originOf, sessionArgs } from "./config.js";
+import { signIn } from "./signin.js";
+const config = configFromEnv();
+const args = process.argv.slice(2);
+const at = args.indexOf("--url");
+const url = at >= 0 ? args.splice(at, 2)[1] : undefined;
+const { file } = sessionArgs(args, config);
+if (!file || (at >= 0 && !url)) {
+    console.error(`Usage: npx -y -p constructor-research-mcp constructor-research-login [--url <any link to your Constructor>] --for ${HARNESSES.join("|")}   (or --to <session file>)`);
+    process.exit(2);
+}
+if (url) {
+    const host = originOf(url);
+    if (config.baseUrlFixed && host !== config.baseUrl) {
+        console.error(`CONSTRUCTOR_BASE_URL fixes the MCP to ${config.baseUrl}.`);
+        process.exit(2);
+    }
+    config.baseUrl = host;
+}
+const result = await signIn(config, file, () => console.log(`A Chrome window opened at ${config.baseUrl}. Sign in there; it closes by itself afterwards.`));
+(result.status === "signed_in" ? console.log : console.error)(result.message);
+process.exit(result.status === "signed_in" ? 0 : 1);

package/dist/logs.d.ts

@@ -0,0 +1,59 @@
+import { PlatformApi } from "./api.js";
+/** Lines kept per build; the tool returns up to this many. */
+export declare const KEEP = 50;
+export type LogState = "live" | "finished" | "unavailable";
+/** Every connection replays the log from the start (a service: its current container), then streams. */
+export type LogKind = "build" | "service";
+export interface LogView {
+    kind: LogKind;
+    id: string;
+    state: LogState;
+    lines: string[];
+    last_received_at?: string;
+    /** New containers seen starting while the MCP followed this service. */
+    restarts_seen?: number;
+    restarted_at?: string[];
+    message?: string;
+}
+/**
+ * Follows build and service log streams and keeps only the last KEEP lines of each, in
+ * memory and in a small file in the state directory. The platform serves a build log only
+ * while the build runs, and every connection replays it from the start, so a dropped
+ * stream is reopened and already-seen lines are skipped. When the build ends the stream
+ * closes and reopening answers "not found"; the kept lines stay readable. A service log
+ * covers its current container only (a restarted container starts empty), so services are followed from their start
+ * and for a while after anyone last asked.
+ */
+export declare class LogFollower {
+    readonly api: PlatformApi;
+    private readonly dir;
+    private logs;
+    private readonly controller;
+    /** Backoff between reconnects; tests shorten it. */
+    retryMs: number[];
+    /** Reopen a stream that sent nothing for this long (a silent proxy timeout). */
+    idleMs: number;
+    /** How long to follow after the last interest: builds until they end, services briefly. */
+    followMs: Record<LogKind, number>;
+    constructor(api: PlatformApi, dir?: string);
+    /** Start following if nobody is; cheap to call on every poll. */
+    follow(id: string, kind?: LogKind): void;
+    /** Last `count` lines, following first if the build or service may still be running. */
+    tail(id: string, kind?: LogKind, count?: number, waitMs?: number): Promise<LogView>;
+    /** Kept lines without contacting the platform. */
+    peek(id: string, kind?: LogKind, count?: number): Promise<LogView | undefined>;
+    close(): Promise<void>;
+    /** New containers seen starting while this service was followed. */
+    restarts(id: string): string[];
+    private view;
+    private read;
+    private add;
+    /** Marks a new container in the kept lines. */
+    private restarted;
+    private keep;
+    /** At most every few seconds while streaming, and once at the end. */
+    private save;
+    private load;
+    /** Forget the oldest finished builds; their files remain. */
+    private prune;
+}

package/dist/logs.js

@@ -0,0 +1,330 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { ToolError, segment } from "./api.js";
+/** Lines kept per build; the tool returns up to this many. */
+export const KEEP = 50;
+/** Longer lines are cut, so one runaway line cannot fill memory. */
+const WIDTH = 1000;
+const ID = /^[a-zA-Z0-9_-]{4,128}$/;
+const STAMP = /^(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z)(?: |$)/;
+/** What the platform prints, unstamped, before a container's first line. */
+const WAITING = /^Container is waiting to start/i;
+/** Restart times kept per service. */
+const RESTARTS = 20;
+const ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+const PATH = {
+    build: "image-builds",
+    service: "services",
+};
+/**
+ * Follows build and service log streams and keeps only the last KEEP lines of each, in
+ * memory and in a small file in the state directory. The platform serves a build log only
+ * while the build runs, and every connection replays it from the start, so a dropped
+ * stream is reopened and already-seen lines are skipped. When the build ends the stream
+ * closes and reopening answers "not found"; the kept lines stay readable. A service log
+ * covers its current container only (a restarted container starts empty), so services are followed from their start
+ * and for a while after anyone last asked.
+ */
+export class LogFollower {
+    api;
+    dir;
+    logs = new Map();
+    controller = new AbortController();
+    /** Backoff between reconnects; tests shorten it. */
+    retryMs = [1000, 2000, 5000, 10000, 20000];
+    /** Reopen a stream that sent nothing for this long (a silent proxy timeout). */
+    idleMs = 5 * 60 * 1000;
+    /** How long to follow after the last interest: builds until they end, services briefly. */
+    followMs = {
+        build: 2 * 60 * 60 * 1000,
+        service: 15 * 60 * 1000,
+    };
+    constructor(api, dir = join(api.config.stateDir, "logs")) {
+        this.api = api;
+        this.dir = dir;
+    }
+    /** Start following if nobody is; cheap to call on every poll. */
+    follow(id, kind = "build") {
+        if (!ID.test(id) || this.controller.signal.aborted)
+            return;
+        let log = this.logs.get(`${kind}:${id}`);
+        if (log)
+            log.until = Date.now() + this.followMs[kind];
+        if (log?.reader || (kind === "build" && log?.state === "finished"))
+            return;
+        if (!log) {
+            log = {
+                kind,
+                until: Date.now() + this.followMs[kind],
+                lines: [],
+                restarts: [],
+                state: "live",
+                saved: 0,
+            };
+            this.logs.set(`${kind}:${id}`, log);
+            this.prune();
+        }
+        log.state = "live";
+        log.error = undefined;
+        const current = log;
+        current.reader = this.read(id, current).finally(() => {
+            current.reader = undefined;
+            if (current.state === "live")
+                current.state = current.lines.length ? "finished" : "unavailable";
+            return this.save(id, current, true);
+        });
+    }
+    /** Last `count` lines, following first if the build or service may still be running. */
+    async tail(id, kind = "build", count = 20, waitMs = kind === "build" ? 8000 : 1500) {
+        if (!ID.test(id))
+            throw new ToolError("invalid_input", `Invalid ${kind} ID.`);
+        let log = this.logs.get(`${kind}:${id}`) ?? (await this.load(id, kind));
+        if (log?.reader || kind === "service" || log?.state !== "finished") {
+            this.follow(id, kind);
+            log = this.logs.get(`${kind}:${id}`);
+            // A new connection replays the build log so far, in bursts over a few seconds:
+            // wait until it has been quiet for a second.
+            const deadline = Date.now() + waitMs;
+            while (log.reader &&
+                Date.now() < deadline &&
+                !(log.received && Date.now() - Date.parse(log.received) >= 1000))
+                await delay(100);
+        }
+        return this.view(id, log, count);
+    }
+    /** Kept lines without contacting the platform. */
+    async peek(id, kind = "build", count = 20) {
+        const log = this.logs.get(`${kind}:${id}`) ?? (await this.load(id, kind));
+        return log && log.lines.length ? this.view(id, log, count) : undefined;
+    }
+    async close() {
+        this.controller.abort();
+        await Promise.allSettled([...this.logs.values()].map((log) => log.reader));
+    }
+    /** New containers seen starting while this service was followed. */
+    restarts(id) {
+        return this.logs.get(`service:${id}`)?.restarts ?? [];
+    }
+    view(id, log, count) {
+        const service = log.kind === "service";
+        const restarts = log.restarts.length;
+        return {
+            kind: log.kind,
+            id,
+            state: log.state,
+            lines: log.lines.slice(-Math.max(1, Math.min(KEEP, count))),
+            last_received_at: log.received,
+            ...(restarts
+                ? { restarts_seen: restarts, restarted_at: log.restarts }
+                : {}),
+            message: log.error ??
+                (restarts
+                    ? `The container restarted ${restarts} time${restarts > 1 ? "s" : ""} while the MCP followed it (last at ${log.restarts.at(-1)}). Lines above each "--- new container" marker come from the container before it; its last lines usually show why it stopped.`
+                    : undefined) ??
+                (log.state === "unavailable"
+                    ? service
+                        ? "No log: the service is not running, or its current container has printed nothing (a container that keeps crashing has no current log)."
+                        : "No log: the build is not running and this MCP did not follow it while it ran. Constructor serves build logs only during the build."
+                    : log.state === "finished"
+                        ? service
+                            ? "No longer following; these are the last lines kept."
+                            : "The build is no longer running; these are the last lines it wrote."
+                        : service
+                            ? "Following the log of the service's current container. No lines can mean the container keeps restarting (crash loop) or has printed nothing yet."
+                            : undefined),
+        };
+    }
+    async read(id, log) {
+        const signal = this.controller.signal;
+        for (let failures = 0;;) {
+            if (signal.aborted || Date.now() > log.until)
+                return;
+            const connection = new AbortController();
+            const stop = () => connection.abort();
+            signal.addEventListener("abort", stop, { once: true });
+            let idle;
+            const watch = () => {
+                clearTimeout(idle);
+                idle = setTimeout(stop, this.idleMs);
+            };
+            try {
+                watch();
+                const response = await this.api.stream(`/${PATH[log.kind]}/${segment(id)}/logs`, connection.signal);
+                if (response.status === 404 || response.status === 421) {
+                    // Not running (the build is over); what was kept is final.
+                    await response.body?.cancel();
+                    return;
+                }
+                if (!response.ok || !response.body) {
+                    await response.body?.cancel();
+                    if (response.status < 500) {
+                        log.error = `Constructor answered HTTP ${response.status} for this build log.`;
+                        return;
+                    }
+                    throw new ToolError("connection_error", "");
+                }
+                failures = 0;
+                log.fresh = true;
+                log.pending = [];
+                let partial = "";
+                const decoder = new TextDecoder();
+                for await (const chunk of response.body) {
+                    watch();
+                    partial += decoder.decode(chunk, { stream: true });
+                    const parts = partial.split(/\r?\n/);
+                    partial = parts.pop().slice(-WIDTH * 4);
+                    for (const part of parts)
+                        this.add(log, part);
+                    await this.save(id, log);
+                }
+                if (partial)
+                    this.add(log, partial);
+                // Held lines of a connection that never showed a stamped line are a replay or a
+                // container that has not started yet; the next connection decides.
+                log.pending = [];
+                // A closed stream means the build ended or a proxy cut it; reopening tells which.
+            }
+            catch (err) {
+                if (signal.aborted)
+                    return;
+                if (err instanceof ToolError && err.code === "needs_auth") {
+                    log.error =
+                        "The token expired while following this build log; the lines below may be incomplete.";
+                    return;
+                }
+                if (++failures > 8) {
+                    log.error =
+                        "The build log connection kept failing; the lines below may be incomplete.";
+                    return;
+                }
+            }
+            finally {
+                clearTimeout(idle);
+                signal.removeEventListener("abort", stop);
+            }
+            await delay(this.retryMs[Math.min(failures, this.retryMs.length - 1)], undefined, { signal }).catch(() => { });
+        }
+    }
+    add(log, raw) {
+        let line = raw.replace(ANSI, "");
+        // Server-sent-event framing, if any: keep data, drop fields and comments.
+        if (/^(event|id|retry):/.test(line) || line.startsWith(":"))
+            return;
+        if (line.startsWith("data:"))
+            line = line.slice(5).replace(/^ /, "");
+        line = line.trimEnd();
+        if (!line)
+            return;
+        const stamp = STAMP.exec(line)?.[1];
+        if (!stamp) {
+            if (log.kind === "service" && WAITING.test(line) && log.last) {
+                // After a container's own lines, the platform's waiting line means a new container,
+                // whether it arrives on this connection or opens the next one.
+                if (log.fresh)
+                    return void log.pending?.push(line);
+                this.restarted(log, new Date().toISOString());
+                log.fresh = true;
+                log.pending = [line];
+                return;
+            }
+            if (log.fresh && log.last)
+                return void log.pending?.push(line);
+            return this.keep(log, line);
+        }
+        if (log.fresh) {
+            log.fresh = false;
+            const held = log.pending ?? [];
+            log.pending = [];
+            // A replay starts with lines already kept (its held lines were kept too); anything
+            // newer on a fresh connection comes from a new container.
+            if (!log.last || stamp > log.last) {
+                if (log.kind === "service" && log.last)
+                    this.restarted(log, stamp);
+                log.restarting = false;
+                for (const h of held)
+                    this.keep(log, h);
+            }
+        }
+        if (log.last && stamp <= log.last)
+            return; // replayed after a reconnect
+        log.last = stamp;
+        // A line that is only a timestamp carries nothing to show.
+        if (line.length > stamp.length)
+            this.keep(log, line);
+    }
+    /** Marks a new container in the kept lines. */
+    restarted(log, at) {
+        if (log.restarting)
+            return;
+        log.restarting = true;
+        log.restarts.push(at);
+        if (log.restarts.length > RESTARTS)
+            log.restarts.shift();
+        this.keep(log, `--- new container (restart ${log.restarts.length}) ---`);
+    }
+    keep(log, line) {
+        log.received = new Date().toISOString();
+        if (line === log.previous && log.lines.length) {
+            log.repeats = (log.repeats ?? 1) + 1;
+            log.lines[log.lines.length - 1] = `${line} (×${log.repeats})`;
+            return;
+        }
+        log.previous = line;
+        log.repeats = 1;
+        log.lines.push(line.length > WIDTH ? line.slice(0, WIDTH) + "…" : line);
+        if (log.lines.length > KEEP)
+            log.lines.shift();
+    }
+    /** At most every few seconds while streaming, and once at the end. */
+    async save(id, log, force = false) {
+        if (!force && Date.now() - log.saved < 5000)
+            return;
+        log.saved = Date.now();
+        try {
+            await mkdir(this.dir, { recursive: true, mode: 0o700 });
+            await writeFile(join(this.dir, `${log.kind}-${id}.json`), JSON.stringify({
+                state: log.reader && !force ? "live" : log.state,
+                lines: log.lines,
+                last: log.last,
+                restarts: log.restarts,
+                received: log.received,
+                error: log.error,
+            }), { mode: 0o600 });
+        }
+        catch {
+            /* Logs are a convenience; never fail a deployment over them. */
+        }
+    }
+    async load(id, kind) {
+        try {
+            const kept = JSON.parse(await readFile(join(this.dir, `${kind}-${id}.json`), "utf8"));
+            // A "live" file was written by another process, which may have stopped.
+            const log = {
+                kind,
+                until: 0,
+                lines: Array.isArray(kept.lines) ? kept.lines.slice(-KEEP) : [],
+                state: kept.state === "finished" ? "finished" : "unavailable",
+                last: kept.last,
+                restarts: Array.isArray(kept.restarts) ? kept.restarts : [],
+                received: kept.received,
+                error: kept.error,
+                saved: 0,
+            };
+            this.logs.set(`${kind}:${id}`, log);
+            return log;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Forget the oldest finished builds; their files remain. */
+    prune() {
+        for (const [id, log] of this.logs) {
+            if (this.logs.size <= 100)
+                return;
+            if (!log.reader)
+                this.logs.delete(id);
+        }
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,23 @@
+import { DeploymentEngine } from "./deployment.js";
+export declare const paused: Set<string>;
+/** Owns execution. The agent submits intent and observes results, never engine steps. */
+export declare class DeploymentRuntime {
+    readonly engine: DeploymentEngine;
+    private readonly pollMilliseconds;
+    private active;
+    private closed;
+    constructor(engine: DeploymentEngine, pollMilliseconds?: number);
+    recover(): Promise<void>;
+    close(): Promise<void>;
+    deploy(raw: unknown): Promise<any>;
+    update(raw: unknown): Promise<any>;
+    buildImage(raw: unknown): Promise<any>;
+    lifecycle(kind: "start" | "stop", raw: unknown): Promise<any>;
+    get(raw: unknown): Promise<any>;
+    private execute;
+    private pause;
+    private wake;
+    private run;
+    private snapshot;
+    private wait;
+}