@orc-brain/shared 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config.d.ts

@@ -0,0 +1,139 @@
+/** Configuration shapes for routing, budget, safety, and limits (§6, §7, §8). */
+import type { ModelName, TaskType } from "./enums.js";
+/** Budget thresholds and per-task bounds (§7). */
+export interface BudgetConfig {
+    /** Fraction of run budget at which to warn (default 0.7). */
+    warn_at: number;
+    /** Fraction of run budget at which dispatch halts (default 0.9). */
+    hard_stop_at: number;
+    /** Floor for the per-task `maxBudgetUsd` bound (default 0.5). */
+    per_task_min_usd: number;
+    /** Cap for the per-task `maxBudgetUsd` bound (default 5). */
+    per_task_max_usd: number;
+    /** Secondary volume ceilings (§7.6). */
+    max_tasks_per_run: number;
+    max_tasks_per_hour: number;
+}
+/** A single model-routing rule (§6). Evaluated in order; first match wins. */
+export interface RoutingRule {
+    id: string;
+    description: string;
+    when: {
+        task_types?: TaskType[];
+        /** Applies only when the scope did not pin a tier. */
+        unpinned_only?: boolean;
+    };
+    model: ModelName;
+}
+/** Model routing policy (§6). */
+export interface RoutingConfig {
+    rules: RoutingRule[];
+    /** Fallback model when no rule matches. */
+    default_model: ModelName;
+    /**
+     * When set, every task runs on this model — overrides scope pins, the static
+     * table, and the dynamic escalations (R1–R7). Configurable via the
+     * `ORC_FORCE_MODEL` environment variable on `orc serve`.
+     */
+    force_model?: ModelName | null;
+}
+/** Dev-scope posture per destructive rule class (§8.2, Open Decision 5). */
+export type DevPosture = "allow_with_audit" | "require_approval" | "deny";
+/** Safety configuration (§8). Production rules are never disableable. */
+export interface SafetyConfig {
+    /**
+     * Host/URL substrings that force a `production` classification (§8.1).
+     * Anything not matching a local/RFC-1918 pattern is `unknown` ⇒ production.
+     */
+    prod_host_indicators: string[];
+    /** Branch names that classify the cwd as production (§8.1). */
+    prod_branches: string[];
+    /** Per-class dev-scope posture (§8.2). Prod scopes always deny. */
+    dev_posture: Record<string, DevPosture>;
+}
+/** Rate-limit detection patterns, kept in config because they drift (§7.4). */
+export interface LimitConfig {
+    /** Regex sources matched against worker error text. */
+    patterns: {
+        session_limit: string;
+        weekly_limit: string;
+        model_limit: string;
+    };
+    /** Backoff schedule in ms when a reset time can't be parsed (§7.4). */
+    backoff_ms: number[];
+    /** Cap on backoff in ms. */
+    backoff_cap_ms: number;
+}
+/** Planner configuration (§3, §15 Phase 2). */
+export interface PlannerConfig {
+    /** Model the plan-only session is pinned to (§3: Opus). */
+    model: ModelName;
+    /** Read-only tools the Planner may use to inspect the repo (§3). */
+    allowed_tools: string[];
+    /** Turn ceiling for a planning session. */
+    max_turns: number;
+}
+/** Retry policy for failed tasks (§5, §13; router R5 escalates on retry). */
+export interface RetryConfig {
+    /** Maximum attempts per task before it is left `failed` (attempt 0 = first try). */
+    max_attempts: number;
+}
+/** Reporting cadence (§11). */
+export interface ReportingConfig {
+    /** Minutes between interval reports while Running (default 15). */
+    interval_minutes: number;
+}
+/** Escalation / blocked-queue posture (§8.5). */
+export interface EscalationConfig {
+    /**
+     * Number of same-rule denials in one task before it transitions to `blocked`
+     * and an escalation is raised (§8.5 default: halt on the 2nd denial).
+     */
+    block_on_denial_count: number;
+}
+/** Pause / interrupt grace behaviour (§5). */
+export interface PauseConfig {
+    /** Grace window (ms) for workers to yield before SIGTERM (§5). */
+    grace_ms: number;
+    /** Additional window (ms) after SIGTERM before SIGKILL (§5). */
+    sigkill_after_ms: number;
+}
+/**
+ * Autonomous outer-loop ("auto-replan controller") posture
+ * (.specs/active/autonomous-loop.md §3.5). Opt-in; default preserves the
+ * static plan-once/execute-fixed-DAG behavior.
+ */
+export interface AutoLoopConfig {
+    /** When false, the controller never engages — behavior is unchanged (AC1). */
+    enabled: boolean;
+    /**
+     * `supervised` keeps the human plan-approval gate for re-planned scopes;
+     * `unattended` auto-approves them (still fully bound by the safety layer,
+     * scope boundaries, budget, and escalations).
+     */
+    mode: "supervised" | "unattended";
+    /** Re-plan trigger granularity. `scope` = after each scope completes. */
+    replan_on: "scope";
+    /** Runaway ceiling: max re-plan cycles before the run is paused (G5). */
+    max_replan_cycles: number;
+}
+/** Top-level orchestrator configuration (`orchestrator.toml`, §12). */
+export interface OrchestratorConfig {
+    concurrency_limit: number;
+    /**
+     * Cap on simultaneously running workers across ALL runs (spec 002 §R13) —
+     * the subscription is shared, so per-run limits alone don't bound total load.
+     */
+    global_concurrency_limit: number;
+    budget: BudgetConfig;
+    routing: RoutingConfig;
+    safety: SafetyConfig;
+    limits: LimitConfig;
+    planner: PlannerConfig;
+    retry: RetryConfig;
+    reporting: ReportingConfig;
+    escalation: EscalationConfig;
+    pause: PauseConfig;
+    autoLoop: AutoLoopConfig;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE;QACJ,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;QACxB,sDAAsD;QACtD,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,2CAA2C;IAC3C,aAAa,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAChC;AAED,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAE1E,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,+DAA+D;IAC/D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACzC;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,QAAQ,EAAE;QACR,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,uEAAuE;IACvE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,KAAK,EAAE,SAAS,CAAC;IACjB,oEAAoE;IACpE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;IAClC,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,wBAAwB,EAAE,MAAM,CAAC;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,eAAe,CAAC;IAC3B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;CAC1B"}

package/dist/config.js

@@ -0,0 +1,3 @@
+/** Configuration shapes for routing, budget, safety, and limits (§6, §7, §8). */
+export {};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/entities.d.ts

@@ -0,0 +1,216 @@
+/** Core entities of the orc-brain data model (§4). */
+import type { EntityBase, IsoTimestamp, Ulid } from "./ids.js";
+import type { BudgetState, Environment, EscalationAction, EscalationStatus, GoalStatus, ModelName, ModelTier, ProjectExecutionMode, ReportTrigger, RunState, ScopePermissionMode, ScopeStatus, SubagentState, TaskStatus, TaskType } from "./enums.js";
+/** A checkable success statement attached to a Goal or Scope (§4). */
+export interface SuccessCriterion {
+    description: string;
+    verification_method?: string;
+}
+/** A human-readable + machine-matchable forbidden action on a Scope (§4, §8). */
+export interface ForbiddenAction {
+    description: string;
+    /** Optional machine pattern appended to the scope's deny rules. */
+    pattern?: string;
+}
+/**
+ * Project: a registered local repository orc operates on (spec 002 §R1).
+ * `repo_root` is unique; `execution_mode` decides worktree isolation (§R8) and
+ * the `default_*` fields seed runs started by the feature flow (§R5).
+ */
+export interface Project extends EntityBase {
+    name: string;
+    repo_root: string;
+    execution_mode: ProjectExecutionMode;
+    default_budget_usd: number;
+    default_concurrency: number;
+    /**
+     * When true (worktree mode only), a successfully settled scope branch is
+     * merged (`--no-ff`) into the run's base branch automatically (spec 002 v2).
+     * Skipped — branch kept for manual merge — if the checkout is dirty, on a
+     * different branch, or the merge conflicts.
+     */
+    auto_merge: boolean;
+}
+/**
+ * Back-reference from a Goal to the external tracker task it was imported
+ * from (spec 003 §R2, §3.5). Null for goals typed by the operator.
+ */
+export interface ExternalRef {
+    /** Plugin name that owns the task (e.g. `"linear"`). */
+    provider: string;
+    /** Provider-native stable id. */
+    id: string;
+    /** Human identifier (e.g. `"ENG-123"`). */
+    identifier: string;
+    url: string;
+    title: string;
+}
+/** Goal: the top-level objective (§4). */
+export interface Goal extends EntityBase {
+    title: string;
+    objective: string;
+    success_criteria: SuccessCriterion[];
+    constraints: string[];
+    out_of_scope: string[];
+    /** Owning project (spec 002 §R2); null only for pre-project legacy goals. */
+    project_id: Ulid | null;
+    /** Denormalized from the project at creation so consumers stay unchanged. */
+    repo_root: string;
+    status: GoalStatus;
+    /** Origin tracker task when imported via a plugin (spec 003 §R2). */
+    external_ref: ExternalRef | null;
+}
+/** Scope: a bounded region of work and the unit of safety config (§4). */
+export interface Scope extends EntityBase {
+    goal_id: Ulid;
+    name: string;
+    description: string;
+    path_allowlist: string[];
+    path_denylist: string[];
+    allowed_tools: string[];
+    disallowed_tools: string[];
+    model_tier: ModelTier;
+    environment: Environment;
+    permission_mode: ScopePermissionMode;
+    forbidden_actions: ForbiddenAction[];
+    success_criteria: SuccessCriterion[];
+    max_budget_usd: number;
+    status: ScopeStatus;
+    depends_on: Ulid[];
+    /** Worktree the scope's workers run in, when isolated (spec 002 §R8). */
+    worktree_path: string | null;
+    /** Scope branch (`orc/<goal>/<scope>`), kept after the worktree is removed. */
+    branch_name: string | null;
+}
+/** Task: an atomic dispatchable unit inside a Scope (§4). */
+export interface Task extends EntityBase {
+    scope_id: Ulid;
+    title: string;
+    prompt: string;
+    task_type: TaskType;
+    depends_on: Ulid[];
+    status: TaskStatus;
+    /**
+     * Dispatch priority (spec 002 v2, kanban drag): higher dispatches first;
+     * ties fall back to creation order. 0 for every task by default.
+     */
+    priority: number;
+    attempt: number;
+    model_used: ModelName | null;
+    routing_reason: string | null;
+    session_id: string | null;
+    cost_usd: number;
+    result_summary: unknown | null;
+    error: unknown | null;
+    /** Set when a non-graceful stop may have left half-applied edits (§5, §13.6). */
+    dirty: boolean;
+}
+/** SubagentRecord: a live/finished worker session, 1:1 with a Task attempt (§4). */
+export interface SubagentRecord extends EntityBase {
+    task_id: Ulid;
+    session_id: string | null;
+    model: ModelName;
+    pid: number | null;
+    state: SubagentState;
+    started_at: IsoTimestamp | null;
+    ended_at: IsoTimestamp | null;
+    num_turns: number;
+    cost_usd: number;
+    last_tool_call: unknown | null;
+    transcript_path: string | null;
+}
+/** Run: one execution of a Goal (§4). */
+export interface Run extends EntityBase {
+    goal_id: Ulid;
+    state: RunState;
+    budget_usd: number;
+    budget_spent_usd: number;
+    budget_state: BudgetState;
+    concurrency_limit: number;
+    started_at: IsoTimestamp | null;
+    paused_at: IsoTimestamp | null;
+    finished_at: IsoTimestamp | null;
+    pause_reason: string | null;
+    /**
+     * Branch of the repo when the run started (spec 002 §R8, §R10): worktrees
+     * fork from it and environment classification uses it, never the `orc/…`
+     * worktree branch. Null when the repo branch could not be read.
+     */
+    base_branch: string | null;
+    /**
+     * True for runs started by the feature flow (spec 002 §R5): the run hands
+     * off to the autonomous controller on quiescence even when the global
+     * `autoLoop.enabled` config is off, and replan cycles are unattended.
+     */
+    auto_loop: boolean;
+    /**
+     * Count of autonomous re-plan cycles executed for this run
+     * (.specs/active/autonomous-loop.md §3.5, G5). Guards against runaway loops
+     * via `AutoLoopConfig.max_replan_cycles`. 0 for static (non-auto) runs.
+     */
+    replan_cycle: number;
+}
+/**
+ * Escalation: a blocked tool call awaiting operator resolution (§8.5). Raised
+ * when a task hits the same deny rule twice; the run continues elsewhere.
+ */
+export interface Escalation extends EntityBase {
+    run_id: Ulid;
+    task_id: Ulid;
+    rule_id: string;
+    tool_name: string;
+    /** Redacted, truncated tool input for display (§8.6). */
+    input_summary: string;
+    /** The subagent's stated intent, if captured. */
+    stated_intent: string | null;
+    status: EscalationStatus;
+    /** How the operator resolved it, once resolved. */
+    action: EscalationAction | null;
+    /** Operator guidance sent back to the subagent (deny_instruct). */
+    message: string | null;
+    resolved_at: IsoTimestamp | null;
+}
+/** Report: a rendered Markdown status report (§4, §11). */
+export interface Report extends EntityBase {
+    run_id: Ulid;
+    trigger: ReportTrigger;
+    content_md: string;
+    path: string | null;
+}
+/**
+ * BudgetLedgerEntry: one row per SDK result message; the source of truth for
+ * cost aggregation (§4, §7). Aggregation is `SUM()` over this table.
+ */
+export interface BudgetLedgerEntry extends EntityBase {
+    run_id: Ulid;
+    task_id: Ulid;
+    session_id: string | null;
+    cost_usd: number;
+    num_turns: number;
+    model: string;
+    tokens_in: number;
+    tokens_out: number;
+    cache_read: number;
+    cache_write: number;
+    recorded_at: IsoTimestamp;
+}
+/**
+ * AuditEvent: an append-only JSONL record. Never stored in SQLite (§4, §8.6).
+ * `tool_input` is redacted per §8.6 before it is written.
+ */
+export interface AuditEvent {
+    ts: IsoTimestamp;
+    /** Who acted, when not a worker — e.g. `"plugin:linear"` (spec 003 §R6). */
+    actor?: string;
+    run_id: Ulid | null;
+    task_id: Ulid | null;
+    session_id: string | null;
+    kind: import("./enums.js").AuditKind;
+    tool_name: string | null;
+    tool_input_hash: string | null;
+    tool_input: unknown;
+    decision: string | null;
+    rule_id: string | null;
+    detail: unknown;
+}
+//# sourceMappingURL=entities.d.ts.map

package/dist/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../src/entities.ts"],"names":[],"mappings":"AAAA,sDAAsD;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,SAAS,EACT,oBAAoB,EACpB,aAAa,EACb,QAAQ,EACR,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,UAAU,EACV,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAQ,SAAQ,UAAU;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,WAAW,IAAK,SAAQ,UAAU;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,qEAAqE;IACrE,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;CAClC;AAED,0EAA0E;AAC1E,MAAM,WAAW,KAAM,SAAQ,UAAU;IACvC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,SAAS,CAAC;IACtB,WAAW,EAAE,WAAW,CAAC;IACzB,eAAe,EAAE,mBAAmB,CAAC;IACrC,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,IAAI,EAAE,CAAC;IACnB,yEAAyE;IACzE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,IAAK,SAAQ,UAAU;IACtC,QAAQ,EAAE,IAAI,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,QAAQ,CAAC;IACpB,UAAU,EAAE,IAAI,EAAE,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,GAAI,SAAQ,UAAU;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,WAAW,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,gBAAgB,CAAC;IACzB,mDAAmD;IACnD,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,YAAY,GAAG,IAAI,CAAC;CAClC;AAED,2DAA2D;AAC3D,MAAM,WAAW,MAAO,SAAQ,UAAU;IACxC,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,YAAY,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,YAAY,CAAC;IACjB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,OAAO,YAAY,EAAE,SAAS,CAAC;IACrC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;CACjB"}

package/dist/entities.js

@@ -0,0 +1,3 @@
+/** Core entities of the orc-brain data model (§4). */
+export {};
+//# sourceMappingURL=entities.js.map

package/dist/entities.js.map

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

package/dist/enums.d.ts

@@ -0,0 +1,47 @@
+/** Enumerations for the orc-brain data model (§4) and state machines (§5). */
+/**
+ * Execution isolation mode of a registered Project (spec 002 §R1, §R8).
+ * `worktree` runs each scope in a dedicated git worktree on an `orc/<goal>/
+ * <scope>` branch; `in_repo` runs workers directly in the repo working tree
+ * (the pre-project behavior).
+ */
+export type ProjectExecutionMode = "worktree" | "in_repo";
+/** Goal lifecycle status. */
+export type GoalStatus = "draft" | "planning" | "awaiting_approval" | "active" | "done" | "abandoned";
+/**
+ * Environment classification of a Scope (§4, §8.1). `unknown` is treated as
+ * `production` everywhere enforcement happens — see the safety layer.
+ */
+export type Environment = "development" | "staging" | "production" | "unknown";
+/**
+ * Permission mode a Scope may request (§4, §8.3). `bypassPermissions` is
+ * deliberately NOT representable — the safety layer refuses it structurally.
+ */
+export type ScopePermissionMode = "plan" | "default" | "acceptEdits";
+/** Model tier a Scope pins, or `auto` to let the router decide (§6). */
+export type ModelTier = "haiku" | "sonnet" | "opus" | "auto";
+/** Concrete model a worker runs on. `inherit` defers to the session default. */
+export type ModelName = "haiku" | "sonnet" | "opus" | "inherit";
+/** Scope lifecycle status (§4). */
+export type ScopeStatus = "proposed" | "approved" | "running" | "blocked" | "done" | "failed";
+/** Router-relevant classification of a Task (§4, §6). */
+export type TaskType = "mechanical" | "codegen" | "refactor" | "test" | "review" | "planning" | "research";
+/** Task lifecycle status (§5). */
+export type TaskStatus = "pending" | "queued" | "running" | "paused" | "blocked" | "done" | "failed" | "skipped" | "cancelled";
+/** Run state machine states (§5). */
+export type RunState = "draft" | "planning" | "awaiting_approval" | "running" | "pausing" | "paused" | "done" | "failed";
+/** Budget backpressure state (§7). */
+export type BudgetState = "ok" | "warn" | "stopped";
+/** Live worker session state (§4 SubagentRecord). */
+export type SubagentState = "spawning" | "running" | "interrupting" | "paused" | "exited";
+/** What triggered a report (§11). */
+export type ReportTrigger = "interval" | "scope_done" | "task_done" | "budget_threshold" | "manual" | "final";
+/** Lifecycle of an operator escalation raised by a blocked tool call (§8.5). */
+export type EscalationStatus = "open" | "resolved";
+/** The three operator resolutions for a blocked action (§8.5). */
+export type EscalationAction = "deny_instruct" | "approve_once" | "skip_task";
+/** Scope of an engaged rate-limit backpressure (§7.4). */
+export type BackpressureScope = "global" | "model";
+/** Kinds of audit event recorded to the append-only JSONL log (§4, §8.6). */
+export type AuditKind = "tool_call" | "tool_result" | "hook_block" | "permission_deny" | "permission_allow" | "interrupt" | "dispatch" | "state_change" | "routing_decision" | "escalation" | "exemption" | "backpressure" | "report" | "plugin";
+//# sourceMappingURL=enums.d.ts.map

package/dist/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../src/enums.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1D,6BAA6B;AAC7B,MAAM,MAAM,UAAU,GACpB,OAAO,GAAG,UAAU,GAAG,mBAAmB,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;AAErE,wEAAwE;AACxE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhE,mCAAmC;AACnC,MAAM,MAAM,WAAW,GACrB,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEtE,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAChB,YAAY,GACZ,SAAS,GACT,UAAU,GACV,MAAM,GACN,QAAQ,GACR,UAAU,GACV,UAAU,CAAC;AAEf,kCAAkC;AAClC,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,MAAM,GACN,QAAQ,GACR,SAAS,GACT,WAAW,CAAC;AAEhB,qCAAqC;AACrC,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,UAAU,GACV,mBAAmB,GACnB,SAAS,GACT,SAAS,GACT,QAAQ,GACR,MAAM,GACN,QAAQ,CAAC;AAEb,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD,qDAAqD;AACrD,MAAM,MAAM,aAAa,GACvB,UAAU,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhE,qCAAqC;AACrC,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,YAAY,GACZ,WAAW,GACX,kBAAkB,GAClB,QAAQ,GACR,OAAO,CAAC;AAEZ,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnD,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,cAAc,GAAG,WAAW,CAAC;AAE9E,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GACjB,WAAW,GACX,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,kBAAkB,GAClB,WAAW,GACX,UAAU,GACV,cAAc,GACd,kBAAkB,GAClB,YAAY,GACZ,WAAW,GACX,cAAc,GACd,QAAQ,GACR,QAAQ,CAAC"}

package/dist/enums.js

@@ -0,0 +1,3 @@
+/** Enumerations for the orc-brain data model (§4) and state machines (§5). */
+export {};
+//# sourceMappingURL=enums.js.map

package/dist/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../src/enums.ts"],"names":[],"mappings":"AAAA,8EAA8E"}

package/dist/events.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Event bus / SSE event schemas (§3, §10). Every event is appended to the
+ * store before fan-out, so the persisted log is never behind the UI.
+ */
+import type { IsoTimestamp, Ulid } from "./ids.js";
+import type { BudgetState, ModelName, RunState, TaskStatus } from "./enums.js";
+import type { ExternalRef } from "./entities.js";
+/** Envelope carried by every bus/SSE event. */
+export interface EventEnvelope<K extends string, P> {
+    /** Monotonic per-run sequence id; also the SSE `id:` for Last-Event-ID resume. */
+    seq: number;
+    ts: IsoTimestamp;
+    run_id: Ulid | null;
+    type: K;
+    payload: P;
+}
+/** A task changed state (§10 `task.state`). */
+export type TaskStateEvent = EventEnvelope<"task.state", {
+    task_id: Ulid;
+    scope_id: Ulid;
+    status: TaskStatus;
+    model?: ModelName;
+    routing_reason?: string;
+    attempt?: number;
+    error?: unknown;
+}>;
+/** A worker began a tool call (§10 `tool.call`). */
+export type ToolCallEvent = EventEnvelope<"tool.call", {
+    task_id: Ulid;
+    session_id: string | null;
+    tool_name: string;
+    /** Truncated/redacted input summary for display. */
+    input_summary: string;
+    decision?: "allow" | "deny";
+    rule_id?: string;
+}>;
+/** A tool call produced a result (§10 `tool.result`). */
+export type ToolResultEvent = EventEnvelope<"tool.result", {
+    task_id: Ulid;
+    session_id: string | null;
+    tool_name: string;
+    is_error: boolean;
+    summary: string;
+}>;
+/** A streamed text delta from a worker (§10 `text.delta`). */
+export type TextDeltaEvent = EventEnvelope<"text.delta", {
+    task_id: Ulid;
+    session_id: string | null;
+    delta: string;
+}>;
+/** Budget ledger updated (§10 `budget.tick`). */
+export type BudgetTickEvent = EventEnvelope<"budget.tick", {
+    budget_usd: number;
+    spent_usd: number;
+    state: BudgetState;
+    warn_at: number;
+    stop_at: number;
+}>;
+/** Rate-limit backpressure engaged/cleared (§7, §10 `limit.backpressure`). */
+export type LimitBackpressureEvent = EventEnvelope<"limit.backpressure", {
+    engaged: boolean;
+    scope: "global" | "model";
+    model?: ModelName;
+    reason: string;
+    /** Epoch ms when backpressure is expected to clear, if known. */
+    resets_at?: number;
+}>;
+/** Run state machine transition (§10 `run.state`). */
+export type RunStateEvent = EventEnvelope<"run.state", {
+    state: RunState;
+    reason?: string;
+}>;
+/** A tool call was blocked and needs operator action (§8.5, §10 `escalation.new`). */
+export type EscalationEvent = EventEnvelope<"escalation.new", {
+    escalation_id: Ulid;
+    task_id: Ulid;
+    rule_id: string;
+    tool_name: string;
+    input_summary: string;
+    stated_intent?: string;
+}>;
+/** A new report was generated (§10 `report.new`). */
+export type ReportEvent = EventEnvelope<"report.new", {
+    report_id: Ulid;
+    trigger: string;
+    path: string | null;
+}>;
+/** A worker was dispatched (§5 dispatch loop). */
+export type DispatchEvent = EventEnvelope<"dispatch", {
+    task_id: Ulid;
+    scope_id: Ulid;
+    model: ModelName;
+    routing_reason: string;
+}>;
+/**
+ * A scope reached a terminal state — all its tasks settled
+ * (.specs/active/autonomous-loop.md §3.2, G1). `scope.done` = none failed;
+ * `scope.failed` = at least one task failed after retries.
+ */
+export type ScopeSettledEvent = EventEnvelope<"scope.done" | "scope.failed", {
+    scope_id: Ulid;
+    goal_id: Ulid;
+    task_count: number;
+    failed_count: number;
+}>;
+/**
+ * The autonomous controller ran a re-plan cycle
+ * (.specs/active/autonomous-loop.md §3.1, G2). `added_tasks` = 0 signals the
+ * no-progress guard (G5).
+ */
+export type ReplanCycleEvent = EventEnvelope<"replan_cycle", {
+    cycle: number;
+    added_scopes: number;
+    added_tasks: number;
+}>;
+/**
+ * The hybrid goal-satisfaction evaluator produced a verdict
+ * (.specs/active/autonomous-loop.md §3.4, G3).
+ */
+export type GoalEvaluatedEvent = EventEnvelope<"goal_evaluated", {
+    satisfied: boolean;
+    unmet: string[];
+    rationale: string;
+}>;
+/**
+ * Dispatch was deferred by proactive pacing (spec 002 §R16): the global
+ * concurrency cap, the tasks-per-hour throttle, or the per-run task ceiling.
+ * Edge-triggered — published when the gate first engages, not every tick.
+ */
+export type PacingHoldEvent = EventEnvelope<"pacing.hold", {
+    reason: "global_concurrency" | "tasks_per_hour" | "tasks_per_run";
+    /** ISO timestamp when dispatch is expected to resume, if known. */
+    resume_at?: IsoTimestamp;
+}>;
+/**
+ * A plugin performed (or failed) an outbound sync action against its external
+ * tracker (spec 003 §R9, §R12) — e.g. a Linear comment or state transition.
+ * Published by the plugin host via `host.reportSync`.
+ */
+export type PluginSyncEvent = EventEnvelope<"plugin.sync", {
+    plugin: string;
+    action: string;
+    ref?: ExternalRef;
+    ok: boolean;
+    detail?: string;
+}>;
+/** Discriminated union of all bus/SSE events. */
+export type BusEvent = TaskStateEvent | ToolCallEvent | ToolResultEvent | TextDeltaEvent | BudgetTickEvent | LimitBackpressureEvent | RunStateEvent | EscalationEvent | ReportEvent | DispatchEvent | ScopeSettledEvent | ReplanCycleEvent | GoalEvaluatedEvent | PacingHoldEvent | PluginSyncEvent;
+/** String literal type of every event kind. */
+export type BusEventType = BusEvent["type"];
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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

package/dist/events.js

@@ -0,0 +1,6 @@
+/**
+ * Event bus / SSE event schemas (§3, §10). Every event is appended to the
+ * store before fan-out, so the persisted log is never behind the UI.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

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

package/dist/ids.d.ts

@@ -0,0 +1,12 @@
+/** Branded ID helpers. All entities carry a ULID `id` (§4). */
+/** A ULID string identifying any orc-brain entity. */
+export type Ulid = string;
+/** ISO-8601 timestamp string (UTC). */
+export type IsoTimestamp = string;
+/** Fields shared by every persisted entity (§4). */
+export interface EntityBase {
+    id: Ulid;
+    created_at: IsoTimestamp;
+    updated_at: IsoTimestamp;
+}
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,sDAAsD;AACtD,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC;AAE1B,uCAAuC;AACvC,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,YAAY,CAAC;IACzB,UAAU,EAAE,YAAY,CAAC;CAC1B"}

package/dist/ids.js

@@ -0,0 +1,3 @@
+/** Branded ID helpers. All entities carry a ULID `id` (§4). */
+export {};
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,+DAA+D"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/** Shared types and event schemas for orc-brain. See specs/001-orchestrator-spec.md (source of truth). */
+/** Semantic version of the shared contract. Bumped when event schemas change. */
+export declare const SHARED_SCHEMA_VERSION: "0.4.0";
+export * from "./ids.js";
+export * from "./enums.js";
+export * from "./entities.js";
+export * from "./events.js";
+export * from "./config.js";
+export * from "./plan.js";
+export * from "./plugins.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAE1G,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,EAAG,OAAgB,CAAC;AAEtD,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/** Shared types and event schemas for orc-brain. See specs/001-orchestrator-spec.md (source of truth). */
+/** Semantic version of the shared contract. Bumped when event schemas change. */
+export const SHARED_SCHEMA_VERSION = "0.4.0";
+export * from "./ids.js";
+export * from "./enums.js";
+export * from "./entities.js";
+export * from "./events.js";
+export * from "./config.js";
+export * from "./plan.js";
+export * from "./plugins.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,0GAA0G;AAE1G,iFAAiF;AACjF,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAgB,CAAC;AAEtD,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/plan.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Planner output contract (§3, §15 Phase 2). The Planner emits a structured
+ * Scope/Task breakdown validated against this shape before it is materialized
+ * into {@link Scope}/{@link Task} rows for operator approval. Dependencies are
+ * expressed by human-readable reference (scope `name`, task `title`) so the LLM
+ * never has to invent ULIDs; the orchestrator resolves them at materialization.
+ */
+import type { Environment, ModelTier, ScopePermissionMode, TaskType } from "./enums.js";
+import type { ForbiddenAction, SuccessCriterion } from "./entities.js";
+/** A planned task inside a planned scope (materializes to a {@link Task}). */
+export interface PlannedTask {
+    title: string;
+    prompt: string;
+    task_type: TaskType;
+    /** Titles of sibling tasks (within the same scope) this task depends on. */
+    depends_on?: string[];
+}
+/** A planned scope (materializes to a {@link Scope}). */
+export interface PlannedScope {
+    name: string;
+    description: string;
+    path_allowlist: string[];
+    path_denylist?: string[];
+    allowed_tools: string[];
+    disallowed_tools?: string[];
+    model_tier: ModelTier;
+    environment: Environment;
+    permission_mode: ScopePermissionMode;
+    forbidden_actions?: ForbiddenAction[];
+    success_criteria?: SuccessCriterion[];
+    max_budget_usd: number;
+    /** Names of other scopes this scope depends on (scope-level DAG). */
+    depends_on?: string[];
+    tasks: PlannedTask[];
+}
+/** The Planner's full output: a proposed Scope/Task DAG for a Goal. */
+export interface Plan {
+    scopes: PlannedScope[];
+}
+/**
+ * JSON Schema handed to the SDK via `outputFormat: { type: "json_schema" }` so
+ * the Planner returns a machine-checkable {@link Plan}. Kept deliberately strict
+ * on enums (they mirror {@link ModelTier}/{@link Environment}/etc.) so an invalid
+ * plan fails fast at validation rather than at dispatch.
+ */
+export declare const PLAN_JSON_SCHEMA: Record<string, unknown>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,QAAQ,EACT,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEvE,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,QAAQ,CAAC;IACpB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,UAAU,EAAE,SAAS,CAAC;IACtB,WAAW,EAAE,WAAW,CAAC;IACzB,eAAe,EAAE,mBAAmB,CAAC;IACrC,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC;IACtC,gBAAgB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAiGpD,CAAC"}

package/dist/plan.js

@@ -0,0 +1,112 @@
+/**
+ * Planner output contract (§3, §15 Phase 2). The Planner emits a structured
+ * Scope/Task breakdown validated against this shape before it is materialized
+ * into {@link Scope}/{@link Task} rows for operator approval. Dependencies are
+ * expressed by human-readable reference (scope `name`, task `title`) so the LLM
+ * never has to invent ULIDs; the orchestrator resolves them at materialization.
+ */
+/**
+ * JSON Schema handed to the SDK via `outputFormat: { type: "json_schema" }` so
+ * the Planner returns a machine-checkable {@link Plan}. Kept deliberately strict
+ * on enums (they mirror {@link ModelTier}/{@link Environment}/etc.) so an invalid
+ * plan fails fast at validation rather than at dispatch.
+ */
+export const PLAN_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["scopes"],
+    properties: {
+        scopes: {
+            type: "array",
+            minItems: 1,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "name",
+                    "description",
+                    "path_allowlist",
+                    "allowed_tools",
+                    "model_tier",
+                    "environment",
+                    "permission_mode",
+                    "max_budget_usd",
+                    "tasks",
+                ],
+                properties: {
+                    name: { type: "string" },
+                    description: { type: "string" },
+                    path_allowlist: { type: "array", items: { type: "string" } },
+                    path_denylist: { type: "array", items: { type: "string" } },
+                    allowed_tools: { type: "array", items: { type: "string" } },
+                    disallowed_tools: { type: "array", items: { type: "string" } },
+                    model_tier: {
+                        type: "string",
+                        enum: ["haiku", "sonnet", "opus", "auto"],
+                    },
+                    environment: {
+                        type: "string",
+                        enum: ["development", "staging", "production", "unknown"],
+                    },
+                    permission_mode: {
+                        type: "string",
+                        enum: ["plan", "default", "acceptEdits"],
+                    },
+                    forbidden_actions: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            additionalProperties: false,
+                            required: ["description"],
+                            properties: {
+                                description: { type: "string" },
+                                pattern: { type: "string" },
+                            },
+                        },
+                    },
+                    success_criteria: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            additionalProperties: false,
+                            required: ["description"],
+                            properties: {
+                                description: { type: "string" },
+                                verification_method: { type: "string" },
+                            },
+                        },
+                    },
+                    max_budget_usd: { type: "number", minimum: 0 },
+                    depends_on: { type: "array", items: { type: "string" } },
+                    tasks: {
+                        type: "array",
+                        minItems: 1,
+                        items: {
+                            type: "object",
+                            additionalProperties: false,
+                            required: ["title", "prompt", "task_type"],
+                            properties: {
+                                title: { type: "string" },
+                                prompt: { type: "string" },
+                                task_type: {
+                                    type: "string",
+                                    enum: [
+                                        "mechanical",
+                                        "codegen",
+                                        "refactor",
+                                        "test",
+                                        "review",
+                                        "planning",
+                                        "research",
+                                    ],
+                                },
+                                depends_on: { type: "array", items: { type: "string" } },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=plan.js.map

package/dist/plan.js.map

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

package/dist/plugins.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Plugin contract (spec 003 §R1). Types only — the host implementation lives
+ * in `@orc-brain/core` (`src/plugins/`). Third-party plugins depend on
+ * `@orc-brain/shared` alone and export a default factory returning an
+ * {@link OrcPlugin}. See `packages/plugin-linear` for the reference plugin.
+ */
+import type { ExternalRef, Goal, Project, Run, Scope } from "./entities.js";
+import type { BusEvent } from "./events.js";
+/**
+ * Version of this contract. The registry refuses to load a plugin whose
+ * manifest declares a different `apiVersion` (spec 003 §R3).
+ */
+export declare const PLUGIN_API_VERSION = 1;
+/** Standardized capabilities a plugin may declare (spec 003 §3.2). */
+export type PluginCapability = "task-provider";
+/** Static description a plugin declares about itself (spec 003 §R1). */
+export interface PluginManifest {
+    /** Unique kebab-case plugin name (e.g. `"linear"`). */
+    name: string;
+    version: string;
+    /** Must equal {@link PLUGIN_API_VERSION} or the plugin is not loaded. */
+    apiVersion: number;
+    capabilities: PluginCapability[];
+    /**
+     * Env-style secret key names the plugin reads via `host.getSecret` (e.g.
+     * `"LINEAR_API_KEY"`). Every declared key is stripped from worker envs and
+     * its value registered for redaction (spec 003 §R5).
+     */
+    secrets?: string[];
+}
+/** A task in an external tracker, normalized by a `task-provider` (§R1). */
+export interface ExternalTask {
+    /** Plugin name that produced this task (e.g. `"linear"`). */
+    provider: string;
+    /** Provider-native stable id (e.g. a Linear issue UUID). */
+    id: string;
+    /** Human identifier (e.g. `"ENG-123"`). */
+    identifier: string;
+    title: string;
+    /** Full description, markdown as-is; empty string when the tracker has none. */
+    description: string;
+    url: string;
+    /** Provider workflow-state name (display only). */
+    state: string;
+    assignee?: string;
+    labels: string[];
+    updated_at: string;
+}
+/** Query accepted by {@link TaskProvider.listTasks} (spec 003 §R1). */
+export interface TaskQuery {
+    search?: string;
+    assigned_to_me?: boolean;
+    state?: string;
+    team?: string;
+    limit?: number;
+}
+/** The `task-provider` capability surface (spec 003 §R1, §R11). */
+export interface TaskProvider {
+    listTasks(query: TaskQuery): Promise<ExternalTask[]>;
+    /** Accepts the provider-native id or the human identifier (§R11). */
+    getTask(id: string): Promise<ExternalTask | null>;
+}
+/**
+ * The narrow host API handed to a plugin's `init` (spec 003 §R1). Implemented
+ * by core; every method is safe to call from plugin callbacks — failures in
+ * the plugin never propagate into orchestrator control flow (§N2).
+ */
+export interface PluginHost {
+    log(msg: string): void;
+    /** Appends an audit entry with `actor: "plugin:<name>"` (spec 003 §R6). */
+    audit(action: string, detail?: unknown): void;
+    /**
+     * Audits a sync action AND publishes a `plugin.sync` bus event
+     * (spec 003 §R9, §R12).
+     */
+    reportSync(action: string, info: {
+        ref?: ExternalRef;
+        ok: boolean;
+        detail?: string;
+        run_id?: string;
+    }): void;
+    /** Secrets file first, then `process.env[key]` fallback (spec 003 §R5). */
+    getSecret(key: string): string | undefined;
+    /** Per-plugin settings from `plugins.json` (spec 003 §R3). */
+    settings: Record<string, unknown>;
+    subscribe(fn: (e: BusEvent) => void): () => void;
+    listProjects(): Promise<Project[]>;
+    getGoal(id: string): Promise<Goal | null>;
+    getRun(id: string): Promise<Run | null>;
+    listScopesByGoal(goalId: string): Promise<Scope[]>;
+    /**
+     * Creates a goal under a project from an external task via the feature-flow
+     * code path — planning kicks off immediately (spec 003 §R4).
+     */
+    createGoalFromExternalTask(projectId: string, task: ExternalTask): Promise<Goal>;
+}
+/** A constructed plugin instance (spec 003 §R1). */
+export interface OrcPlugin {
+    manifest: PluginManifest;
+    init(host: PluginHost): Promise<void> | void;
+    close?(): Promise<void> | void;
+    /** Present when `manifest.capabilities` includes `"task-provider"`. */
+    taskProvider?: TaskProvider;
+    /**
+     * Called by the host after one of this provider's tasks is imported as a
+     * goal (spec 003 §R12 import comment). Fire-and-forget; errors are audited.
+     */
+    onTaskImported?(task: ExternalTask, goal: Goal): Promise<void> | void;
+}
+/**
+ * Shape of a plugin module: the default export is a factory taking the
+ * declaration's `settings` (spec 003 §R1). Tests construct plugins directly.
+ */
+export type OrcPluginModule = {
+    default: (settings: Record<string, unknown>) => OrcPlugin;
+};
+/** One entry of `<stateDir>/plugins.json` (spec 003 §R3). */
+export interface PluginDeclaration {
+    name: string;
+    /** Absolute path to an ESM module, or a builtin alias (e.g. `"linear"`). */
+    specifier: string;
+    enabled: boolean;
+    settings?: Record<string, unknown>;
+}
+/** Load status of a declared plugin, as reported by `GET /api/plugins` (§R3). */
+export interface PluginStatus {
+    name: string;
+    version: string | null;
+    capabilities: PluginCapability[];
+    enabled: boolean;
+    status: "active" | "disabled" | "error";
+    error?: string;
+}
+//# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.d.ts.map

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

package/dist/plugins.js

@@ -0,0 +1,12 @@
+/**
+ * Plugin contract (spec 003 §R1). Types only — the host implementation lives
+ * in `@orc-brain/core` (`src/plugins/`). Third-party plugins depend on
+ * `@orc-brain/shared` alone and export a default factory returning an
+ * {@link OrcPlugin}. See `packages/plugin-linear` for the reference plugin.
+ */
+/**
+ * Version of this contract. The registry refuses to load a plugin whose
+ * manifest declares a different `apiVersion` (spec 003 §R3).
+ */
+export const PLUGIN_API_VERSION = 1;
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@orc-brain/shared",
+  "version": "1.0.0",
+  "description": "Shared types and event schemas for orc-brain (no runtime logic).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Paulo Lima",
+  "homepage": "https://github.com/anplabs/orc-brain#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anplabs/orc-brain.git",
+    "directory": "packages/shared"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}