@claudexor/schema 1.0.0

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * @claudexor/schema — single source of truth for all Claudexor data shapes.
+ *
+ * Every other package imports types and validators from here. Do not define
+ * competing shapes elsewhere. JSON Schema is generated from these Zod schemas
+ * (see scripts/gen-jsonschema.ts).
+ */
+export * from "./primitives.js";
+export * from "./surface-run-controls.js";
+export * from "./attachment.js";
+export * from "./task.js";
+export * from "./spec.js";
+export * from "./context.js";
+export * from "./harness.js";
+export * from "./review.js";
+export * from "./workproduct.js";
+export * from "./budget.js";
+export * from "./route.js";
+export * from "./decision.js";
+export * from "./control-run-detail.js";
+export * from "./gate.js";
+export * from "./events.js";
+export * from "./telemetry.js";
+export * from "./config.js";
+export * from "./workspace.js";
+export * from "./thread.js";
+export * from "./orchestrate.js";
+export * from "./control.js";
+export * from "./control-trust.js";
+export * from "./agent-capabilities.js";
+export * from "./apply-eligibility.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC"}

package/dist/orchestrate.d.ts

@@ -0,0 +1,428 @@
+import { z } from "zod";
+/**
+ * The autonomous `orchestrate` planner. It is NOT a privileged harness: it is
+ * an intent routed like reviewers (doctor-ok + capability + quota headroom),
+ * sticky per thread, overridable. Its tool belt maps 1:1 onto existing engine
+ * entry points; it never grows its own business logic.
+ *
+ * Detailed per-tool input/output schemas are introduced alongside their wiring
+ * (staged-field discipline); this module fixes the tool vocabulary + contract.
+ */
+export declare const OrchestrateToolName: z.ZodEnum<["start_run", "race", "status", "answer_question", "apply", "review"]>;
+export type OrchestrateToolName = z.infer<typeof OrchestrateToolName>;
+/** How much the planner may act without confirmation. */
+export declare const OrchestrateAutonomy: z.ZodEnum<["suggest", "auto_safe", "auto_full"]>;
+export type OrchestrateAutonomy = z.infer<typeof OrchestrateAutonomy>;
+export declare const DEFAULT_ORCHESTRATE_TOOL_BELT: OrchestrateToolName[];
+export declare const OrchestrateContract: z.ZodObject<{
+    thread_id: z.ZodString;
+    goal: z.ZodString;
+    tool_belt: z.ZodDefault<z.ZodArray<z.ZodEnum<["start_run", "race", "status", "answer_question", "apply", "review"]>, "many">>;
+    budget: z.ZodDefault<z.ZodObject<{
+        max_usd: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        max_tool_calls: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        max_usd: number | null;
+        max_tool_calls: number | null;
+    }, {
+        max_usd?: number | null | undefined;
+        max_tool_calls?: number | null | undefined;
+    }>>;
+    autonomy: z.ZodDefault<z.ZodEnum<["suggest", "auto_safe", "auto_full"]>>;
+}, "strip", z.ZodTypeAny, {
+    thread_id: string;
+    budget: {
+        max_usd: number | null;
+        max_tool_calls: number | null;
+    };
+    goal: string;
+    tool_belt: ("status" | "review" | "apply" | "start_run" | "race" | "answer_question")[];
+    autonomy: "suggest" | "auto_safe" | "auto_full";
+}, {
+    thread_id: string;
+    goal: string;
+    budget?: {
+        max_usd?: number | null | undefined;
+        max_tool_calls?: number | null | undefined;
+    } | undefined;
+    tool_belt?: ("status" | "review" | "apply" | "start_run" | "race" | "answer_question")[] | undefined;
+    autonomy?: "suggest" | "auto_safe" | "auto_full" | undefined;
+}>;
+export type OrchestrateContract = z.infer<typeof OrchestrateContract>;
+/**
+ * Data-driven tool-risk classification. SAFE = provably no live-tree mutation
+ * (isolated envelope sub-runs or pure reads); RISKY = mutates the live tree.
+ * This is the SSOT the executor classifies against — never a hardcoded
+ * enum-in-logic switch. `apply` is the only mutating tool.
+ */
+export declare const TOOL_RISK: Record<OrchestrateToolName, "safe" | "risky">;
+/**
+ * Classify a tool's risk, FAIL-CLOSED: any unknown/undeclared tool is risky.
+ * The executor must never auto-run a tool it cannot prove is safe.
+ */
+export declare function toolRisk(tool: string): "safe" | "risky";
+/**
+ * One concrete tool invocation in a planner plan, with PER-TOOL TYPED args via a
+ * discriminated union on `tool`. The executor (auto_safe/auto_full) runs these
+ * in order; under `suggest` the user executes them. Args are validated by the
+ * variant — never an open `z.record` bag — so a malformed plan fails loudly.
+ */
+export declare const OrchestratePlanCall: z.ZodDiscriminatedUnion<"tool", [z.ZodObject<{
+    tool: z.ZodLiteral<"start_run">;
+    prompt: z.ZodString;
+    mode: z.ZodDefault<z.ZodEnum<["ask", "plan", "audit", "agent", "orchestrate"]>>;
+    harness: z.ZodOptional<z.ZodString>;
+    why: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    tool: "start_run";
+    mode: "ask" | "plan" | "audit" | "agent" | "orchestrate";
+    why: string;
+    harness?: string | undefined;
+}, {
+    prompt: string;
+    tool: "start_run";
+    mode?: "ask" | "plan" | "audit" | "agent" | "orchestrate" | undefined;
+    harness?: string | undefined;
+    why?: string | undefined;
+}>, z.ZodObject<{
+    tool: z.ZodLiteral<"race">;
+    prompt: z.ZodString;
+    n: z.ZodDefault<z.ZodNumber>;
+    why: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    tool: "race";
+    why: string;
+    n: number;
+}, {
+    prompt: string;
+    tool: "race";
+    why?: string | undefined;
+    n?: number | undefined;
+}>, z.ZodObject<{
+    tool: z.ZodLiteral<"review">;
+    run_id: z.ZodString;
+    why: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tool: "review";
+    run_id: string;
+    why: string;
+}, {
+    tool: "review";
+    run_id: string;
+    why?: string | undefined;
+}>, z.ZodObject<{
+    tool: z.ZodLiteral<"status">;
+    run_id: z.ZodString;
+    why: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tool: "status";
+    run_id: string;
+    why: string;
+}, {
+    tool: "status";
+    run_id: string;
+    why?: string | undefined;
+}>, z.ZodObject<{
+    tool: z.ZodLiteral<"answer_question">;
+    interaction_id: z.ZodString;
+    answers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        question_id: z.ZodString;
+        selected_labels: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        free_text: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        question_id: string;
+        selected_labels: string[];
+        free_text: string | null;
+    }, {
+        question_id: string;
+        selected_labels?: string[] | undefined;
+        free_text?: string | null | undefined;
+    }>, "many">>;
+    why: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    interaction_id: string;
+    answers: {
+        question_id: string;
+        selected_labels: string[];
+        free_text: string | null;
+    }[];
+    tool: "answer_question";
+    why: string;
+}, {
+    interaction_id: string;
+    tool: "answer_question";
+    answers?: {
+        question_id: string;
+        selected_labels?: string[] | undefined;
+        free_text?: string | null | undefined;
+    }[] | undefined;
+    why?: string | undefined;
+}>, z.ZodObject<{
+    tool: z.ZodLiteral<"apply">;
+    run_id: z.ZodString;
+    mode: z.ZodDefault<z.ZodEnum<["apply", "branch", "commit", "pr"]>>;
+    why: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    tool: "apply";
+    mode: "apply" | "commit" | "branch" | "pr";
+    run_id: string;
+    why: string;
+}, {
+    tool: "apply";
+    run_id: string;
+    mode?: "apply" | "commit" | "branch" | "pr" | undefined;
+    why?: string | undefined;
+}>]>;
+export type OrchestratePlanCall = z.infer<typeof OrchestratePlanCall>;
+/**
+ * The TYPED orchestration plan extracted from the planner's report (the fenced
+ * JSON block the orchestrate prompt requires). Persisted as
+ * `final/orchestration.yaml`; a missing/invalid block is disclosed in the
+ * summary, never silently dropped.
+ */
+export declare const OrchestratePlan: z.ZodObject<{
+    tool_calls: z.ZodArray<z.ZodDiscriminatedUnion<"tool", [z.ZodObject<{
+        tool: z.ZodLiteral<"start_run">;
+        prompt: z.ZodString;
+        mode: z.ZodDefault<z.ZodEnum<["ask", "plan", "audit", "agent", "orchestrate"]>>;
+        harness: z.ZodOptional<z.ZodString>;
+        why: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        prompt: string;
+        tool: "start_run";
+        mode: "ask" | "plan" | "audit" | "agent" | "orchestrate";
+        why: string;
+        harness?: string | undefined;
+    }, {
+        prompt: string;
+        tool: "start_run";
+        mode?: "ask" | "plan" | "audit" | "agent" | "orchestrate" | undefined;
+        harness?: string | undefined;
+        why?: string | undefined;
+    }>, z.ZodObject<{
+        tool: z.ZodLiteral<"race">;
+        prompt: z.ZodString;
+        n: z.ZodDefault<z.ZodNumber>;
+        why: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        prompt: string;
+        tool: "race";
+        why: string;
+        n: number;
+    }, {
+        prompt: string;
+        tool: "race";
+        why?: string | undefined;
+        n?: number | undefined;
+    }>, z.ZodObject<{
+        tool: z.ZodLiteral<"review">;
+        run_id: z.ZodString;
+        why: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tool: "review";
+        run_id: string;
+        why: string;
+    }, {
+        tool: "review";
+        run_id: string;
+        why?: string | undefined;
+    }>, z.ZodObject<{
+        tool: z.ZodLiteral<"status">;
+        run_id: z.ZodString;
+        why: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tool: "status";
+        run_id: string;
+        why: string;
+    }, {
+        tool: "status";
+        run_id: string;
+        why?: string | undefined;
+    }>, z.ZodObject<{
+        tool: z.ZodLiteral<"answer_question">;
+        interaction_id: z.ZodString;
+        answers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            question_id: z.ZodString;
+            selected_labels: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            free_text: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            question_id: string;
+            selected_labels: string[];
+            free_text: string | null;
+        }, {
+            question_id: string;
+            selected_labels?: string[] | undefined;
+            free_text?: string | null | undefined;
+        }>, "many">>;
+        why: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        interaction_id: string;
+        answers: {
+            question_id: string;
+            selected_labels: string[];
+            free_text: string | null;
+        }[];
+        tool: "answer_question";
+        why: string;
+    }, {
+        interaction_id: string;
+        tool: "answer_question";
+        answers?: {
+            question_id: string;
+            selected_labels?: string[] | undefined;
+            free_text?: string | null | undefined;
+        }[] | undefined;
+        why?: string | undefined;
+    }>, z.ZodObject<{
+        tool: z.ZodLiteral<"apply">;
+        run_id: z.ZodString;
+        mode: z.ZodDefault<z.ZodEnum<["apply", "branch", "commit", "pr"]>>;
+        why: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tool: "apply";
+        mode: "apply" | "commit" | "branch" | "pr";
+        run_id: string;
+        why: string;
+    }, {
+        tool: "apply";
+        run_id: string;
+        mode?: "apply" | "commit" | "branch" | "pr" | undefined;
+        why?: string | undefined;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    tool_calls: ({
+        prompt: string;
+        tool: "start_run";
+        mode: "ask" | "plan" | "audit" | "agent" | "orchestrate";
+        why: string;
+        harness?: string | undefined;
+    } | {
+        prompt: string;
+        tool: "race";
+        why: string;
+        n: number;
+    } | {
+        tool: "review";
+        run_id: string;
+        why: string;
+    } | {
+        tool: "status";
+        run_id: string;
+        why: string;
+    } | {
+        interaction_id: string;
+        answers: {
+            question_id: string;
+            selected_labels: string[];
+            free_text: string | null;
+        }[];
+        tool: "answer_question";
+        why: string;
+    } | {
+        tool: "apply";
+        mode: "apply" | "commit" | "branch" | "pr";
+        run_id: string;
+        why: string;
+    })[];
+}, {
+    tool_calls: ({
+        prompt: string;
+        tool: "start_run";
+        mode?: "ask" | "plan" | "audit" | "agent" | "orchestrate" | undefined;
+        harness?: string | undefined;
+        why?: string | undefined;
+    } | {
+        prompt: string;
+        tool: "race";
+        why?: string | undefined;
+        n?: number | undefined;
+    } | {
+        tool: "review";
+        run_id: string;
+        why?: string | undefined;
+    } | {
+        tool: "status";
+        run_id: string;
+        why?: string | undefined;
+    } | {
+        interaction_id: string;
+        tool: "answer_question";
+        answers?: {
+            question_id: string;
+            selected_labels?: string[] | undefined;
+            free_text?: string | null | undefined;
+        }[] | undefined;
+        why?: string | undefined;
+    } | {
+        tool: "apply";
+        run_id: string;
+        mode?: "apply" | "commit" | "branch" | "pr" | undefined;
+        why?: string | undefined;
+    })[];
+}>;
+export type OrchestratePlan = z.infer<typeof OrchestratePlan>;
+/** Per-step executor status (auto_safe/auto_full). */
+export declare const OrchestrateStepStatus: z.ZodEnum<["pending", "running", "done", "skipped", "blocked", "failed"]>;
+export type OrchestrateStepStatus = z.infer<typeof OrchestrateStepStatus>;
+/**
+ * Typed executor progress over a plan's tool_calls. Persisted as
+ * `final/orchestration_progress.yaml` and projected into the run detail so a
+ * surface renders honest per-step outcomes (which safe steps ran, where a risky
+ * step blocked, why it stopped). Producer: the orchestrator executor; consumer:
+ * the control-api run-detail projection.
+ */
+export declare const OrchestratePlanProgress: z.ZodObject<{
+    steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        tool: z.ZodEnum<["start_run", "race", "status", "answer_question", "apply", "review"]>;
+        risk: z.ZodEnum<["safe", "risky"]>;
+        status: z.ZodEnum<["pending", "running", "done", "skipped", "blocked", "failed"]>;
+        /** Sub-run id this step started/targeted (start_run/race/review/status/apply), when known. */
+        run_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        detail: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "blocked" | "failed" | "running" | "done" | "skipped";
+        detail: string | null;
+        tool: "status" | "review" | "apply" | "start_run" | "race" | "answer_question";
+        run_id: string | null;
+        index: number;
+        risk: "safe" | "risky";
+    }, {
+        status: "pending" | "blocked" | "failed" | "running" | "done" | "skipped";
+        tool: "status" | "review" | "apply" | "start_run" | "race" | "answer_question";
+        index: number;
+        risk: "safe" | "risky";
+        detail?: string | null | undefined;
+        run_id?: string | null | undefined;
+    }>, "many">>;
+    autonomy: z.ZodEnum<["suggest", "auto_safe", "auto_full"]>;
+    /** Set when the executor stopped early (first risky step under auto_safe, budget, abort). */
+    stopped_reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    autonomy: "suggest" | "auto_safe" | "auto_full";
+    steps: {
+        status: "pending" | "blocked" | "failed" | "running" | "done" | "skipped";
+        detail: string | null;
+        tool: "status" | "review" | "apply" | "start_run" | "race" | "answer_question";
+        run_id: string | null;
+        index: number;
+        risk: "safe" | "risky";
+    }[];
+    stopped_reason: string | null;
+}, {
+    autonomy: "suggest" | "auto_safe" | "auto_full";
+    steps?: {
+        status: "pending" | "blocked" | "failed" | "running" | "done" | "skipped";
+        tool: "status" | "review" | "apply" | "start_run" | "race" | "answer_question";
+        index: number;
+        risk: "safe" | "risky";
+        detail?: string | null | undefined;
+        run_id?: string | null | undefined;
+    }[] | undefined;
+    stopped_reason?: string | null | undefined;
+}>;
+export type OrchestratePlanProgress = z.infer<typeof OrchestratePlanProgress>;
+export declare function orchestratePlanJsonSchema(): Record<string, unknown>;
+//# sourceMappingURL=orchestrate.d.ts.map

package/dist/orchestrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.d.ts","sourceRoot":"","sources":["../src/orchestrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;GAQG;AAEH,eAAO,MAAM,mBAAmB,kFAI7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,kDAI7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,6BAA6B,EAAE,mBAAmB,EAU9D,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBqE,CAAC;AACtG,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,GAAG,OAAO,CAOnE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8DgF,CAAC;AACjH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAI2F,CAAC;AACxH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,sDAAsD;AACtD,eAAO,MAAM,qBAAqB,2EAEiG,CAAC;AACpI,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;QAS1B,8FAA8F;;;;;;;;;;;;;;;;;;;IAQpG,6FAA6F;;;;;;;;;;;;;;;;;;;;;;;;EAO6C,CAAC;AAC/I,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAQ9E,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnE"}