@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/service/server-routes-action-proposals.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function tryHandleActionProposals(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-action-proposals.js

@@ -0,0 +1,45 @@
+import { LOCAL_SERVICE_ROUTES } from "./routes.js";
+import { decodeOr400, readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { listStoredProjects } from "../project-store.js";
+export async function tryHandleActionProposals(req, res, runtime, path, method) {
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.actionProposals) {
+        const firstProject = listStoredProjects()[0];
+        sendJson(res, 200, {
+            action_proposals: runtime.listActionProposals(firstProject?.projectDataDir ?? runtime.rootPath),
+        });
+        return true;
+    }
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.actionProposals) {
+        const body = await readJsonBody(req);
+        const firstProject = listStoredProjects()[0];
+        sendJson(res, 202, await runtime.createActionProposal(firstProject?.projectDataDir ?? runtime.rootPath, body));
+        return true;
+    }
+    const actionProposalMatch = path.match(/^\/v1\/action-proposals\/([^/]+)(?:\/([^/]+))?$/);
+    if (actionProposalMatch?.[1]) {
+        const proposalId = decodeOr400(res, actionProposalMatch[1], "Action proposal id");
+        if (proposalId === null)
+            return true;
+        const child = actionProposalMatch[2];
+        const firstProject = listStoredProjects()[0];
+        const projectDataDir = firstProject?.projectDataDir ?? runtime.rootPath;
+        if (method === "GET" && !child) {
+            const proposal = runtime.getActionProposal(projectDataDir, proposalId);
+            if (!proposal)
+                sendError(res, 404, "Action proposal not found.");
+            else
+                sendJson(res, 200, proposal);
+            return true;
+        }
+        if (method === "POST" && child === "decision") {
+            const body = await readJsonBody(req);
+            const proposal = await runtime.decideActionProposal(projectDataDir, proposalId, body);
+            if (!proposal)
+                sendError(res, 404, "Action proposal not found.");
+            else
+                sendJson(res, 202, proposal);
+            return true;
+        }
+    }
+    return false;
+}

package/dist/packages/runtime/service/server-routes-agents.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function tryHandleExecutor(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;
+export declare function tryHandleAgents(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-agents.js

@@ -0,0 +1,132 @@
+import { join } from "node:path";
+import { AgentPrefsPatchSchema, AgentRoleMapPatchSchema, CustomAgentRegisterRequestSchema, InterfMcpHandoffSchema, } from "../schemas/index.js";
+import { buildInterfMcpHandoff } from "../agent-handoff.js";
+import { buildLocalServiceUrl, LOCAL_SERVICE_ROUTES } from "./routes.js";
+import { decodeOr400, readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { packageRoot } from "./server-api-files.js";
+export async function tryHandleExecutor(req, res, runtime, path, method) {
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.executor) {
+        sendJson(res, 200, runtime.getExecutorStatus());
+        return true;
+    }
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.executor) {
+        const body = await readJsonBody(req);
+        sendJson(res, 202, runtime.selectExecutor(body));
+        return true;
+    }
+    return false;
+}
+export async function tryHandleAgents(req, res, runtime, path, method) {
+    if (path === LOCAL_SERVICE_ROUTES.agents) {
+        if (method === "GET") {
+            sendJson(res, 200, runtime.getAgentsRegistry());
+            return true;
+        }
+        if (method === "POST") {
+            try {
+                const body = CustomAgentRegisterRequestSchema.parse(await readJsonBody(req));
+                const updated = runtime.registerCustomAgent(body);
+                sendJson(res, 201, updated);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    if (method === "GET" && path === `${LOCAL_SERVICE_ROUTES.agents}/roles`) {
+        sendJson(res, 200, {
+            kind: "interf-canonical-roles",
+            version: 1,
+            roles: ["extractor", "summarizer", "structurer", "verifier", "general"],
+        });
+        return true;
+    }
+    if (method === "GET" && path === `${LOCAL_SERVICE_ROUTES.mcp}/connect`) {
+        const serviceUrl = buildLocalServiceUrl({ host: runtime.host, port: runtime.port });
+        const skillPath = join(packageRoot(), "public-repo", "skills", "interf", "SKILL.md");
+        const mcpBinPath = join(packageRoot(), "dist", "bin-mcp.js");
+        const mcpArgs = [mcpBinPath, "--profile", "app", "--url", serviceUrl];
+        if (runtime.authToken) {
+            mcpArgs.push("--token", runtime.authToken);
+        }
+        sendJson(res, 200, InterfMcpHandoffSchema.parse(buildInterfMcpHandoff({
+            serviceUrl,
+            authToken: runtime.authToken,
+            skillPath,
+            mcpCommand: process.execPath,
+            mcpArgs,
+        })));
+        return true;
+    }
+    if (path === `${LOCAL_SERVICE_ROUTES.agents}/role-map`) {
+        if (method === "GET") {
+            const registry = runtime.getAgentsRegistry();
+            sendJson(res, 200, {
+                role_map: registry.role_map,
+                active_agent: registry.active_agent,
+            });
+            return true;
+        }
+        if (method === "PATCH") {
+            try {
+                const patch = AgentRoleMapPatchSchema.parse(await readJsonBody(req));
+                const updated = runtime.patchAgentsRoleMap(patch);
+                sendJson(res, 200, updated);
+            }
+            catch (error) {
+                sendError(res, 400, error instanceof Error ? error.message : String(error));
+            }
+            return true;
+        }
+    }
+    // /v1/agents/<name> — DELETE removes a custom agent (built-in names
+    // return 400). PATCH updates the agent's stored prefs (env vars, model,
+    // effort) for built-ins or custom agents alike.
+    const agentMatch = path.match(/^\/v1\/agents\/([^/]+)$/);
+    if (agentMatch?.[1] && method === "DELETE") {
+        const name = decodeOr400(res, agentMatch[1], "Agent name");
+        if (name === null)
+            return true;
+        try {
+            const updated = runtime.unregisterCustomAgent(name);
+            sendJson(res, 200, updated);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const status = /built-in agent/.test(message) ? 400 : 404;
+            sendError(res, status, message);
+        }
+        return true;
+    }
+    if (agentMatch?.[1] && method === "PATCH") {
+        const name = decodeOr400(res, agentMatch[1], "Agent name");
+        if (name === null)
+            return true;
+        try {
+            const body = AgentPrefsPatchSchema.parse(await readJsonBody(req));
+            // Normalize the validated patch into the stored prefs shape, preserving
+            // the prior wire tolerance: an empty env_vars map is omitted, and a `""`
+            // or `null` model/effort clears that pref.
+            const prefs = {};
+            if ("env_vars" in body) {
+                const value = body.env_vars;
+                if (value && Object.keys(value).length > 0)
+                    prefs.env_vars = value;
+            }
+            if ("model" in body) {
+                prefs.model = body.model === "" ? null : body.model ?? null;
+            }
+            if ("effort" in body) {
+                prefs.effort = body.effort === "" ? null : body.effort ?? null;
+            }
+            const updated = runtime.setAgentPrefs(name, prefs);
+            sendJson(res, 200, updated);
+        }
+        catch (error) {
+            sendError(res, 400, error instanceof Error ? error.message : String(error));
+        }
+        return true;
+    }
+    return false;
+}

package/dist/packages/runtime/service/server-routes-auth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Auth routes for the desktop shell.
+ *
+ * The CLI's `interf auth login` command runs the loopback PKCE flow
+ * in-process and writes the session itself. The desktop app cannot do
+ * that — it is a Zero Native (Zig + WKWebView) binary with no Node
+ * runtime — so it asks the engine to run the same flow on its behalf
+ * and waits for the result.
+ *
+ * The flow is identical to the CLI path:
+ *
+ *   1. Engine binds a fresh loopback HTTP server on 127.0.0.1.
+ *   2. Engine asks WorkOS for a PKCE authorize URL bound to that
+ *      callback URL and opens the user's system browser at it.
+ *   3. User completes AuthKit; AuthKit redirects to the loopback
+ *      server with `?code=...&state=...`.
+ *   4. Engine exchanges the code for tokens, writes the refresh token
+ *      to the keychain, writes `~/.interf/auth/session.json`, and
+ *      updates `runtime.currentAccount` so any subsequent `/v1/me` GET
+ *      reflects the new identity without an engine restart.
+ *
+ * The POST that triggers all this is long-running by design — the
+ * response is sent only after AuthKit has roundtripped. The UI calls
+ * it with a generous timeout and shows a spinner.
+ *
+ * `interf://` URL scheme handling is intentionally NOT used here. The
+ * loopback flow is platform-agnostic and reuses the CLI's well-tested
+ * orchestration; the deep-link path adds an Info.plist /
+ * NSAppleEventManager hop that zero-native 0.1.9 does not register.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function tryHandleAuth(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-auth.js

@@ -0,0 +1,138 @@
+/**
+ * Auth routes for the desktop shell.
+ *
+ * The CLI's `interf auth login` command runs the loopback PKCE flow
+ * in-process and writes the session itself. The desktop app cannot do
+ * that — it is a Zero Native (Zig + WKWebView) binary with no Node
+ * runtime — so it asks the engine to run the same flow on its behalf
+ * and waits for the result.
+ *
+ * The flow is identical to the CLI path:
+ *
+ *   1. Engine binds a fresh loopback HTTP server on 127.0.0.1.
+ *   2. Engine asks WorkOS for a PKCE authorize URL bound to that
+ *      callback URL and opens the user's system browser at it.
+ *   3. User completes AuthKit; AuthKit redirects to the loopback
+ *      server with `?code=...&state=...`.
+ *   4. Engine exchanges the code for tokens, writes the refresh token
+ *      to the keychain, writes `~/.interf/auth/session.json`, and
+ *      updates `runtime.currentAccount` so any subsequent `/v1/me` GET
+ *      reflects the new identity without an engine restart.
+ *
+ * The POST that triggers all this is long-running by design — the
+ * response is sent only after AuthKit has roundtripped. The UI calls
+ * it with a generous timeout and shows a spinner.
+ *
+ * `interf://` URL scheme handling is intentionally NOT used here. The
+ * loopback flow is platform-agnostic and reuses the CLI's well-tested
+ * orchestration; the deep-link path adds an Info.plist /
+ * NSAppleEventManager hop that zero-native 0.1.9 does not register.
+ */
+import { AuthFlowError, defaultPkceTransport, runPkceFlow, } from "../auth/auth-flow.js";
+import { entitlementsForPlan } from "../auth/account-context.js";
+import { deleteRefreshToken, setRefreshToken, } from "../auth/keychain.js";
+import { clearSession, writeSession, } from "../auth/session-store.js";
+import { WorkOSConfigError } from "../auth/workos-client.js";
+import { LOCAL_SERVICE_ROUTES } from "./routes.js";
+import { readJsonBody, sendError, sendErrorResponse, sendJson, } from "./server-helpers.js";
+const AUTH_LOGIN_PATH = `${LOCAL_SERVICE_ROUTES.auth}/login`;
+const AUTH_LOGOUT_PATH = `${LOCAL_SERVICE_ROUTES.auth}/logout`;
+export async function tryHandleAuth(req, res, runtime, path, method) {
+    if (method !== "POST")
+        return false;
+    if (path === AUTH_LOGIN_PATH) {
+        await handleLogin(req, res, runtime);
+        return true;
+    }
+    if (path === AUTH_LOGOUT_PATH) {
+        await handleLogout(req, res, runtime);
+        return true;
+    }
+    return false;
+}
+async function handleLogin(req, res, runtime) {
+    let body = {};
+    try {
+        const raw = await readJsonBody(req);
+        if (raw && typeof raw === "object")
+            body = raw;
+    }
+    catch {
+        // Empty/invalid body is fine — login takes no required input.
+    }
+    try {
+        const result = await runPkceFlow(defaultPkceTransport(), {
+            autoOpenBrowser: body.open_browser ?? true,
+            ...(body.login_hint ? { loginHint: body.login_hint } : {}),
+        });
+        try {
+            await setRefreshToken(result.user.id, result.refreshToken);
+        }
+        catch {
+            // Keychain failure is non-fatal — the session still works for
+            // the current process. The user will be prompted again after
+            // the next engine restart.
+        }
+        const refreshedAt = new Date().toISOString();
+        const plan = "free";
+        const displayName = [result.user.firstName, result.user.lastName]
+            .filter((part) => typeof part === "string" && part.length > 0)
+            .join(" ") || null;
+        const account = {
+            user_id: result.user.id,
+            email: result.user.email,
+            display_name: displayName,
+            plan,
+            entitlements: entitlementsForPlan(plan),
+            refreshed_at: refreshedAt,
+        };
+        writeSession(account);
+        runtime.currentAccount = account;
+        sendJson(res, 200, {
+            kind: "interf-auth-login",
+            version: 1,
+            account: {
+                user_id: account.user_id,
+                email: account.email,
+                display_name: account.display_name,
+                plan: account.plan,
+                entitlements: {
+                    max_active_projects: Number.isFinite(account.entitlements.max_active_projects)
+                        ? account.entitlements.max_active_projects
+                        : null,
+                    pro_features: account.entitlements.pro_features,
+                },
+                refreshed_at: account.refreshed_at,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof WorkOSConfigError) {
+            sendError(res, 503, error.message);
+            return;
+        }
+        if (error instanceof AuthFlowError) {
+            sendError(res, 400, `Sign-in failed: ${error.message}`);
+            return;
+        }
+        sendErrorResponse(res, error, 500);
+    }
+}
+async function handleLogout(_req, res, runtime) {
+    const previous = runtime.currentAccount;
+    if (previous) {
+        try {
+            await deleteRefreshToken(previous.user_id);
+        }
+        catch {
+            // Best-effort cleanup; the on-disk session below is the
+            // authoritative signal.
+        }
+    }
+    clearSession();
+    runtime.currentAccount = null;
+    sendJson(res, 200, {
+        kind: "interf-auth-logout",
+        version: 1,
+    });
+}

package/dist/packages/runtime/service/server-routes-build-plans.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function tryHandleBuildPlans(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-build-plans.js

@@ -0,0 +1,86 @@
+import { BuildPlanSaveRequestSchema } from "../schemas/index.js";
+import { LOCAL_SERVICE_ROUTES } from "./routes.js";
+import { decodeOr400, readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { isTraversalRelativePath, safeApiFilePath, sendApiFile, } from "./server-api-files.js";
+import { findInstanceBuildPlan, listInstanceBuildPlanRuns, listInstanceBuildPlans, resolveInstanceBuildPlanPackageRoot, } from "./server-instance-helpers.js";
+import { installUserBuildPlan } from "../../build-plans/package/user-build-plans.js";
+export async function tryHandleBuildPlans(req, res, runtime, path, method) {
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.buildPlans) {
+        sendJson(res, 200, { build_plans: listInstanceBuildPlans(runtime) });
+        return true;
+    }
+    if (method === "POST" && path === LOCAL_SERVICE_ROUTES.buildPlans) {
+        try {
+            const body = BuildPlanSaveRequestSchema.parse(await readJsonBody(req));
+            const installed = installUserBuildPlan({
+                sourceDir: body.source_path,
+                id: body.id,
+                overwrite: body.overwrite,
+            });
+            sendJson(res, 201, {
+                build_plan_id: installed.id,
+                installed: true,
+                path: installed.path,
+            });
+        }
+        catch (error) {
+            sendError(res, 400, error instanceof Error ? error.message : String(error));
+        }
+        return true;
+    }
+    const buildPlanMatch = path.match(/^\/v1\/build-plans\/([^/]+)$/);
+    if (method === "GET" && buildPlanMatch?.[1]) {
+        const buildPlanId = decodeOr400(res, buildPlanMatch[1], "Build Plan id");
+        if (buildPlanId === null)
+            return true;
+        const buildPlanResource = findInstanceBuildPlan(runtime, buildPlanId);
+        if (!buildPlanResource)
+            sendError(res, 404, "Build Plan not found.");
+        else
+            sendJson(res, 200, buildPlanResource);
+        return true;
+    }
+    const buildPlanRunsMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/runs$/);
+    if (method === "GET" && buildPlanRunsMatch?.[1]) {
+        const buildPlanId = decodeOr400(res, buildPlanRunsMatch[1], "Build Plan id");
+        if (buildPlanId === null)
+            return true;
+        const runs = listInstanceBuildPlanRuns(runtime, buildPlanId);
+        sendJson(res, 200, { runs });
+        return true;
+    }
+    // GET /v1/build-plans/<id>/files/<relpath> — read-only file serving inside
+    // the Build Plan package root. Used by the locator pattern's `api-served` kind so
+    // the UI can render SKILL.md / contract files in a side drawer over a
+    // remote engine. Resolution: project-draft (when first project exists) →
+    // user library → built-in. Path-guard rejects any traversal outside
+    // the resolved root.
+    const buildPlanFilesMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/files\/(.+)$/);
+    if (method === "GET" && buildPlanFilesMatch?.[1] && buildPlanFilesMatch[2]) {
+        const buildPlanId = decodeOr400(res, buildPlanFilesMatch[1], "Build Plan id");
+        if (buildPlanId === null)
+            return true;
+        const relPath = decodeOr400(res, buildPlanFilesMatch[2], "File path");
+        if (relPath === null)
+            return true;
+        if (isTraversalRelativePath(relPath)) {
+            sendError(res, 400, "File path escapes Build Plan root.");
+            return true;
+        }
+        const root = resolveInstanceBuildPlanPackageRoot(runtime, buildPlanId);
+        if (!root) {
+            sendError(res, 404, `Build Plan not found: ${buildPlanId}`);
+            return true;
+        }
+        const safePath = safeApiFilePath(root, relPath);
+        if (!safePath) {
+            sendError(res, 400, "File path escapes Build Plan root.");
+            return true;
+        }
+        if (!sendApiFile(res, safePath)) {
+            sendError(res, 404, `File not found: ${relPath}`);
+        }
+        return true;
+    }
+    return false;
+}

package/dist/packages/runtime/service/server-routes-discovery.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+export declare function tryHandleDiscovery(_req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): boolean;
+export declare function tryHandleOpenPath(req: IncomingMessage, res: ServerResponse, _runtime: LocalServiceRuntime, path: string, method: string): Promise<boolean>;

package/dist/packages/runtime/service/server-routes-discovery.js

@@ -0,0 +1,196 @@
+import { LOCAL_SERVICE_LOOPBACK_HOSTS, LocalServiceDiscoverySchema, OpenPathRequestSchema, } from "../schemas/index.js";
+import { buildLocalServiceUrl, LOCAL_SERVICE_ROUTES, } from "./routes.js";
+import { buildOpenApiDocument } from "./openapi.js";
+import { readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { packageRoot, } from "./server-api-files.js";
+import { listStoredProjects } from "../project-store.js";
+import { userBuildPlansRoot } from "../../contracts/lib/project-paths.js";
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { assertPathWithinRoot } from "../../contracts/utils/path-guards.js";
+export function tryHandleDiscovery(_req, res, runtime, path, method) {
+    // GET /health — liveness probe used by the CLI bootstrap.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.health) {
+        sendJson(res, 200, runtime.health());
+        return true;
+    }
+    // GET /v1 — discovery list of available resources.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.api) {
+        sendJson(res, 200, LocalServiceDiscoverySchema.parse({
+            kind: "interf-local-service-discovery",
+            version: 1,
+            resources: {
+                instance: LOCAL_SERVICE_ROUTES.instance,
+                projects: LOCAL_SERVICE_ROUTES.projects,
+                build_plans: LOCAL_SERVICE_ROUTES.buildPlans,
+                runs: LOCAL_SERVICE_ROUTES.runs,
+                openapi: LOCAL_SERVICE_ROUTES.openapi,
+                action_proposals: LOCAL_SERVICE_ROUTES.actionProposals,
+                executor: LOCAL_SERVICE_ROUTES.executor,
+                agents: LOCAL_SERVICE_ROUTES.agents,
+                me: LOCAL_SERVICE_ROUTES.me,
+                open_path: LOCAL_SERVICE_ROUTES.openPath,
+            },
+        }));
+        return true;
+    }
+    // GET /v1/openapi.json — human-readable API contract generated from the
+    // same operation registry used by clients and tools.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.openapi) {
+        sendJson(res, 200, buildOpenApiDocument({
+            version: runtime.packageVersion ?? "0.1.0",
+        }));
+        return true;
+    }
+    // GET /v1/me — current account / session.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.me) {
+        if (runtime.currentAccount) {
+            sendJson(res, 200, {
+                kind: "interf-current-account",
+                version: 1,
+                user_id: runtime.currentAccount.user_id,
+                email: runtime.currentAccount.email,
+                display_name: runtime.currentAccount.display_name,
+                plan: runtime.currentAccount.plan,
+                entitlements: {
+                    max_active_projects: Number.isFinite(runtime.currentAccount.entitlements.max_active_projects)
+                        ? runtime.currentAccount.entitlements.max_active_projects
+                        : null,
+                    pro_features: runtime.currentAccount.entitlements.pro_features,
+                },
+                refreshed_at: runtime.currentAccount.refreshed_at,
+            });
+        }
+        else {
+            sendJson(res, 200, {
+                kind: "interf-current-account",
+                version: 1,
+                user_id: null,
+                email: null,
+                display_name: null,
+                plan: "anonymous",
+                entitlements: {
+                    max_active_projects: 10,
+                    pro_features: [],
+                },
+                refreshed_at: null,
+            });
+        }
+        return true;
+    }
+    // GET /v1/instance — local service metadata.
+    if (method === "GET" && path === LOCAL_SERVICE_ROUTES.instance) {
+        const startedAtIso = runtime.startedAt ?? new Date().toISOString();
+        const startedMs = Date.parse(startedAtIso);
+        const uptimeSeconds = Number.isFinite(startedMs)
+            ? Math.max(0, Math.floor((Date.now() - startedMs) / 1000))
+            : 0;
+        const agentState = runtime.getAgentsRegistry();
+        // `connection_kind` lets the UI know whether OS-open is even
+        // possible. A loopback bind means the local service has filesystem access
+        // to the same host as the user; non-loopback (cloud) returns
+        // "remote" so the UI routes to api-served / signed-URL paths
+        // instead. The current binary refuses non-loopback binds (see the
+        // host whitelist below), so the value is "local" today; the field
+        // is in place so the UI can read it without a CLI version sniff.
+        const isLoopback = LOCAL_SERVICE_LOOPBACK_HOSTS.includes(runtime.host);
+        const health = runtime.health();
+        sendJson(res, 200, {
+            kind: "interf-instance",
+            version: 1,
+            url: buildLocalServiceUrl({ host: runtime.host, port: runtime.port }),
+            host: runtime.host,
+            port: runtime.port,
+            pid: process.pid,
+            started_at: startedAtIso,
+            uptime_seconds: uptimeSeconds,
+            package_version: runtime.packageVersion ?? null,
+            project_count: listStoredProjects().length,
+            active_run_count: health.active_runs,
+            idle_for_seconds: health.idle_for_seconds,
+            auth_required: Boolean(runtime.authToken),
+            owner_kind: runtime.ownerKind,
+            ...(runtime.ownerPid ? { owner_pid: runtime.ownerPid } : {}),
+            // connected-agents fields:
+            agent_count: agentState.agents.length,
+            default_agent: agentState.active_agent?.name ?? null,
+            // connection-mode flag:
+            connection_kind: isLoopback ? "local" : "remote",
+        });
+        return true;
+    }
+    return false;
+}
+function resolveOpenPath(allowedRoots, pathValue) {
+    const roots = allowedRoots.map((root) => resolve(root));
+    const targetPath = resolve(pathValue);
+    for (const root of roots) {
+        try {
+            return assertPathWithinRoot(root, targetPath, "Open path");
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error(`Open path must stay inside ${roots.join(" or ")}: ${targetPath}`);
+}
+async function openLocalPath(allowedRoots, pathValue) {
+    const targetPath = resolveOpenPath(allowedRoots, pathValue);
+    if (!existsSync(targetPath)) {
+        throw new Error(`Path does not exist: ${targetPath}`);
+    }
+    if (process.env.INTERF_OPEN_PATH_DRY_RUN === "1") {
+        return targetPath;
+    }
+    const isDirectory = statSync(targetPath).isDirectory();
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "explorer.exe"
+            : "xdg-open";
+    const args = process.platform === "darwin"
+        ? (isDirectory ? [targetPath] : ["-R", targetPath])
+        : process.platform === "win32"
+            ? (isDirectory ? [targetPath] : ["/select,", targetPath])
+            : [isDirectory ? targetPath : dirname(targetPath)];
+    await new Promise((resolveOpen, rejectOpen) => {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", rejectOpen);
+        child.once("spawn", () => {
+            child.unref();
+            resolveOpen();
+        });
+    });
+    return targetPath;
+}
+export async function tryHandleOpenPath(req, res, _runtime, path, method) {
+    if (!(method === "POST" && path === LOCAL_SERVICE_ROUTES.openPath)) {
+        return false;
+    }
+    try {
+        const body = OpenPathRequestSchema.parse(await readJsonBody(req));
+        // Permit opening:
+        //  - any registered project root or its bound source folder
+        //  - the user buildPlan library at `~/.interf/build-plans/`
+        //  - the bundled built-in buildPlan root inside the installed package
+        //    (so SKILL.md / contract files in `interf-default` open correctly)
+        const allowedRoots = [];
+        for (const stored of listStoredProjects()) {
+            allowedRoots.push(stored.projectDataDir);
+            if (stored.source.locator)
+                allowedRoots.push(stored.source.locator);
+        }
+        allowedRoots.push(userBuildPlansRoot());
+        allowedRoots.push(packageRoot()); // covers <pkg>/public-repo/build-plans/...
+        const openedPath = await openLocalPath(allowedRoots, body.path);
+        sendJson(res, 202, { opened: true, path: openedPath });
+    }
+    catch (error) {
+        sendError(res, 400, error instanceof Error ? error.message : String(error));
+    }
+    return true;
+}

package/dist/packages/runtime/service/server-routes-events.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LocalServiceRuntime } from "../runtime.js";
+/** Fan a change ping out to every open events stream for this runtime. */
+export declare function notifyServiceChange(runtime: LocalServiceRuntime): void;
+export declare function tryHandleEvents(req: IncomingMessage, res: ServerResponse, runtime: LocalServiceRuntime, path: string, method: string): boolean;