oxe-cc 1.0.0 → 1.2.1

package/lib/runtime/plugins/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./plugin-abi"), exports);
 __exportStar(require("./plugin-registry"), exports);
+__exportStar(require("./plugin-manifest"), exports);
+__exportStar(require("./capability-matrix"), exports);

package/lib/runtime/plugins/plugin-manifest.d.ts

@@ -0,0 +1,22 @@
+import type { OxePlugin } from './plugin-abi';
+export declare const CURRENT_ABI_VERSION = "1.0.0";
+export interface PluginManifest {
+    name: string;
+    version: string;
+    abi_version: string;
+    capabilities: Array<'tool' | 'workspace' | 'verifier' | 'context' | 'hooks'>;
+    tool_action_types?: string[];
+    workspace_strategies?: string[];
+    verifier_check_types?: string[];
+    context_provider_names?: string[];
+    hook_names?: string[];
+}
+export interface PluginValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export declare function extractManifest(plugin: OxePlugin): PluginManifest;
+export declare function validatePlugin(plugin: OxePlugin): PluginValidationResult;
+export declare function isAbiCompatible(pluginAbiVersion: string): boolean;
+export declare function sandboxInvoke<T>(fn: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/lib/runtime/plugins/plugin-manifest.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_ABI_VERSION = void 0;
+exports.extractManifest = extractManifest;
+exports.validatePlugin = validatePlugin;
+exports.isAbiCompatible = isAbiCompatible;
+exports.sandboxInvoke = sandboxInvoke;
+exports.CURRENT_ABI_VERSION = '1.0.0';
+function extractManifest(plugin) {
+    const capabilities = [];
+    if (plugin.toolProviders?.length)
+        capabilities.push('tool');
+    if (plugin.workspaceProviders?.length)
+        capabilities.push('workspace');
+    if (plugin.verifierProviders?.length)
+        capabilities.push('verifier');
+    if (plugin.contextProviders?.length)
+        capabilities.push('context');
+    if (plugin.hooks && Object.keys(plugin.hooks).length > 0)
+        capabilities.push('hooks');
+    return {
+        name: plugin.name,
+        version: plugin.version ?? '0.0.0',
+        abi_version: exports.CURRENT_ABI_VERSION,
+        capabilities,
+        tool_action_types: plugin.toolProviders?.flatMap((p) => ['read_code', 'generate_patch', 'run_tests', 'collect_evidence', 'custom'].filter((t) => p.supports(t))) ?? [],
+        workspace_strategies: plugin.workspaceProviders?.map((p) => p.name) ?? [],
+        verifier_check_types: plugin.verifierProviders?.flatMap((p) => ['unit', 'integration', 'smoke', 'policy', 'security', 'custom'].filter((t) => p.supports(t))) ?? [],
+        context_provider_names: plugin.contextProviders?.map((p) => p.name) ?? [],
+        hook_names: plugin.hooks ? Object.keys(plugin.hooks) : [],
+    };
+}
+function validatePlugin(plugin) {
+    const errors = [];
+    const warnings = [];
+    if (!plugin.name || typeof plugin.name !== 'string') {
+        errors.push('Plugin must have a non-empty string name');
+    }
+    if (plugin.version && !/^\d+\.\d+\.\d+/.test(plugin.version)) {
+        warnings.push(`Plugin version "${plugin.version}" does not follow semver`);
+    }
+    if (!plugin.toolProviders?.length &&
+        !plugin.workspaceProviders?.length &&
+        !plugin.verifierProviders?.length &&
+        !plugin.contextProviders?.length &&
+        !plugin.hooks) {
+        warnings.push('Plugin declares no providers or hooks — it has no effect');
+    }
+    // Validate each tool provider
+    for (const tp of plugin.toolProviders ?? []) {
+        if (!tp.name)
+            errors.push('ToolProvider missing name');
+        if (typeof tp.supports !== 'function')
+            errors.push(`ToolProvider "${tp.name}" missing supports() method`);
+        if (typeof tp.invoke !== 'function')
+            errors.push(`ToolProvider "${tp.name}" missing invoke() method`);
+    }
+    // Validate each workspace provider
+    for (const wp of plugin.workspaceProviders ?? []) {
+        if (!wp.name)
+            errors.push('WorkspaceProvider missing name');
+        if (typeof wp.supportsStrategy !== 'function')
+            errors.push(`WorkspaceProvider "${wp.name}" missing supportsStrategy()`);
+        if (typeof wp.allocate !== 'function')
+            errors.push(`WorkspaceProvider "${wp.name}" missing allocate()`);
+    }
+    // Validate each verifier provider
+    for (const vp of plugin.verifierProviders ?? []) {
+        if (!vp.name)
+            errors.push('VerifierProvider missing name');
+        if (typeof vp.supports !== 'function')
+            errors.push(`VerifierProvider "${vp.name}" missing supports()`);
+        if (typeof vp.execute !== 'function')
+            errors.push(`VerifierProvider "${vp.name}" missing execute()`);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+function isAbiCompatible(pluginAbiVersion) {
+    // Major version must match; minor/patch are backwards-compatible
+    const [currMajor] = exports.CURRENT_ABI_VERSION.split('.').map(Number);
+    const [plugMajor] = pluginAbiVersion.split('.').map(Number);
+    return currMajor === plugMajor;
+}
+function sandboxInvoke(fn, timeoutMs = 10000) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Plugin invocation timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        fn().then((result) => { clearTimeout(timer); resolve(result); }, (err) => { clearTimeout(timer); reject(err instanceof Error ? err : new Error(String(err))); });
+    });
+}

package/lib/runtime/plugins/plugin-registry.js

@@ -8,6 +8,7 @@ exports.globalRegistry = globalRegistry;
 exports.resetGlobalRegistry = resetGlobalRegistry;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const plugin_manifest_1 = require("./plugin-manifest");
 class PluginRegistry {
     constructor() {
         this.plugins = [];
@@ -16,6 +17,10 @@ class PluginRegistry {
         if (this.plugins.some((p) => p.name === plugin.name)) {
             throw new Error(`Plugin "${plugin.name}" is already registered`);
         }
+        const validation = (0, plugin_manifest_1.validatePlugin)(plugin);
+        if (!validation.valid && validation.errors.length > 0) {
+            throw new Error(`Plugin "${plugin.name}" failed validation: ${validation.errors.join('; ')}`);
+        }
         this.plugins.push(plugin);
     }
     unregister(name) {

package/lib/runtime/policy/policy-engine.d.ts

@@ -1,12 +1,27 @@
 export type PolicyAction = 'allow' | 'deny' | 'require_human_gate';
+export type SideEffectClass = 'read_fs' | 'write_fs' | 'spawn_process' | 'network_call' | 'git_mutation' | 'db_change' | 'secret_access' | 'infra_operation';
+export type AutonomyTier = 'L0' | 'L1' | 'L2' | 'L3';
 export interface PolicyWhenClause {
     tool?: string;
     env?: string;
     kind?: string;
+    side_effect_class?: SideEffectClass;
+    autonomy_tier?: AutonomyTier;
 }
 export interface PolicyAssertClause {
     diff_within_scope?: boolean;
 }
+export interface NodePolicyConfig {
+    max_retries: number;
+    mutation_budget?: number;
+    autonomy_tier?: AutonomyTier;
+    allowed_side_effects?: SideEffectClass[];
+}
+export interface EnvironmentGuardrail {
+    protected_paths: string[];
+    protected_branches: string[];
+    require_human_gate_on: SideEffectClass[];
+}
 export interface PolicyRule {
     id: string;
     when: PolicyWhenClause;
@@ -19,6 +34,10 @@ export interface PolicyContext {
     kind?: string;
     mutation_scope?: string[];
     affected_paths?: string[];
+    side_effect_class?: SideEffectClass;
+    autonomy_tier?: AutonomyTier;
+    mutation_count?: number;
+    node_policy?: NodePolicyConfig;
 }
 export interface PolicyDecision {
     allowed: boolean;
@@ -28,13 +47,21 @@ export interface PolicyDecision {
 }
 export declare class PolicyEngine {
     private readonly rules;
-    constructor(rules?: PolicyRule[]);
+    private readonly guardrail;
+    constructor(rules?: PolicyRule[], guardrail?: EnvironmentGuardrail);
     evaluate(ctx: PolicyContext): PolicyDecision;
+    private checkGuardrails;
+    private checkAutonomyTier;
+    private checkMutationBudget;
     private matches;
     private checkAssert;
     withRule(rule: PolicyRule): PolicyEngine;
+    withGuardrail(guardrail: EnvironmentGuardrail): PolicyEngine;
+    getGuardrail(): EnvironmentGuardrail;
     static fromConfig(config: {
         policies?: PolicyRule[];
+        guardrail?: EnvironmentGuardrail;
     }): PolicyEngine;
     static fromConfigFile(configPath: string): PolicyEngine;
+    static defaultGuardrail(): EnvironmentGuardrail;
 }

package/lib/runtime/policy/policy-engine.js

@@ -7,11 +7,37 @@ const ALLOW_ALL = {
     reason: 'no matching policy — default allow',
     rule_id: null,
 };
+const DEFAULT_GUARDRAIL = {
+    protected_paths: ['.oxe/config.json', '.env', 'package.json'],
+    protected_branches: ['main', 'master', 'production', 'release'],
+    require_human_gate_on: ['infra_operation', 'db_change', 'secret_access'],
+};
+// Autonomy tier → max side effect class allowed without a gate
+const TIER_SIDE_EFFECT_MAP = {
+    L0: ['read_fs'],
+    L1: ['read_fs', 'write_fs', 'spawn_process'],
+    L2: ['read_fs', 'write_fs', 'spawn_process', 'network_call', 'git_mutation'],
+    L3: ['read_fs', 'write_fs', 'spawn_process', 'network_call', 'git_mutation', 'db_change', 'secret_access', 'infra_operation'],
+};
 class PolicyEngine {
-    constructor(rules = []) {
+    constructor(rules = [], guardrail = DEFAULT_GUARDRAIL) {
         this.rules = rules;
+        this.guardrail = guardrail;
     }
     evaluate(ctx) {
+        // Check autonomy tier first — a denial takes priority over guardrail gates
+        const tierDecision = this.checkAutonomyTier(ctx);
+        if (tierDecision)
+            return tierDecision;
+        // Check environment guardrails (may require gate even when tier permits)
+        const guardrailDecision = this.checkGuardrails(ctx);
+        if (guardrailDecision)
+            return guardrailDecision;
+        // Check mutation budget
+        const budgetDecision = this.checkMutationBudget(ctx);
+        if (budgetDecision)
+            return budgetDecision;
+        // Evaluate rules (first match wins)
         for (const rule of this.rules) {
             if (!this.matches(rule.when, ctx))
                 continue;
@@ -37,6 +63,59 @@ class PolicyEngine {
         }
         return ALLOW_ALL;
     }
+    checkGuardrails(ctx) {
+        // Protected path check
+        const affected = ctx.affected_paths ?? [];
+        for (const p of affected) {
+            if (this.guardrail.protected_paths.some((pp) => p === pp || p.startsWith(pp + '/'))) {
+                return {
+                    allowed: true,
+                    gate_required: true,
+                    reason: `Protected path affected: ${p}`,
+                    rule_id: '__guardrail_path',
+                };
+            }
+        }
+        // Side effect class requiring gate
+        if (ctx.side_effect_class && this.guardrail.require_human_gate_on.includes(ctx.side_effect_class)) {
+            return {
+                allowed: true,
+                gate_required: true,
+                reason: `Side effect class '${ctx.side_effect_class}' requires human gate`,
+                rule_id: '__guardrail_side_effect',
+            };
+        }
+        return null;
+    }
+    checkAutonomyTier(ctx) {
+        if (!ctx.autonomy_tier || !ctx.side_effect_class)
+            return null;
+        const allowed = TIER_SIDE_EFFECT_MAP[ctx.autonomy_tier] ?? [];
+        if (!allowed.includes(ctx.side_effect_class)) {
+            return {
+                allowed: false,
+                gate_required: false,
+                reason: `Autonomy tier ${ctx.autonomy_tier} does not permit side effect '${ctx.side_effect_class}'`,
+                rule_id: '__autonomy_tier',
+            };
+        }
+        return null;
+    }
+    checkMutationBudget(ctx) {
+        const budget = ctx.node_policy?.mutation_budget;
+        if (budget === undefined || budget === null)
+            return null;
+        const count = ctx.mutation_count ?? 0;
+        if (count >= budget) {
+            return {
+                allowed: false,
+                gate_required: false,
+                reason: `Mutation budget exhausted: ${count}/${budget}`,
+                rule_id: '__mutation_budget',
+            };
+        }
+        return null;
+    }
     matches(when, ctx) {
         if (when.tool && when.tool !== ctx.tool)
             return false;
@@ -44,6 +123,10 @@ class PolicyEngine {
             return false;
         if (when.kind && when.kind !== ctx.kind)
             return false;
+        if (when.side_effect_class && when.side_effect_class !== ctx.side_effect_class)
+            return false;
+        if (when.autonomy_tier && when.autonomy_tier !== ctx.autonomy_tier)
+            return false;
         return true;
     }
     checkAssert(assert, ctx) {
@@ -51,7 +134,7 @@ class PolicyEngine {
             const scope = ctx.mutation_scope ?? [];
             const affected = ctx.affected_paths ?? [];
             if (scope.length === 0)
-                return null; // no scope declared — pass
+                return null;
             const outsideScope = affected.filter((p) => !scope.some((s) => p.startsWith(s) || s.startsWith(p)));
             if (outsideScope.length > 0) {
                 return `paths outside mutation scope: ${outsideScope.join(', ')}`;
@@ -60,14 +143,19 @@ class PolicyEngine {
         return null;
     }
     withRule(rule) {
-        return new PolicyEngine([...this.rules, rule]);
+        return new PolicyEngine([...this.rules, rule], this.guardrail);
+    }
+    withGuardrail(guardrail) {
+        return new PolicyEngine(this.rules, guardrail);
+    }
+    getGuardrail() {
+        return this.guardrail;
     }
     static fromConfig(config) {
-        return new PolicyEngine(config.policies ?? []);
+        return new PolicyEngine(config.policies ?? [], config.guardrail ?? DEFAULT_GUARDRAIL);
     }
     static fromConfigFile(configPath) {
         try {
-            // Dynamic require to avoid bundling issues
             // eslint-disable-next-line @typescript-eslint/no-var-requires
             const cfg = require(configPath);
             return PolicyEngine.fromConfig(cfg);
@@ -76,5 +164,8 @@ class PolicyEngine {
             return new PolicyEngine();
         }
     }
+    static defaultGuardrail() {
+        return { ...DEFAULT_GUARDRAIL };
+    }
 }
 exports.PolicyEngine = PolicyEngine;

package/lib/runtime/reducers/run-state-reducer.d.ts

@@ -3,6 +3,17 @@ import type { Run } from '../models/run';
 import type { WorkItem } from '../models/work-item';
 import type { Attempt } from '../models/attempt';
 import type { Workspace } from '../models/workspace';
+export interface PolicyDecisionRecord {
+    allowed: boolean;
+    gate_required: boolean;
+    reason: string;
+    rule_id: string | null;
+}
+export interface ToolFailureRecord {
+    tool: string;
+    error: string;
+    timestamp: string;
+}
 export interface RunState {
     run: Run | null;
     workItems: Map<string, WorkItem>;
@@ -11,6 +22,16 @@ export interface RunState {
     completedWorkItems: Set<string>;
     failedWorkItems: Set<string>;
     blockedWorkItems: Set<string>;
+    retryCounts: Map<string, number>;
+    policyDecisions: Map<string, PolicyDecisionRecord>;
+    pendingGates: Set<string>;
+    resolvedGates: Map<string, {
+        decision: string;
+        actor?: string;
+    }>;
+    verificationStatus: Map<string, 'started' | 'completed' | 'failed'>;
+    evidenceRefs: Map<string, string[]>;
+    toolFailures: Map<string, ToolFailureRecord[]>;
 }
 export declare function createEmptyRunState(): RunState;
 export declare function reduce(events: OxeEvent[]): RunState;
@@ -18,3 +39,8 @@ export { applyEvent as applyEventExported };
 declare function applyEvent(state: RunState, event: OxeEvent): RunState;
 export declare function getWorkItemStatus(state: RunState, workItemId: string): WorkItem['status'] | null;
 export declare function getAttemptCount(state: RunState, workItemId: string): number;
+export declare function getRetryCount(state: RunState, workItemId: string): number;
+export declare function getPolicyDecision(state: RunState, workItemId: string): PolicyDecisionRecord | null;
+export declare function getVerificationStatus(state: RunState, workItemId: string): 'started' | 'completed' | 'failed' | null;
+export declare function getEvidenceRefs(state: RunState, workItemId: string): string[];
+export declare function getToolFailures(state: RunState, workItemId: string): ToolFailureRecord[];

package/lib/runtime/reducers/run-state-reducer.js

@@ -5,6 +5,11 @@ exports.reduce = reduce;
 exports.applyEventExported = applyEvent;
 exports.getWorkItemStatus = getWorkItemStatus;
 exports.getAttemptCount = getAttemptCount;
+exports.getRetryCount = getRetryCount;
+exports.getPolicyDecision = getPolicyDecision;
+exports.getVerificationStatus = getVerificationStatus;
+exports.getEvidenceRefs = getEvidenceRefs;
+exports.getToolFailures = getToolFailures;
 function createEmptyRunState() {
     return {
         run: null,
@@ -14,6 +19,13 @@ function createEmptyRunState() {
         completedWorkItems: new Set(),
         failedWorkItems: new Set(),
         blockedWorkItems: new Set(),
+        retryCounts: new Map(),
+        policyDecisions: new Map(),
+        pendingGates: new Set(),
+        resolvedGates: new Map(),
+        verificationStatus: new Map(),
+        evidenceRefs: new Map(),
+        toolFailures: new Map(),
     };
 }
 function reduce(events) {
@@ -43,7 +55,6 @@ function applyEvent(state, event) {
                 workItems.set(event.work_item_id, { ...existing, status: 'ready' });
             }
             else {
-                // First time we see this work item — create from payload
                 const item = event.payload;
                 workItems.set(event.work_item_id, { ...item, work_item_id: event.work_item_id, status: 'ready' });
             }
@@ -85,6 +96,14 @@ function applyEvent(state, event) {
                 workItems.set(event.work_item_id, { ...item, status: 'completed' });
             const completedWorkItems = new Set(state.completedWorkItems);
             completedWorkItems.add(event.work_item_id);
+            // Collect evidence refs from payload
+            const evidence = event.payload.evidence ?? [];
+            if (evidence.length > 0) {
+                const evidenceRefs = new Map(state.evidenceRefs);
+                const existing = evidenceRefs.get(event.work_item_id) ?? [];
+                evidenceRefs.set(event.work_item_id, [...existing, ...evidence]);
+                return { ...state, workItems, completedWorkItems, evidenceRefs };
+            }
             return { ...state, workItems, completedWorkItems };
         }
         case 'WorkItemBlocked': {
@@ -98,6 +117,88 @@ function applyEvent(state, event) {
             blockedWorkItems.add(event.work_item_id);
             return { ...state, workItems, blockedWorkItems };
         }
+        case 'RetryScheduled': {
+            if (!event.work_item_id)
+                return state;
+            const retryCounts = new Map(state.retryCounts);
+            const current = retryCounts.get(event.work_item_id) ?? 0;
+            retryCounts.set(event.work_item_id, current + 1);
+            return { ...state, retryCounts };
+        }
+        case 'PolicyEvaluated': {
+            const p = event.payload;
+            const key = p.work_item_id ?? event.work_item_id;
+            if (!key)
+                return state;
+            const policyDecisions = new Map(state.policyDecisions);
+            policyDecisions.set(key, {
+                allowed: p.allowed ?? true,
+                gate_required: p.gate_required ?? false,
+                reason: p.reason ?? '',
+                rule_id: p.rule_id ?? null,
+            });
+            return { ...state, policyDecisions };
+        }
+        case 'GateRequested': {
+            const gateId = event.payload.gate_id;
+            if (!gateId)
+                return state;
+            const pendingGates = new Set(state.pendingGates);
+            pendingGates.add(gateId);
+            return { ...state, pendingGates };
+        }
+        case 'GateResolved': {
+            const p = event.payload;
+            if (!p.gate_id)
+                return state;
+            const pendingGates = new Set(state.pendingGates);
+            pendingGates.delete(p.gate_id);
+            const resolvedGates = new Map(state.resolvedGates);
+            resolvedGates.set(p.gate_id, { decision: p.decision ?? 'approved', actor: p.actor });
+            return { ...state, pendingGates, resolvedGates };
+        }
+        case 'VerificationStarted': {
+            const key = event.work_item_id ?? event.payload.work_item_id;
+            if (!key)
+                return state;
+            const verificationStatus = new Map(state.verificationStatus);
+            verificationStatus.set(key, 'started');
+            return { ...state, verificationStatus };
+        }
+        case 'VerificationCompleted': {
+            const p = event.payload;
+            const key = event.work_item_id ?? p.work_item_id;
+            if (!key)
+                return state;
+            const verificationStatus = new Map(state.verificationStatus);
+            verificationStatus.set(key, p.status ?? 'completed');
+            return { ...state, verificationStatus };
+        }
+        case 'ToolFailed': {
+            if (!event.work_item_id)
+                return state;
+            const p = event.payload;
+            const toolFailures = new Map(state.toolFailures);
+            const existing = toolFailures.get(event.work_item_id) ?? [];
+            toolFailures.set(event.work_item_id, [
+                ...existing,
+                { tool: p.tool ?? 'unknown', error: p.error ?? '', timestamp: event.timestamp },
+            ]);
+            return { ...state, toolFailures };
+        }
+        case 'EvidenceCollected': {
+            const p = event.payload;
+            const key = event.work_item_id ?? p.work_item_id;
+            if (!key)
+                return state;
+            const refs = p.refs ?? (p.ref ? [p.ref] : []);
+            if (refs.length === 0)
+                return state;
+            const evidenceRefs = new Map(state.evidenceRefs);
+            const existing = evidenceRefs.get(key) ?? [];
+            evidenceRefs.set(key, [...existing, ...refs]);
+            return { ...state, evidenceRefs };
+        }
         default:
             return state;
     }
@@ -108,3 +209,18 @@ function getWorkItemStatus(state, workItemId) {
 function getAttemptCount(state, workItemId) {
     return state.attempts.get(workItemId)?.length ?? 0;
 }
+function getRetryCount(state, workItemId) {
+    return state.retryCounts.get(workItemId) ?? 0;
+}
+function getPolicyDecision(state, workItemId) {
+    return state.policyDecisions.get(workItemId) ?? null;
+}
+function getVerificationStatus(state, workItemId) {
+    return state.verificationStatus.get(workItemId) ?? null;
+}
+function getEvidenceRefs(state, workItemId) {
+    return state.evidenceRefs.get(workItemId) ?? [];
+}
+function getToolFailures(state, workItemId) {
+    return state.toolFailures.get(workItemId) ?? [];
+}

package/lib/runtime/scheduler/agent-registry.d.ts

@@ -0,0 +1,44 @@
+import type { TaskExecutor } from './scheduler';
+import type { WorkspaceManager } from '../workspace/workspace-manager';
+import type { AgentRole, AgentActionLog } from './agent-roles';
+export type AgentStatus = 'idle' | 'running' | 'paused' | 'failed' | 'timeout';
+export interface AgentHeartbeat {
+    agent_id: string;
+    last_seen: string;
+    current_task: string | null;
+    status: AgentStatus;
+}
+export interface RegisteredAgent {
+    id: string;
+    executor: TaskExecutor;
+    workspaceManager: WorkspaceManager;
+    assignedTaskIds: string[];
+    heartbeat: AgentHeartbeat;
+    role?: AgentRole;
+    actionLog: AgentActionLog[];
+}
+export declare class AgentRegistry {
+    private agents;
+    private readonly heartbeatTimeoutMs;
+    constructor(heartbeatTimeoutMs?: number);
+    register(id: string, executor: TaskExecutor, workspaceManager: WorkspaceManager, assignedTaskIds?: string[], role?: AgentRole): RegisteredAgent;
+    unregister(id: string): void;
+    beat(id: string, currentTask?: string | null): void;
+    setStatus(id: string, status: AgentStatus): void;
+    isAlive(id: string): boolean;
+    /** Returns agents that haven't sent a heartbeat within the timeout window */
+    timedOut(): RegisteredAgent[];
+    liveAgents(): RegisteredAgent[];
+    get(id: string): RegisteredAgent | null;
+    list(): RegisteredAgent[];
+    /**
+     * Reassign orphaned tasks from timed-out agents to a fallback agent.
+     * Returns the list of task IDs that were reassigned.
+     */
+    failover(fallbackAgentId: string): string[];
+    /** Return all agents assigned to a given role */
+    getByRole(role: AgentRole): RegisteredAgent[];
+    /** Append an action log entry for a registered agent (no-op if unknown) */
+    logAction(agentId: string, log: AgentActionLog): void;
+    clear(): void;
+}