lastlight 0.1.15 → 0.2.0

package/dist/notify/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared, platform-agnostic notification model.
+ *
+ * The notifier renders workflow progress as a single "task list" surface that
+ * is **edited in place** as phases run — one GitHub comment (via
+ * `issues.updateComment`) and/or one Slack message (via `chat.update`) instead
+ * of a fresh comment per phase. The model here is the canonical content; the
+ * renderer (`render.ts`) turns it into markdown that both platforms consume
+ * (Slack runs the markdown through `markdownToSlackMrkdwn` in its transport).
+ *
+ * Nothing in this module imports GitHub or Slack — platform code lives behind
+ * the `NotifierTransport` interface so the content model stays decoupled and
+ * shared.
+ */
+/** Lifecycle state of a single checklist step. */
+export type StepStatus = "pending" | "running" | "done" | "blocked" | "awaiting" | "failed" | "skipped";
+/** One row in the task list. `key` is stable; `label` is what humans see. */
+export interface ProgressStep {
+    key: string;
+    label: string;
+    status: StepStatus;
+    /** Optional one-line context shown after the label (e.g. a link or status). */
+    detail?: string;
+}
+/** The full content model rendered into the single status surface. */
+export interface ProgressModel {
+    /** Heading line, e.g. "build for #18". */
+    title: string;
+    /** Optional bold sub-heading, e.g. the issue title. */
+    subtitle?: string;
+    /** Optional metadata lines under the heading (branch link, PR link, …). */
+    meta?: string[];
+    /** Ordered checklist. */
+    steps: ProgressStep[];
+    /** Optional trailing line (e.g. artifacts link). */
+    footer?: string;
+}
+/**
+ * A platform binding. Each transport owns its own in-place-update handle
+ * (a GitHub comment id or a Slack message ts) internally.
+ */
+export interface NotifierTransport {
+    /** Create-or-update the single status surface with the rendered markdown. */
+    publish(markdown: string): Promise<void>;
+    /**
+     * Post a *new, separate* message (not an edit). Used for approval prompts —
+     * moments worth an actual notification, since an in-place edit is silent.
+     */
+    note(markdown: string): Promise<void>;
+    /**
+     * Whether this surface wants a separate *completion* ping at the end of a
+     * run. Slack sets this (its in-place edits are silent and it has no other
+     * signal); GitHub leaves it false — the edited checklist plus the
+     * PR-opened event already notify watchers, so a terminal comment would just
+     * be noise. Default false.
+     */
+    readonly terminalPing?: boolean;
+}
+/**
+ * The runner-facing API. `runner.ts` only ever sees this interface — it never
+ * touches a transport or the markdown directly.
+ */
+export interface ProgressReporter {
+    /** Seed the task list. Idempotent: a resumed run re-seeds the same surface. */
+    start(model: ProgressModel): Promise<void>;
+    /** Transition a step's status (and optionally set its one-line detail). */
+    step(key: string, status: StepStatus, detail?: string): Promise<void>;
+    /**
+     * Insert (or update) a dynamic step before `beforeKey` — used for loop
+     * iterations (re-review / fix cycles). Appends when `beforeKey` is omitted
+     * or not found.
+     */
+    insertStep(step: ProgressStep, beforeKey?: string): Promise<void>;
+    /** Post a standalone message to every surface (e.g. an approval prompt). */
+    note(markdown: string): Promise<void>;
+    /**
+     * Set (or clear) the trailing footer of the single status surface and
+     * re-publish in place. Used to fold a workflow's final synthesized result
+     * into the same comment as the checklist rather than posting a new one.
+     * Pass an empty string to clear.
+     */
+    footer(markdown: string): Promise<void>;
+    /**
+     * Post the run's completion message, but only to surfaces that want a
+     * terminal ping (Slack) — GitHub is left with just the finished checklist.
+     */
+    noteTerminal(markdown: string): Promise<void>;
+}
+/** Persisted in-place-update handles, stored under `workflow_runs.scratch.notifier`. */
+export interface NotifierState {
+    githubCommentId?: number;
+    slackTs?: string;
+    slackChannel?: string;
+    slackThread?: string;
+}

package/dist/notify/types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared, platform-agnostic notification model.
+ *
+ * The notifier renders workflow progress as a single "task list" surface that
+ * is **edited in place** as phases run — one GitHub comment (via
+ * `issues.updateComment`) and/or one Slack message (via `chat.update`) instead
+ * of a fresh comment per phase. The model here is the canonical content; the
+ * renderer (`render.ts`) turns it into markdown that both platforms consume
+ * (Slack runs the markdown through `markdownToSlackMrkdwn` in its transport).
+ *
+ * Nothing in this module imports GitHub or Slack — platform code lives behind
+ * the `NotifierTransport` interface so the content model stays decoupled and
+ * shared.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/notify/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/notify/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/sandbox/docker-compose.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sandbox/docker-compose.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { parse } from "yaml";
+import { COREDNS_OPEN_IP, COREDNS_STRICT_IP, NGINX_OPEN_IP, NGINX_STRICT_IP, OTEL_COLLECTOR_IP, OTEL_COLLECTOR_UID, SANDBOX_EGRESS_SUBNET, } from "./egress-firewall-config.js";
+const compose = parse(readFileSync(resolve(__dirname, "../../docker-compose.yml"), "utf-8"));
+const FIREWALL_SERVICES = [
+    "nginx-egress-strict",
+    "nginx-egress-open",
+    "coredns-strict",
+    "coredns-open",
+];
+const HARNESS_SERVICES = ["agent", "caddy"];
+function networkNamesOf(service) {
+    const nets = compose.services[service]?.networks;
+    if (!nets)
+        return [];
+    if (Array.isArray(nets))
+        return nets;
+    return Object.keys(nets);
+}
+function ipv4OnNetwork(service, net) {
+    const nets = compose.services[service]?.networks;
+    if (!nets || Array.isArray(nets))
+        return undefined;
+    const cfg = nets[net];
+    if (cfg && typeof cfg === "object" && "ipv4_address" in cfg) {
+        return String(cfg.ipv4_address);
+    }
+    return undefined;
+}
+describe("docker-compose egress topology", () => {
+    it("declares the three expected networks", () => {
+        expect(Object.keys(compose.networks).sort()).toEqual(["internal", "proxy-egress", "sandbox-egress"].sort());
+    });
+    it("marks sandbox-egress as internal: true with the expected static subnet", () => {
+        const net = compose.networks["sandbox-egress"];
+        expect(net?.internal).toBe(true);
+        // Subnet must match SANDBOX_EGRESS_SUBNET so the constants in
+        // egress-firewall-config.ts are valid IPs in that range.
+        const subnet = net?.ipam?.config?.[0]?.subnet;
+        expect(subnet).toBe(SANDBOX_EGRESS_SUBNET);
+    });
+    it("proxy-egress is a regular bridge (no internal: true) so firewalls can reach the internet", () => {
+        const net = compose.networks["proxy-egress"];
+        // YAML `proxy-egress:` parses to null when no fields are set.
+        expect(net == null || net.internal !== true).toBe(true);
+    });
+    for (const svc of FIREWALL_SERVICES) {
+        describe(svc, () => {
+            const nets = networkNamesOf(svc);
+            it("does NOT attach to the harness `internal` network", () => {
+                // Security-critical: if regressed, an unrestricted sandbox can
+                // bridge into compose-internal services via the firewall.
+                expect(nets).not.toContain("internal");
+            });
+            it("attaches to sandbox-egress (so sandboxes can reach it)", () => {
+                expect(nets).toContain("sandbox-egress");
+            });
+        });
+    }
+    it("nginx firewalls attach to proxy-egress (so they can reach the public internet)", () => {
+        for (const svc of ["nginx-egress-strict", "nginx-egress-open"]) {
+            expect(networkNamesOf(svc)).toContain("proxy-egress");
+        }
+    });
+    describe("otel-collector", () => {
+        const nets = networkNamesOf("otel-collector");
+        it("is dual-homed on sandbox-egress (ingress from sandboxes) + proxy-egress (outbound to backend)", () => {
+            expect(nets).toContain("sandbox-egress");
+            expect(nets).toContain("proxy-egress");
+        });
+        it("does NOT attach to the harness `internal` network (can't bridge a sandbox into harness services)", () => {
+            expect(nets).not.toContain("internal");
+        });
+        it("uses the static IP the harness bakes into the sandbox OTLP endpoint", () => {
+            expect(ipv4OnNetwork("otel-collector", "sandbox-egress")).toBe(OTEL_COLLECTOR_IP);
+        });
+        it("does NOT force root — runs as the image's non-root UID", () => {
+            // The harness writes the mode-0600 config as UID OTEL_COLLECTOR_UID (its
+            // `lastlight` user is pinned to it), so the collector reads it as owner
+            // without root. If this ever regresses to `user: "0:0"`, we'd be running
+            // a sandbox-facing service as root unnecessarily.
+            expect(compose.services["otel-collector"]?.user).toBeUndefined();
+        });
+    });
+    it("pins the harness `lastlight` UID to the collector image UID so it can read the 0600 config", () => {
+        // The collector reads the harness-written mode-0600 OTLP config as its
+        // owner. That only works if the harness writes it as the collector's UID,
+        // so the Dockerfile must `useradd -u <OTEL_COLLECTOR_UID> lastlight`. If
+        // the collector image's UID ever changes, this test fails loudly to force
+        // bumping both together.
+        const dockerfile = readFileSync(resolve(__dirname, "../../Dockerfile"), "utf-8");
+        expect(dockerfile).toMatch(new RegExp(`useradd[^\\n]*-u\\s+${OTEL_COLLECTOR_UID}\\s+lastlight`));
+    });
+    it("coredns containers do NOT attach to proxy-egress (no internet needed)", () => {
+        // CoreDNS only synthesises answers from its config; it never recurses.
+        // Keeping it off proxy-egress is defence in depth.
+        for (const svc of ["coredns-strict", "coredns-open"]) {
+            expect(networkNamesOf(svc)).not.toContain("proxy-egress");
+        }
+    });
+    it("static IPs match the constants the harness bakes into the generated configs", () => {
+        expect(ipv4OnNetwork("coredns-strict", "sandbox-egress")).toBe(COREDNS_STRICT_IP);
+        expect(ipv4OnNetwork("coredns-open", "sandbox-egress")).toBe(COREDNS_OPEN_IP);
+        expect(ipv4OnNetwork("nginx-egress-strict", "sandbox-egress")).toBe(NGINX_STRICT_IP);
+        expect(ipv4OnNetwork("nginx-egress-open", "sandbox-egress")).toBe(NGINX_OPEN_IP);
+    });
+    for (const svc of HARNESS_SERVICES) {
+        it(`harness service \`${svc}\` does NOT attach to proxy-egress or sandbox-egress`, () => {
+            // Keeps the egress fabric isolated from anything carrying secrets.
+            const nets = networkNamesOf(svc);
+            expect(nets).not.toContain("proxy-egress");
+            expect(nets).not.toContain("sandbox-egress");
+        });
+    }
+    it("proxy-egress contains exactly the two nginx firewalls and the otel-collector", () => {
+        // These are the only services allowed an outbound path: the firewalls
+        // tunnel sandbox HTTPS, and the collector re-exports sandbox telemetry.
+        // None touch `internal`, so none can bridge a sandbox into harness
+        // services. Any other service appearing here is a regression.
+        const onProxyEgress = Object.keys(compose.services)
+            .filter((name) => networkNamesOf(name).includes("proxy-egress"))
+            .sort();
+        expect(onProxyEgress).toEqual(["nginx-egress-open", "nginx-egress-strict", "otel-collector"]);
+    });
+});
+//# sourceMappingURL=docker-compose.test.js.map

package/dist/sandbox/docker-compose.test.js.map

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

package/dist/sandbox/docker.d.ts

@@ -6,7 +6,7 @@
  * workspace after volumes are mounted — no post-run docker exec needed.
  *
  * Volumes mounted at runtime:
- * - Shared data volume (/data): Claude auth, secrets (app.pem), session logs
+ * - Shared data volume (/data): secrets (app.pem), session logs
  * - Task worktree (/home/agent/workspace): per-task git repo
  */
 export interface SandboxConfig {
@@ -16,12 +16,61 @@ export interface SandboxConfig {
     env: Record<string, string>;
     /** Timeout in seconds (default: 1800 = 30 min) */
     timeoutSeconds?: number;
+    /**
+     * Per-sandbox memory cap, in Docker's `--memory` format (e.g. "2g", "512m").
+     * Default: 2g — enough headroom for `npm install`, vite build, and an
+     * agent loop, but small enough that several concurrent sandboxes can't
+     * exhaust a 16 GB host. Override via the `SANDBOX_MEMORY_LIMIT` env var.
+     */
+    memoryLimit?: string;
+    /**
+     * Docker network to attach the sandbox container to. Defaults to
+     * `LASTLIGHT_SANDBOX_NETWORK` env var or `lastlight_sandbox-egress`
+     * (the `internal: true` network declared in docker-compose.yml). The
+     * sandbox can only reach the public internet through the nginx-egress
+     * firewall sidecars on this network.
+     */
+    network?: string;
+    /**
+     * IP of the coredns sidecar this sandbox uses as its DNS resolver.
+     * `coredns-strict` (172.30.0.10) returns the strict-nginx IP for
+     * allowlisted hosts and NXDOMAIN for everything else; `coredns-open`
+     * (172.30.0.11) returns the open-nginx IP for any hostname (minus a
+     * small SSRF deny set). Passed to `docker run` as `--dns <ip>`.
+     *
+     * No env vars are injected — the sandbox has no idea a firewall is
+     * in front of it. Works for every SDK regardless of whether it
+     * honours HTTP_PROXY / HTTPS_PROXY.
+     */
+    dnsIp?: string;
 }
 export interface SandboxInfo {
     containerId: string;
     containerName: string;
     worktreePath: string;
 }
+/**
+ * How `/home/agent/workspace` is materialized inside the sandbox container.
+ *
+ * - `bind`: classic host-path bind mount. Only safe when the host filesystem
+ *   path is identical from the harness's view and the docker daemon's view —
+ *   i.e. local dev where the harness runs directly on the host, or any
+ *   deployment where `SANDBOX_DATA_VOLUME` is a real host path.
+ * - `volume-subpath`: mount a subpath of a named docker volume. Required
+ *   when the harness runs inside a container that holds the data dir via a
+ *   named volume (the standard docker-compose setup). A bare bind would
+ *   resolve `/app/data/sandboxes/<id>` against the host's empty bare-FS
+ *   `/app/data/...` rather than the named volume's `_data/sandboxes/<id>`,
+ *   producing two divergent trees and breaking skill staging.
+ */
+export type WorkspaceMount = {
+    type: "bind";
+    hostPath: string;
+} | {
+    type: "volume-subpath";
+    volume: string;
+    subpath: string;
+};
 export declare class DockerSandbox {
     private config;
     private activeContainers;
@@ -32,25 +81,64 @@ export declare class DockerSandbox {
     create(opts: {
         taskId: string;
         worktreePath: string;
+        workspaceMount: WorkspaceMount;
     }): Promise<SandboxInfo>;
     /**
-     * Wait for the sandbox entrypoint to finish setup.
-     * Polls for the credentials symlink in the agent's home directory.
+     * Wait for the sandbox entrypoint to finish setup. The entrypoint touches
+     * `$WORKSPACE/.ready` as its last step before exec'ing the agent shell.
      */
     private waitForReady;
     /**
-     * Run the Claude CLI inside the sandbox with a prompt.
+     * Run the agentic-pi CLI inside the sandbox with a prompt.
      *
-     * Streams stdout line-by-line so the caller can react to stream-json events
-     * (e.g. capture the session id from the `system/init` line) before the
-     * agent has finished. The full stdout is also buffered and returned for
-     * post-run parsing of the `result` line.
+     * Streams stdout line-by-line so the caller can react to JSON events
+     * (e.g. capture the top-level `session` record's id) before the agent
+     * has finished. The full stdout is also buffered and returned for
+     * post-run parsing of the usage_snapshot rollup.
      */
     runAgent(taskId: string, prompt: string, opts?: {
         model?: string;
+        /**
+         * Pi thinking level: `off | minimal | low | medium | high | xhigh`.
+         * Validated against the closed set before being shell-interpolated.
+         */
+        thinking?: string;
+        /** agentic-pi GitHub profile: `read | issues-write | review-write | repo-write`. */
+        profile?: string;
+        /**
+         * Env forwarded INTO the sandboxed run via repeated `--sandbox-env`
+         * flags. Used to inject git identity. Keys / values are charset-asserted
+         * before shell interpolation.
+         */
+        sandboxEnv?: Record<string, string>;
+        /**
+         * Working directory for the agent process inside the container.
+         * Defaults to WORKSPACE_DIR (the workspace root). When the harness
+         * pre-cloned the target repo, the executor passes
+         * `<WORKSPACE_DIR>/<repo>` so the agent starts inside the checked-out
+         * tree. The path is asserted against an allowlist before being passed
+         * to `docker exec -w` to keep it shell-safe.
+         */
+        agentCwd?: string;
+        /**
+         * Enable agentic-pi's web-search extension. When false (or omitted),
+         * `--no-web-search` is appended to suppress auto-enable. When true,
+         * the flag is omitted and agentic-pi auto-detects the provider from
+         * whichever `*_API_KEY` env var the container received.
+         */
+        webSearch?: boolean;
+        /** Force a specific web-search provider. Validated against a closed set. */
+        webSearchProvider?: "tavily" | "brave" | "exa";
+        /**
+         * Per-phase skill directories to load, as absolute in-container paths
+         * under WORKSPACE_DIR (e.g. `/home/agent/workspace/.lastlight-skills/
+         * <phase>/<skill>`). Each becomes a repeated `--skill <dir>` flag.
+         * Charset/prefix-asserted before shell interpolation.
+         */
+        skillDirs?: string[];
         /** Called for each newline-terminated stdout line as it arrives. */
         onLine?: (line: string) => void;
-    }): Promise<string>;
+    }): Promise<void>;
     /**
      * Remove a sandbox container.
      */