@xenosystem/agent-sdk 0.9.21 → 0.9.24

package/dist/coordination/index.d.cts

@@ -0,0 +1,395 @@
+declare const XENO_COORDINATION_SCHEMA_VERSION: 1;
+type XenoGoalStatus = "active" | "paused" | "waiting" | "blocked" | "completed" | "failed" | "cancelled";
+type XenoGoalTaskStatus = "pending" | "ready" | "running" | "blocked" | "failed" | "completed" | "cancelled" | "interrupted";
+interface XenoGoalCriterion {
+    id: string;
+    description: string;
+    required: boolean;
+}
+interface XenoGoalCriterionResult {
+    criterionId: string;
+    satisfied: boolean;
+    evidence: string[];
+    reason: string;
+    evaluatedAt: string;
+}
+interface XenoGoalVerification {
+    status: "pending" | "running" | "passed" | "failed";
+    criteria: XenoGoalCriterionResult[];
+    evidence: string[];
+    summary?: string;
+    verifiedAt?: string;
+    verifiedBy?: string;
+}
+interface XenoGoalTask {
+    id: string;
+    milestoneId: string;
+    parentTaskId?: string;
+    title: string;
+    description?: string;
+    status: XenoGoalTaskStatus;
+    assignedAgentId?: string;
+    dependsOn?: string[];
+    progress?: string;
+    resultEventId?: string;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+interface XenoGoalMilestone {
+    id: string;
+    title: string;
+    description?: string;
+    status: "pending" | "active" | "blocked" | "completed" | "cancelled";
+    taskIds: string[];
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+interface XenoGoalProgress {
+    summary: string;
+    currentMilestoneId?: string;
+    currentTaskId?: string;
+    completedTaskCount: number;
+    totalTaskCount: number;
+    percent?: number;
+    outstanding: string[];
+    decisions: string[];
+    updatedAt: string;
+}
+interface XenoGoalRecord {
+    schemaVersion: typeof XENO_COORDINATION_SCHEMA_VERSION;
+    id: string;
+    version: number;
+    sessionId: string;
+    objective: string;
+    why?: string;
+    successCriteria: XenoGoalCriterion[];
+    constraints: string[];
+    limits?: {
+        maxIterations?: number;
+        maxTokens?: number;
+        maxWallClockMs?: number;
+    };
+    metadata: Record<string, string | number | boolean>;
+    status: XenoGoalStatus;
+    milestones: XenoGoalMilestone[];
+    tasks: XenoGoalTask[];
+    progress: XenoGoalProgress;
+    verification: XenoGoalVerification;
+    steering: Array<{
+        id: string;
+        instruction: string;
+        createdAt: string;
+        consumedAt?: string;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+type XenoLoopKind = "agentic-development" | "goal-continuation" | "scheduled";
+type XenoLoopStatus = "running" | "paused" | "waiting" | "stopped" | "completed" | "failed";
+interface XenoLoopSchedule {
+    kind: "fixed-interval" | "dynamic";
+    intervalMs?: number;
+    nextRunAt?: string;
+    expiresAt?: string;
+}
+interface XenoLoopIteration {
+    number: number;
+    startedAt: string;
+    completedAt?: string;
+    status: "running" | "completed" | "failed" | "interrupted";
+    activity: string;
+    taskId?: string;
+    verificationEventId?: string;
+    error?: string;
+}
+interface XenoLoopRecord {
+    schemaVersion: typeof XENO_COORDINATION_SCHEMA_VERSION;
+    id: string;
+    version: number;
+    sessionId: string;
+    goalId?: string;
+    kind: XenoLoopKind;
+    status: XenoLoopStatus;
+    currentActivity?: string;
+    iterations: XenoLoopIteration[];
+    schedule?: XenoLoopSchedule;
+    stopReason?: string;
+    createdAt: string;
+    updatedAt: string;
+    stoppedAt?: string;
+}
+type XenoHandoffStatus = "prepared" | "available" | "claimed" | "completed" | "failed" | "cancelled";
+interface XenoHandoffOperation {
+    operationId: string;
+    kind: "tool" | "command" | "build" | "subagent" | "other";
+    status: "running" | "completed" | "interrupted";
+    sideEffecting: boolean;
+    recovery: "waited" | "resume" | "retry" | "manual";
+}
+interface XenoHandoffRecord {
+    schemaVersion: typeof XENO_COORDINATION_SCHEMA_VERSION;
+    id: string;
+    version: number;
+    sessionId: string;
+    goalId?: string;
+    loopId?: string;
+    status: XenoHandoffStatus;
+    sourceOwnerId: string;
+    targetOwnerId?: string;
+    claimedBy?: string;
+    sourceLeaseEpoch: number;
+    targetLeaseEpoch?: number;
+    workspace?: string;
+    branch?: string;
+    currentMilestoneId?: string;
+    currentTaskId?: string;
+    agentIds: string[];
+    operations: XenoHandoffOperation[];
+    contextDigest?: string;
+    createdAt: string;
+    updatedAt: string;
+    claimedAt?: string;
+    completedAt?: string;
+    failedAt?: string;
+    failureReason?: string;
+}
+interface XenoExecutionOwner {
+    ownerId: string;
+    leaseId: string;
+    epoch: number;
+    acquiredAt: string;
+    heartbeatAt: string;
+    expiresAt: string;
+    processId?: number;
+    host?: string;
+}
+type XenoCoordinationEventType = "goal.created" | "goal.updated" | "goal.steered" | "goal.completed" | "goal.cancelled" | "loop.started" | "loop.iteration" | "loop.paused" | "loop.waiting" | "loop.resumed" | "loop.stopped" | "loop.completed" | "loop.failed" | "handoff.created" | "handoff.claimed" | "handoff.completed" | "handoff.failed" | "ownership.acquired" | "ownership.renewed" | "ownership.released";
+interface XenoCoordinationEvent {
+    schemaVersion: typeof XENO_COORDINATION_SCHEMA_VERSION;
+    id: string;
+    sequence: number;
+    type: XenoCoordinationEventType;
+    sessionId: string;
+    goalId?: string;
+    loopId?: string;
+    handoffId?: string;
+    ownerId?: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+interface XenoCoordinationSessionState {
+    schemaVersion: typeof XENO_COORDINATION_SCHEMA_VERSION;
+    sessionId: string;
+    version: number;
+    ownershipEpoch: number;
+    owner?: XenoExecutionOwner;
+    goals: XenoGoalRecord[];
+    loops: XenoLoopRecord[];
+    handoffs: XenoHandoffRecord[];
+    events: XenoCoordinationEvent[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface XenoCoordinationStoreOptions {
+    rootDirectory?: string;
+    now?: () => string;
+    idFactory?: (prefix: string) => string;
+    ownerLeaseMs?: number;
+    lockTimeoutMs?: number;
+    lockStaleMs?: number;
+    maximumEventsPerSession?: number;
+}
+interface CreateXenoGoalInput {
+    sessionId: string;
+    objective: string;
+    why?: string;
+    successCriteria?: Array<string | Omit<XenoGoalCriterion, "id"> & {
+        id?: string;
+    }>;
+    constraints?: string[];
+    limits?: XenoGoalRecord["limits"];
+    metadata?: Record<string, string | number | boolean>;
+}
+interface CreateXenoHandoffInput {
+    sessionId: string;
+    sourceOwnerId: string;
+    sourceLeaseId: string;
+    goalId?: string;
+    loopId?: string;
+    targetOwnerId?: string;
+    workspace?: string;
+    branch?: string;
+    currentMilestoneId?: string;
+    currentTaskId?: string;
+    agentIds?: string[];
+    operations?: XenoHandoffOperation[];
+    contextDigest?: string;
+}
+declare class XenoCoordinationError extends Error {
+    readonly code: "INVALID" | "NOT_FOUND" | "CONFLICT" | "NOT_OWNER" | "LEASE_EXPIRED" | "UNSAFE_HANDOFF" | "VERIFICATION_REQUIRED";
+    readonly details: Record<string, unknown>;
+    constructor(code: "INVALID" | "NOT_FOUND" | "CONFLICT" | "NOT_OWNER" | "LEASE_EXPIRED" | "UNSAFE_HANDOFF" | "VERIFICATION_REQUIRED", message: string, details?: Record<string, unknown>);
+}
+interface UpdateXenoGoalInput {
+    objective?: string;
+    why?: string;
+    constraints?: string[];
+    successCriteria?: XenoGoalCriterion[];
+    status?: Exclude<XenoGoalStatus, "completed">;
+    progress?: Partial<Omit<XenoGoalProgress, "updatedAt">>;
+    verification?: XenoGoalVerification;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface StartXenoLoopInput {
+    sessionId: string;
+    goalId?: string;
+    kind: XenoLoopKind;
+    activity?: string;
+    schedule?: XenoLoopSchedule;
+}
+interface ClaimXenoHandoffInput {
+    sessionId: string;
+    handoffId: string;
+    targetOwnerId: string;
+    processId?: number;
+    host?: string;
+}
+declare class DurableXenoCoordinationStore {
+    private readonly rootDirectory;
+    private readonly now;
+    private readonly idFactory;
+    private readonly ownerLeaseMs;
+    private readonly lockTimeoutMs;
+    private readonly lockStaleMs;
+    private readonly maximumEventsPerSession;
+    constructor(options?: XenoCoordinationStoreOptions);
+    getSessionState(sessionId: string): Promise<XenoCoordinationSessionState>;
+    listSessionStates(): Promise<XenoCoordinationSessionState[]>;
+    createGoal(input: CreateXenoGoalInput): Promise<XenoGoalRecord>;
+    getGoal(sessionId: string, goalId?: string): Promise<XenoGoalRecord | undefined>;
+    updateGoal(sessionId: string, goalId: string, expectedVersion: number, update: UpdateXenoGoalInput): Promise<XenoGoalRecord>;
+    addMilestone(sessionId: string, goalId: string, expectedVersion: number, input: {
+        title: string;
+        description?: string;
+    }): Promise<XenoGoalRecord>;
+    addTask(sessionId: string, goalId: string, expectedVersion: number, input: {
+        milestoneId: string;
+        parentTaskId?: string;
+        title: string;
+        description?: string;
+        assignedAgentId?: string;
+        dependsOn?: string[];
+    }): Promise<XenoGoalRecord>;
+    updateTask(sessionId: string, goalId: string, taskId: string, expectedVersion: number, update: Pick<XenoGoalTask, "status"> & Partial<Pick<XenoGoalTask, "progress" | "resultEventId" | "assignedAgentId">>): Promise<XenoGoalRecord>;
+    steerGoal(sessionId: string, goalId: string, expectedVersion: number, instruction: string): Promise<XenoGoalRecord>;
+    consumeGoalSteering(sessionId: string, goalId: string, expectedVersion: number): Promise<{
+        goal: XenoGoalRecord;
+        instructions: Array<{
+            id: string;
+            instruction: string;
+            createdAt: string;
+        }>;
+    }>;
+    completeGoal(sessionId: string, goalId: string, expectedVersion: number, verification: XenoGoalVerification): Promise<XenoGoalRecord>;
+    cancelGoal(sessionId: string, goalId: string, expectedVersion: number, reason: string): Promise<XenoGoalRecord>;
+    startLoop(input: StartXenoLoopInput): Promise<XenoLoopRecord>;
+    getLoop(sessionId: string, loopId?: string): Promise<XenoLoopRecord | undefined>;
+    beginLoopIteration(sessionId: string, loopId: string, expectedVersion: number, activity: string, taskId?: string): Promise<XenoLoopRecord>;
+    finishLoopIteration(sessionId: string, loopId: string, expectedVersion: number, result: {
+        status: "completed" | "failed" | "interrupted";
+        verificationEventId?: string;
+        error?: string;
+        nextStatus?: Extract<XenoLoopStatus, "running" | "waiting" | "failed">;
+    }): Promise<XenoLoopRecord>;
+    setLoopStatus(sessionId: string, loopId: string, expectedVersion: number, status: Extract<XenoLoopStatus, "paused" | "running" | "waiting" | "stopped" | "completed" | "failed">, reason?: string): Promise<XenoLoopRecord>;
+    acquireOwnership(sessionId: string, ownerId: string, options?: {
+        processId?: number;
+        host?: string;
+        leaseMs?: number;
+    }): Promise<XenoExecutionOwner>;
+    renewOwnership(sessionId: string, ownerId: string, leaseId: string, leaseMs?: number): Promise<XenoExecutionOwner>;
+    releaseOwnership(sessionId: string, ownerId: string, leaseId: string): Promise<XenoExecutionOwner>;
+    createHandoff(input: CreateXenoHandoffInput): Promise<XenoHandoffRecord>;
+    claimHandoff(input: ClaimXenoHandoffInput): Promise<{
+        handoff: XenoHandoffRecord;
+        owner: XenoExecutionOwner;
+    }>;
+    completeHandoff(sessionId: string, handoffId: string, ownerId: string, leaseId: string): Promise<XenoHandoffRecord>;
+    failHandoff(sessionId: string, handoffId: string, reason: string): Promise<XenoHandoffRecord>;
+    private mutateGoal;
+    private mutateLoop;
+    private recalculateProgress;
+    private requireGoal;
+    private requireOwner;
+    private assertVersion;
+    private newOwner;
+    private ownerExpired;
+    private appendEvent;
+    private mutate;
+    private statePath;
+    private lockPath;
+    private readState;
+    private writeState;
+    private renameReplacing;
+    private withSessionLock;
+    private staleLockOwner;
+    private quarantineLock;
+}
+type XenoCoordinationAction = "state.get" | "goal.create" | "goal.update" | "goal.complete" | "goal.cancel" | "goal.steer" | "loop.start" | "loop.get" | "loop.begin" | "loop.finish" | "loop.set_status" | "ownership.acquire" | "ownership.renew" | "ownership.release" | "handoff.create" | "handoff.claim" | "handoff.complete" | "handoff.fail";
+interface ExecuteXenoCoordinationActionInput {
+    action: XenoCoordinationAction;
+    sessionId: string;
+    payload?: Record<string, unknown>;
+}
+interface ExecuteXenoCoordinationActionResult {
+    action: XenoCoordinationAction;
+    sessionId: string;
+    result: unknown;
+    state: XenoCoordinationSessionState;
+    event?: XenoCoordinationEvent;
+}
+declare function executeXenoCoordinationAction(store: DurableXenoCoordinationStore, input: ExecuteXenoCoordinationActionInput): Promise<ExecuteXenoCoordinationActionResult>;
+interface XenoExecutionLeaseSessionOptions {
+    store?: DurableXenoCoordinationStore;
+    sessionId: string;
+    ownerId?: string;
+    processId?: number;
+    host?: string;
+    leaseMs?: number;
+    heartbeatMs?: number;
+    claimHandoffId?: string;
+    onOwnershipLost?: (error: unknown) => void;
+}
+declare class XenoExecutionLeaseSession {
+    readonly sessionId: string;
+    readonly ownerId: string;
+    private readonly store;
+    private readonly processId;
+    private readonly host;
+    private readonly leaseMs;
+    private readonly heartbeatMs;
+    private readonly claimHandoffId?;
+    private readonly onOwnershipLost?;
+    private timer?;
+    private heartbeatInFlight;
+    private owner?;
+    private stopped;
+    private lostError?;
+    private preparedHandoffId?;
+    constructor(options: XenoExecutionLeaseSessionOptions);
+    get currentOwner(): XenoExecutionOwner | undefined;
+    get active(): boolean;
+    start(): Promise<XenoExecutionOwner>;
+    assertOwned(): Promise<XenoExecutionOwner>;
+    private renewHeldLease;
+    prepareHandoff(input?: Omit<CreateXenoHandoffInput, "sessionId" | "sourceOwnerId" | "sourceLeaseId">): Promise<XenoHandoffRecord>;
+    stop(options?: {
+        release?: boolean;
+    }): Promise<void>;
+    private heartbeat;
+    private markLost;
+}
+export { type ClaimXenoHandoffInput, type CreateXenoGoalInput, type CreateXenoHandoffInput, DurableXenoCoordinationStore, type ExecuteXenoCoordinationActionInput, type ExecuteXenoCoordinationActionResult, type StartXenoLoopInput, type UpdateXenoGoalInput, XENO_COORDINATION_SCHEMA_VERSION, type XenoCoordinationAction, XenoCoordinationError, type XenoCoordinationEvent, type XenoCoordinationEventType, type XenoCoordinationSessionState, type XenoCoordinationStoreOptions, XenoExecutionLeaseSession, type XenoExecutionLeaseSessionOptions, type XenoExecutionOwner, type XenoGoalCriterion, type XenoGoalCriterionResult, type XenoGoalMilestone, type XenoGoalProgress, type XenoGoalRecord, type XenoGoalStatus, type XenoGoalTask, type XenoGoalTaskStatus, type XenoGoalVerification, type XenoHandoffOperation, type XenoHandoffRecord, type XenoHandoffStatus, type XenoLoopIteration, type XenoLoopKind, type XenoLoopRecord, type XenoLoopSchedule, type XenoLoopStatus, executeXenoCoordinationAction };