@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/schemas/context-graphs.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { ArtifactRefSchema, } from "../execution/lib/schema.js";
+import { BuildPlanIdSchema, BuildEvidenceResourceSchema, GraphManifestSchema, GraphManifestStageSummarySchema, GraphReadinessRollupSchema, MetricCountSchema, ProjectIntentSchema, ProjectIdSchema, ReadinessSchema, ResourceRefSchema, } from "../../contracts/lib/schema.js";
+import { ContextGraphArtifactHandoffSchema, ContextGraphPortableHandoffSchema, } from "../../contracts/lib/project-schema.js";
+import { StageExecutionSessionSchema, } from "../build/lib/schema.js";
+export const ContextGraphSemanticNodeKindSchema = z.enum([
+    "project",
+    "home",
+    "claim",
+    "entity",
+    "index",
+    "knowledge",
+    "summary",
+    "artifact",
+    "source",
+    "note",
+]);
+export const ContextGraphSemanticEdgeKindSchema = z.enum([
+    "links-to",
+    "source-ref",
+    "contains",
+    "handoff",
+]);
+export const ContextGraphSemanticNodeSchema = z.object({
+    id: z.string().min(1),
+    kind: ContextGraphSemanticNodeKindSchema,
+    label: z.string().min(1),
+    path: z.string().min(1).nullable().optional(),
+    summary: z.string().min(1).nullable().optional(),
+    source_refs: z.array(z.string().min(1)).default([]),
+    link_count: z.number().int().nonnegative().default(0),
+    backlink_count: z.number().int().nonnegative().default(0),
+}).strict();
+export const ContextGraphSemanticEdgeSchema = z.object({
+    id: z.string().min(1),
+    kind: ContextGraphSemanticEdgeKindSchema,
+    source: z.string().min(1),
+    target: z.string().min(1),
+    label: z.string().min(1),
+    detail: z.string().min(1),
+}).strict();
+export const ContextGraphSemanticGraphSchema = z.object({
+    kind: z.literal("interf-context-graph-semantic-graph"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    nodes: z.array(ContextGraphSemanticNodeSchema),
+    edges: z.array(ContextGraphSemanticEdgeSchema),
+    stats: z.object({
+        notes: z.number().int().nonnegative(),
+        links: z.number().int().nonnegative(),
+        source_refs: z.number().int().nonnegative(),
+        unresolved_links: z.number().int().nonnegative(),
+    }).strict(),
+}).strict();
+export const ContextGraphResourceSchema = z.object({
+    kind: z.literal("interf-context-graph"),
+    version: z.literal(1),
+    graph_id: z.string().min(1).optional(),
+    project_id: ProjectIdSchema.optional(),
+    intent: ProjectIntentSchema,
+    build_run_id: z.string().min(1).nullable().optional(),
+    source_manifest_id: z.string().min(1).nullable().optional(),
+    created_at: z.string().min(1).optional(),
+    is_latest: z.boolean().optional(),
+    project: ProjectIdSchema,
+    path: z.string().min(1),
+    exists: z.boolean(),
+    readiness: ReadinessSchema,
+    build_plan: BuildPlanIdSchema.nullable().optional(),
+    latest_build_run_id: z.string().min(1).nullable().optional(),
+    latest_benchmark_run_id: z.string().min(1).nullable().optional(),
+    // COMPAT — entrypoint_artifact / artifact_handoffs / artifacts / build_evidence /
+    // semantic_graph are pre-refactor handoff fields. Primary handlers populate
+    // entrypoints + resources + graph_manifest + primary_metrics + readiness_rollup
+    // instead. Removal trigger: once no live client reads these legacy fields,
+    // drop them from this schema and ContextGraphResource.
+    entrypoint_artifact: ContextGraphArtifactHandoffSchema.nullable().optional(),
+    artifact_handoffs: z.array(ContextGraphArtifactHandoffSchema).default([]),
+    portable_handoff: ContextGraphPortableHandoffSchema.nullable().optional(),
+    artifacts: z.array(ArtifactRefSchema).default([]),
+    build_evidence: BuildEvidenceResourceSchema.optional(),
+    semantic_graph: ContextGraphSemanticGraphSchema.optional(),
+    graph_manifest: GraphManifestSchema.nullable().optional(),
+    primary_metrics: z.array(MetricCountSchema).default([]),
+    stage_summaries: z.array(GraphManifestStageSummarySchema).default([]),
+    entrypoints: z.array(ResourceRefSchema).default([]),
+    resources: z.array(ResourceRefSchema).default([]),
+    readiness_rollup: GraphReadinessRollupSchema.nullable().optional(),
+    stage_sessions: z.array(StageExecutionSessionSchema).default([]),
+}).strict();
+export const ContextGraphListResponseSchema = z.object({
+    graphs: z.array(ContextGraphResourceSchema),
+}).strict();
+/**
+ * `GET /v1/projects/<id>/context-graph/sessions` — the replayable per-stage
+ * execution shell sessions for the latest Build run. One shape, reused by the
+ * service operation registry, the CLI `graphs sessions` reader, and MCP.
+ */
+export const ContextGraphSessionsResponseSchema = z.object({
+    sessions: z.array(StageExecutionSessionSchema),
+}).strict();
+/**
+ * `GET /v1/projects/<id>/context-graph/sessions/<stage-run-id>` — one preserved
+ * execution shell session. Same single-session shape across service, CLI, MCP.
+ */
+export const ContextGraphSessionResponseSchema = z.object({
+    session: StageExecutionSessionSchema,
+}).strict();
+export { BuildEvidenceResourceSchema };
+export { StageExecutionSessionSchema };

package/dist/packages/runtime/schemas/files.d.ts

@@ -0,0 +1,227 @@
+import { z } from "zod";
+/**
+ * Discriminated locator for an artifact returned by the API. Aliases the
+ * canonical `LocatorSchema` from contracts so all three kinds —
+ * `local-path`, `remote-url`, `api-served` — flow through the same
+ * resource-access pattern.
+ */
+export declare const ArtifactLocatorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "local-path": "local-path";
+        "remote-url": "remote-url";
+        "api-served": "api-served";
+    }>;
+    value: z.ZodString;
+}, z.core.$strict>;
+export declare const ReadinessResourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-readiness-state">;
+    version: z.ZodLiteral<1>;
+    generated_at: z.ZodString;
+    project: z.ZodString;
+    status: z.ZodEnum<{
+        ready: "ready";
+        "not-ready": "not-ready";
+        failed: "failed";
+        "not-configured": "not-configured";
+        "not-built": "not-built";
+        building: "building";
+        built: "built";
+        checking: "checking";
+        stale: "stale";
+    }>;
+    ready: z.ZodBoolean;
+    summary: z.ZodString;
+    context_graph_path: z.ZodNullable<z.ZodString>;
+    latest_build_run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    latest_benchmark_run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    build: z.ZodNullable<z.ZodObject<{
+        gate: z.ZodEnum<{
+            "context-graph": "context-graph";
+            "project-config": "project-config";
+            "build-run": "build-run";
+            "artifact-diagnostics": "artifact-diagnostics";
+            "context-checks": "context-checks";
+            benchmarks: "benchmarks";
+            "benchmarks-current": "benchmarks-current";
+        }>;
+        ok: z.ZodBoolean;
+        status: z.ZodOptional<z.ZodEnum<{
+            ready: "ready";
+            "not-ready": "not-ready";
+            failed: "failed";
+            "not-configured": "not-configured";
+            "not-built": "not-built";
+            building: "building";
+            built: "built";
+            checking: "checking";
+            stale: "stale";
+        }>>;
+        summary: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        artifact_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>;
+    check_results: z.ZodObject<{
+        configured: z.ZodNumber;
+        fingerprint: z.ZodNullable<z.ZodString>;
+        source_files: z.ZodNullable<z.ZodObject<{
+            passed: z.ZodNumber;
+            total: z.ZodNumber;
+            pass_rate: z.ZodNullable<z.ZodNumber>;
+            checks_fingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            stale: z.ZodDefault<z.ZodBoolean>;
+            run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            run_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>>;
+        context_graph: z.ZodNullable<z.ZodObject<{
+            passed: z.ZodNumber;
+            total: z.ZodNumber;
+            pass_rate: z.ZodNullable<z.ZodNumber>;
+            checks_fingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            stale: z.ZodDefault<z.ZodBoolean>;
+            run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            run_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        gate: z.ZodEnum<{
+            "context-graph": "context-graph";
+            "project-config": "project-config";
+            "build-run": "build-run";
+            "artifact-diagnostics": "artifact-diagnostics";
+            "context-checks": "context-checks";
+            benchmarks: "benchmarks";
+            "benchmarks-current": "benchmarks-current";
+        }>;
+        ok: z.ZodBoolean;
+        status: z.ZodOptional<z.ZodEnum<{
+            ready: "ready";
+            "not-ready": "not-ready";
+            failed: "failed";
+            "not-configured": "not-configured";
+            "not-built": "not-built";
+            building: "building";
+            built: "built";
+            checking: "checking";
+            stale: "stale";
+        }>>;
+        summary: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        artifact_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const SourceFileResourceSchema: z.ZodObject<{
+    project: z.ZodString;
+    source_manifest_id: z.ZodOptional<z.ZodString>;
+    source_file_id: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    locator: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        image: "image";
+        pdf: "pdf";
+        document: "document";
+        spreadsheet: "spreadsheet";
+        presentation: "presentation";
+        text: "text";
+        other: "other";
+    }>>;
+    absolute_path: z.ZodString;
+    size_bytes: z.ZodNumber;
+    modified_at: z.ZodNullable<z.ZodString>;
+    source_folder_path: z.ZodString;
+}, z.core.$strict>;
+export declare const SourceFileListResponseSchema: z.ZodObject<{
+    source_files: z.ZodArray<z.ZodObject<{
+        project: z.ZodString;
+        source_manifest_id: z.ZodOptional<z.ZodString>;
+        source_file_id: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        locator: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            image: "image";
+            pdf: "pdf";
+            document: "document";
+            spreadsheet: "spreadsheet";
+            presentation: "presentation";
+            text: "text";
+            other: "other";
+        }>>;
+        absolute_path: z.ZodString;
+        size_bytes: z.ZodNumber;
+        modified_at: z.ZodNullable<z.ZodString>;
+        source_folder_path: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const SourceManifestResourceSchema: z.ZodObject<{
+    source_manifest: z.ZodObject<{
+        kind: z.ZodLiteral<"interf-source-manifest">;
+        version: z.ZodLiteral<1>;
+        manifest_id: z.ZodString;
+        generated_at: z.ZodString;
+        run_id: z.ZodNullable<z.ZodString>;
+        project: z.ZodString;
+        source: z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                "local-folder": "local-folder";
+            }>;
+            locator: z.ZodString;
+        }, z.core.$strict>;
+        scanner: z.ZodObject<{
+            executor: z.ZodString;
+            agent_label: z.ZodString;
+            attempt: z.ZodNumber;
+        }, z.core.$strict>;
+        source_total: z.ZodNumber;
+        files: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            locator: z.ZodString;
+            path: z.ZodString;
+            kind: z.ZodDefault<z.ZodEnum<{
+                image: "image";
+                pdf: "pdf";
+                document: "document";
+                spreadsheet: "spreadsheet";
+                presentation: "presentation";
+                text: "text";
+                other: "other";
+            }>>;
+            size_bytes: z.ZodOptional<z.ZodNumber>;
+            content_hash: z.ZodOptional<z.ZodString>;
+            page_count: z.ZodOptional<z.ZodNumber>;
+            inspectable_units: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    file: "file";
+                    page: "page";
+                    slide: "slide";
+                    sheet: "sheet";
+                    table: "table";
+                    image: "image";
+                    section: "section";
+                }>;
+                index: z.ZodOptional<z.ZodNumber>;
+                label: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            confidence: z.ZodDefault<z.ZodEnum<{
+                high: "high";
+                medium: "medium";
+                low: "low";
+            }>>;
+            evidence: z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    "agent-observation": "agent-observation";
+                    "connector-metadata": "connector-metadata";
+                    "user-provided": "user-provided";
+                }>;
+                summary: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ArtifactLocator = z.infer<typeof ArtifactLocatorSchema>;
+export type ReadinessResource = z.infer<typeof ReadinessResourceSchema>;
+export type SourceFileResource = z.infer<typeof SourceFileResourceSchema>;
+export type SourceFileListResponse = z.infer<typeof SourceFileListResponseSchema>;
+export type SourceManifestResource = z.infer<typeof SourceManifestResourceSchema>;

package/dist/packages/runtime/schemas/files.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { LocatorSchema, ProjectIdSchema, ReadinessSchema, SourceManifestSchema, SourceManifestFileKindSchema, } from "../../contracts/lib/schema.js";
+/**
+ * Discriminated locator for an artifact returned by the API. Aliases the
+ * canonical `LocatorSchema` from contracts so all three kinds —
+ * `local-path`, `remote-url`, `api-served` — flow through the same
+ * resource-access pattern.
+ */
+export const ArtifactLocatorSchema = LocatorSchema;
+export const ReadinessResourceSchema = ReadinessSchema;
+export const SourceFileResourceSchema = z.object({
+    project: ProjectIdSchema,
+    source_manifest_id: z.string().min(1).optional(),
+    source_file_id: z.string().min(1).optional(),
+    path: z.string().min(1),
+    locator: z.string().min(1).optional(),
+    kind: SourceManifestFileKindSchema.optional(),
+    absolute_path: z.string().min(1),
+    size_bytes: z.number().int().min(0),
+    modified_at: z.string().min(1).nullable(),
+    source_folder_path: z.string().min(1),
+}).strict();
+export const SourceFileListResponseSchema = z.object({
+    source_files: z.array(SourceFileResourceSchema),
+}).strict();
+export const SourceManifestResourceSchema = z.object({
+    source_manifest: SourceManifestSchema,
+}).strict();

package/dist/packages/runtime/schemas/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./context-graphs.js";
+export * from "./files.js";
+export * from "./instance.js";
+export * from "./projects.js";
+export * from "./build-plans.js";
+export * from "./jobs.js";
+export * from "./agents.js";
+export * from "./runs.js";
+export * from "./actions.js";

package/dist/packages/runtime/schemas/index.js

@@ -0,0 +1,13 @@
+// Aggregate barrel for engine API resource schemas. Re-exports only;
+// no schemas are defined here. Prefer importing directly from a
+// resource module (e.g. `./projects.js`) when a single file
+// needs only a few shapes.
+export * from "./context-graphs.js";
+export * from "./files.js";
+export * from "./instance.js";
+export * from "./projects.js";
+export * from "./build-plans.js";
+export * from "./jobs.js";
+export * from "./agents.js";
+export * from "./runs.js";
+export * from "./actions.js";

package/dist/packages/runtime/schemas/instance.d.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+/** Per-instance metadata from `GET /v1/instance` (replaces /v1/status). */
+export declare const InstanceResourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-instance">;
+    version: z.ZodLiteral<1>;
+    url: z.ZodString;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    pid: z.ZodOptional<z.ZodNumber>;
+    started_at: z.ZodString;
+    uptime_seconds: z.ZodOptional<z.ZodNumber>;
+    package_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    project_count: z.ZodNumber;
+    active_run_count: z.ZodNumber;
+    idle_for_seconds: z.ZodNumber;
+    auth_required: z.ZodBoolean;
+    owner_kind: z.ZodOptional<z.ZodEnum<{
+        "desktop-app": "desktop-app";
+        headless: "headless";
+    }>>;
+    owner_pid: z.ZodOptional<z.ZodNumber>;
+    agent_count: z.ZodOptional<z.ZodNumber>;
+    default_agent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    connection_kind: z.ZodOptional<z.ZodEnum<{
+        local: "local";
+        remote: "remote";
+    }>>;
+}, z.core.$strict>;
+/**
+ * The local service must only ever bind to a loopback interface. Any other
+ * host (LAN IP, 0.0.0.0, public address) lets a remote browser tab POST at
+ * the service, which is the CSRF model we are explicitly rejecting. Keep
+ * the allowlist literal — refactoring to a `.refine()` over `z.string()`
+ * would lose the static type narrowing.
+ */
+export declare const LOCAL_SERVICE_LOOPBACK_HOSTS: readonly ["127.0.0.1", "localhost", "::1"];
+export declare const LocalServiceHostSchema: z.ZodString;
+export declare const LocalServicePortSchema: z.ZodNumber;
+/**
+ * Per-instance bearer token. Generated at startup with crypto.randomBytes(32)
+ * and rendered as a 64-char hex string. Any deviation should fail validation
+ * loud and early.
+ */
+export declare const LocalServiceAuthTokenSchema: z.ZodString;
+export declare const LocalServiceConfigSchema: z.ZodObject<{
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const ServiceRegistryEntrySchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    url: z.ZodString;
+    started_at: z.ZodString;
+    owner_kind: z.ZodOptional<z.ZodEnum<{
+        "desktop-app": "desktop-app";
+        headless: "headless";
+    }>>;
+    owner_pid: z.ZodOptional<z.ZodNumber>;
+    auth_token: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const ServiceRegistrySchema: z.ZodObject<{
+    services: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        pid: z.ZodNumber;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        url: z.ZodString;
+        started_at: z.ZodString;
+        owner_kind: z.ZodOptional<z.ZodEnum<{
+            "desktop-app": "desktop-app";
+            headless: "headless";
+        }>>;
+        owner_pid: z.ZodOptional<z.ZodNumber>;
+        auth_token: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const LocalServiceHealthSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-local-service-health">;
+    version: z.ZodLiteral<1>;
+    status: z.ZodLiteral<"ok">;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    service_url: z.ZodString;
+    control_path: z.ZodOptional<z.ZodString>;
+    source_folder_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    started_at: z.ZodOptional<z.ZodString>;
+    package_version: z.ZodOptional<z.ZodString>;
+    instance_started_at: z.ZodOptional<z.ZodString>;
+    active_runs: z.ZodDefault<z.ZodNumber>;
+    idle_for_seconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const LocalServiceErrorSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        message: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        upgrade_hint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const LocalServiceDiscoverySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-local-service-discovery">;
+    version: z.ZodLiteral<1>;
+    resources: z.ZodObject<{
+        instance: z.ZodString;
+        projects: z.ZodString;
+        build_plans: z.ZodString;
+        runs: z.ZodString;
+        openapi: z.ZodOptional<z.ZodString>;
+        action_proposals: z.ZodString;
+        executor: z.ZodString;
+        open_path: z.ZodString;
+        agents: z.ZodOptional<z.ZodString>;
+        me: z.ZodOptional<z.ZodString>;
+        readiness: z.ZodOptional<z.ZodString>;
+        source_files: z.ZodOptional<z.ZodString>;
+        project_setups: z.ZodOptional<z.ZodString>;
+        project_changes: z.ZodOptional<z.ZodString>;
+        build_plan_changes: z.ZodOptional<z.ZodString>;
+        benchmark_question_drafts: z.ZodOptional<z.ZodString>;
+        build_plan_draft_runs: z.ZodOptional<z.ZodString>;
+        build_plan_improvement_runs: z.ZodOptional<z.ZodString>;
+        verify_runs: z.ZodOptional<z.ZodString>;
+        reset: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const OpenPathRequestSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strict>;
+export declare const OpenPathResponseSchema: z.ZodObject<{
+    opened: z.ZodBoolean;
+    path: z.ZodString;
+}, z.core.$strict>;
+export type InstanceResource = z.infer<typeof InstanceResourceSchema>;
+export type LocalServiceConfig = z.infer<typeof LocalServiceConfigSchema>;
+export type LocalServiceError = z.infer<typeof LocalServiceErrorSchema>;
+export type LocalServiceHealth = z.infer<typeof LocalServiceHealthSchema>;
+export type LocalServiceAuthToken = z.infer<typeof LocalServiceAuthTokenSchema>;
+export type LocalServiceDiscovery = z.infer<typeof LocalServiceDiscoverySchema>;
+export type OpenPathRequest = z.infer<typeof OpenPathRequestSchema>;
+export type OpenPathResponse = z.infer<typeof OpenPathResponseSchema>;
+export type ServiceRegistryEntry = z.infer<typeof ServiceRegistryEntrySchema>;
+export type ServiceRegistry = z.infer<typeof ServiceRegistrySchema>;

package/dist/packages/runtime/schemas/instance.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+/** Per-instance metadata from `GET /v1/instance` (replaces /v1/status). */
+export const InstanceResourceSchema = z.object({
+    kind: z.literal("interf-instance"),
+    version: z.literal(1),
+    url: z.string().min(1),
+    host: z.string().min(1),
+    port: z.number().int().min(1).max(65535),
+    pid: z.number().int().positive().optional(),
+    started_at: z.string().min(1),
+    uptime_seconds: z.number().int().min(0).optional(),
+    package_version: z.string().min(1).nullable().optional(),
+    project_count: z.number().int().min(0),
+    active_run_count: z.number().int().min(0),
+    idle_for_seconds: z.number().int().min(0),
+    auth_required: z.boolean(),
+    owner_kind: z.enum(["desktop-app", "headless"]).optional(),
+    owner_pid: z.number().int().positive().optional(),
+    agent_count: z.number().int().min(0).optional(),
+    default_agent: z.string().min(1).nullable().optional(),
+    /**
+     * Locator-pattern connection mode. `local` means the service
+     * is bound to a loopback host the user's UI can target with OS-shell
+     * actions; `remote` means OS-open is unavailable and resources must
+     * be fetched via api-served / signed URLs.
+     */
+    connection_kind: z.enum(["local", "remote"]).optional(),
+}).strict();
+/**
+ * The local service must only ever bind to a loopback interface. Any other
+ * host (LAN IP, 0.0.0.0, public address) lets a remote browser tab POST at
+ * the service, which is the CSRF model we are explicitly rejecting. Keep
+ * the allowlist literal — refactoring to a `.refine()` over `z.string()`
+ * would lose the static type narrowing.
+ */
+export const LOCAL_SERVICE_LOOPBACK_HOSTS = ["127.0.0.1", "localhost", "::1"];
+export const LocalServiceHostSchema = z
+    .string()
+    .min(1)
+    .refine((value) => LOCAL_SERVICE_LOOPBACK_HOSTS.includes(value), {
+    message: `Local service host must be one of: ${LOCAL_SERVICE_LOOPBACK_HOSTS.join(", ")}.`,
+});
+export const LocalServicePortSchema = z.number().int().min(1).max(65535);
+/**
+ * Per-instance bearer token. Generated at startup with crypto.randomBytes(32)
+ * and rendered as a 64-char hex string. Any deviation should fail validation
+ * loud and early.
+ */
+export const LocalServiceAuthTokenSchema = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/i, "Auth token must be a 64-character hex string.");
+export const LocalServiceConfigSchema = z.object({
+    host: LocalServiceHostSchema.default("127.0.0.1"),
+    port: LocalServicePortSchema.default(4873),
+}).strict();
+export const ServiceRegistryEntrySchema = z.object({
+    pid: z.number().int().positive(),
+    host: LocalServiceHostSchema,
+    port: LocalServicePortSchema,
+    url: z.string().min(1),
+    started_at: z.string().min(1),
+    owner_kind: z.enum(["desktop-app", "headless"]).optional(),
+    owner_pid: z.number().int().positive().optional(),
+    /**
+     * Bearer token protected local clients must send. Optional in the
+     * schema so older registry files keep parsing; fresh product entries
+     * always have one.
+     */
+    auth_token: LocalServiceAuthTokenSchema.optional(),
+}).strict();
+export const ServiceRegistrySchema = z.object({
+    services: z.array(ServiceRegistryEntrySchema).default([]),
+}).strict();
+export const LocalServiceHealthSchema = z.object({
+    kind: z.literal("interf-local-service-health"),
+    version: z.literal(1),
+    status: z.literal("ok"),
+    host: LocalServiceHostSchema,
+    port: LocalServicePortSchema,
+    service_url: z.string().min(1),
+    control_path: z.string().min(1).optional(),
+    source_folder_path: z.string().min(1).nullable().optional(),
+    started_at: z.string().min(1).optional(),
+    package_version: z.string().min(1).optional(),
+    instance_started_at: z.string().min(1).optional(),
+    active_runs: z.number().int().min(0).default(0),
+    idle_for_seconds: z.number().int().min(0).default(0),
+}).strict();
+export const LocalServiceErrorSchema = z.object({
+    error: z.object({
+        message: z.string().min(1),
+        code: z.string().min(1).optional(),
+        /**
+         * Upgrade-pricing URL for entitlement / quota errors (402). Clients
+         * surface this verbatim as a "View pricing" CTA. Omitted on all other
+         * error kinds.
+         */
+        upgrade_hint: z.string().min(1).optional(),
+    }).strict(),
+}).strict();
+export const LocalServiceDiscoverySchema = z.object({
+    kind: z.literal("interf-local-service-discovery"),
+    version: z.literal(1),
+    resources: z.object({
+        instance: z.string().min(1),
+        projects: z.string().min(1),
+        build_plans: z.string().min(1),
+        runs: z.string().min(1),
+        /** Generated OpenAPI contract for the local service API. */
+        openapi: z.string().min(1).optional(),
+        action_proposals: z.string().min(1),
+        executor: z.string().min(1),
+        open_path: z.string().min(1),
+        /**
+         * Connected-agents primitive. Optional so older clients still
+         * pass discovery validation when the engine has been upgraded
+         * but the client hasn't.
+         */
+        agents: z.string().min(1).optional(),
+        /** Current account / session — used by clients to fetch the signed-in user. */
+        me: z.string().min(1).optional(),
+        /**
+         * Optional resource paths for scoped helper resources.
+         */
+        readiness: z.string().min(1).optional(),
+        source_files: z.string().min(1).optional(),
+        project_setups: z.string().min(1).optional(),
+        project_changes: z.string().min(1).optional(),
+        build_plan_changes: z.string().min(1).optional(),
+        benchmark_question_drafts: z.string().min(1).optional(),
+        build_plan_draft_runs: z.string().min(1).optional(),
+        build_plan_improvement_runs: z.string().min(1).optional(),
+        verify_runs: z.string().min(1).optional(),
+        reset: z.string().min(1).optional(),
+    }).strict(),
+}).strict();
+export const OpenPathRequestSchema = z.object({
+    path: z.string().min(1),
+}).strict();
+export const OpenPathResponseSchema = z.object({
+    opened: z.boolean(),
+    path: z.string().min(1),
+}).strict();