@forge-sdk/collab

import * as api from '@forge-sdk/collab';

export const CollabErrorCode /* type inferred in source */;

export type CollabErrorCodeType =
  (typeof CollabErrorCode)[keyof typeof CollabErrorCode];

export class CollabError extends Error {
  readonly code: CollabErrorCodeType;
  static sessionNotFound(sessionId: string): CollabError;
  static sessionAlreadyActive(sessionId: string): CollabError;
  static sessionTimedOut(sessionId: string): CollabError;
  static invalidSessionTransition(from: string, to: string): CollabError;
  static notAParticipant(agentDid: string, sessionId: string): CollabError;
  static taskNotFound(taskId: string): CollabError;
  static taskAlreadyAssigned(taskId: string, assignee: string): CollabError;
  static capabilityMismatch(
    taskType: string,
    agentDid: string,
    reason: string
  ): CollabError;
  static contextKeyNotFound(key: string): CollabError;
  static contextPermissionDenied(key: string, agentDid: string): CollabError;
  static interruptRejected(interruptId: string, reason: string): CollabError;
  static delegationFailed(reason: string): CollabError;
  static roleViolation(
    agentDid: string,
    role: string,
    action: string
  ): CollabError;
}

export {
  CollaborationRole,
  type CollaborationRoleType,
  SessionState,
  type SessionStateType,
  validSessionTransitions,
  isSessionTerminal,
  type SessionParticipant,
  type CollaborationSession,
  type SessionTransition,
  TaskPriority,
  type TaskPriorityType,
  TaskStatus,
  type TaskStatusType,
  type TaskConstraints,
  defaultTaskConstraints,
  type DelegatedTask,
  type TaskResult,
  type TaskAcknowledgment,
  type TaskProgress,
  InterruptType,
  type InterruptTypeType,
  type Interrupt,
  type InterruptResponse,
  type InterruptedState,
  ContextVisibility,
  type ContextVisibilityType,
  type ContextEntry,
  type AgentCapabilityProfile,
} from './types.js';

export { SessionManager } from './session.js';

export {
  type CoordinatorContract,
  type WorkerContract,
  type PeerContract,
} from './roles.js';

export {
  CollabErrorCode,
  type CollabErrorCodeType,
  CollabError,
} from './error.js';

export interface CoordinatorContract {
  /**
   * Decomposes a high-level task into smaller sub-tasks.
   *
   * @param task - The task to decompose.
   * @returns A list of sub-tasks derived from the original task.
   * @throws {CollabError} DelegationFailed if the task cannot be decomposed.
   */
  decomposeTask(task: DelegatedTask): Promise<DelegatedTask[]>;

  /**
   * Assigns a task to a specific worker agent.
   *
   * @param task - The task to assign.
   * @param workerDid - The OAS DID of the target worker.
   * @returns A TaskAcknowledgment from the worker.
   * @throws {CollabError} CapabilityMismatch or DelegationFailed.
   */
  assignTask(
    task: DelegatedTask,
    workerDid: string
  ): Promise<TaskAcknowledgment>;

  /**
   * Aggregates results from multiple worker tasks into a single result.
   *
   * @param results - The results from all completed sub-tasks.
   * @returns A single aggregated TaskResult.
   * @throws {CollabError} DelegationFailed if results cannot be aggregated.
   */
  aggregateResults(results: readonly TaskResult[]): Promise<TaskResult>;

  /**
   * Handles a failure reported by a worker.
   *
   * @param taskId - The ID of the failed task.
   * @param workerDid - The DID of the worker that failed.
   * @param error - A description of the failure.
   * @throws {CollabError} DelegationFailed if recovery is not possible.
   */
  handleWorkerFailure(
    taskId: string,
    workerDid: string,
    error: string
  ): Promise<void>;
}

export interface WorkerContract {
  /**
   * Called when a task is delegated to this worker.
   *
   * @param task - The delegated task to evaluate.
   * @returns A TaskAcknowledgment indicating acceptance or rejection.
   */
  onTaskDelegated(task: DelegatedTask): Promise<TaskAcknowledgment>;

  /**
   * Reports progress on an in-flight task.
   *
   * @param progress - The progress report.
   * @throws {CollabError} TaskNotFound if the task ID is unknown.
   */
  reportProgress(progress: TaskProgress): Promise<void>;

  /**
   * Submits the result of a completed task.
   *
   * @param result - The task result to submit.
   * @throws {CollabError} TaskNotFound if the task ID is unknown.
   */
  submitResult(result: TaskResult): Promise<void>;

  /**
   * Called when a task is cancelled by the coordinator.
   *
   * @param taskId - The ID of the cancelled task.
   * @param reason - A human-readable cancellation reason.
   */
  onTaskCancelled(taskId: string, reason: string): Promise<void>;
}

export interface PeerContract {
  /**
   * Submits a proposal for peer consensus.
   *
   * @param proposal - The proposal data to submit for voting.
   * @returns A unique proposal ID string.
   */
  propose(proposal: unknown): Promise<string>;

  /**
   * Votes on an existing proposal.
   *
   * @param proposalId - The ID of the proposal to vote on.
   * @param approve - true to approve, false to reject.
   */
  vote(proposalId: string, approve: boolean): Promise<void>;

  /**
   * Called when consensus is reached on a proposal.
   *
   * @param proposalId - The ID of the proposal that reached consensus.
   * @param result - The consensus result data.
   */
  onConsensus(proposalId: string, result: unknown): Promise<void>;
}

export class SessionManager {
  constructor();
  get state(): SessionStateType;
  get history(): readonly SessionTransition[];
  transition(target: SessionStateType): SessionTransition;
  canTransitionTo(target: SessionStateType): boolean;
  validTransitions(): readonly SessionStateType[];
  isTerminal(): boolean;
}

export const CollaborationRole /* type inferred in source */;

export type CollaborationRoleType =
  (typeof CollaborationRole)[keyof typeof CollaborationRole];

export const SessionState /* type inferred in source */;

export type SessionStateType =
  (typeof SessionState)[keyof typeof SessionState];

export function validSessionTransitions(
  state: SessionStateType
): readonly SessionStateType[];

export function isSessionTerminal(state: SessionStateType): boolean;

export interface SessionParticipant {
  /** The OAS DID of the participating agent. */
  readonly agentDid: string;
  /** The role this agent plays in the session. */
  readonly role: CollaborationRoleType;
  /** ISO 8601 timestamp when the agent joined the session. */
  readonly joinedAt: string;
  /** Current participation status (e.g., "active", "left", "disconnected"). */
  readonly status: string;
}

export interface CollaborationSession {
  /** Unique identifier for this session. */
  readonly sessionId: string;
  /** The type of collaboration (e.g., "code-review", "data-analysis"). */
  readonly sessionType: string;
  /** The agents participating in this session. */
  readonly participants: readonly SessionParticipant[];
  /** The DID of the coordinator agent, if any. */
  readonly coordinator: string | undefined;
  /** The ID of the shared context store for this session. */
  readonly sharedContextId: string | undefined;
  /** ISO 8601 timestamp when the session was created. */
  readonly createdAt: string;
  /** Optional session timeout in seconds. */
  readonly timeoutSeconds: number | undefined;
  /** Arbitrary metadata for application-specific session properties. */
  readonly metadata: Record<string, unknown>;
}

export interface SessionTransition {
  /** The state before the transition. */
  readonly from: SessionStateType;
  /** The state after the transition. */
  readonly to: SessionStateType;
  /** ISO 8601 timestamp when the transition occurred. */
  readonly timestamp: string;
}

export const TaskPriority /* type inferred in source */;

export type TaskPriorityType =
  (typeof TaskPriority)[keyof typeof TaskPriority];

export const TaskStatus /* type inferred in source */;

export type TaskStatusType =
  (typeof TaskStatus)[keyof typeof TaskStatus];

export interface TaskConstraints {
  /** Maximum number of reasoning steps the worker may take. */
  readonly maxSteps: number | undefined;
  /** Maximum number of tokens the worker may consume. */
  readonly maxTokens: number | undefined;
  /** Maximum duration in seconds for task execution. */
  readonly maxDurationSeconds: number | undefined;
  /** Allowed tool names. If empty, no tool restrictions apply. */
  readonly allowedTools: readonly string[];
  /** Minimum required confidence score (0.0 to 1.0) for the result. */
  readonly requiredConfidence: number | undefined;
}

export function defaultTaskConstraints(): TaskConstraints;

export interface DelegatedTask {
  /** Unique identifier for this task. */
  readonly taskId: string;
  /** The type of task (e.g., "code-review", "summarize"). */
  readonly taskType: string;
  /** Human-readable description of the task. */
  readonly description: string;
  /** Input data for the task. */
  readonly input: unknown;
  /** Optional JSON Schema describing the expected output format. */
  readonly outputSchema: unknown | undefined;
  /** Constraints bounding the task execution. */
  readonly constraints: TaskConstraints;
  /** The OAS DID of the agent that delegated this task. */
  readonly delegator: string;
  /** Priority level for task scheduling. */
  readonly priority: TaskPriorityType;
  /** Optional ISO 8601 deadline for task completion. */
  readonly deadline: string | undefined;
  /** Keys in the shared context that this task may read. */
  readonly contextKeys: readonly string[];
}

export interface TaskResult {
  /** The ID of the task this result corresponds to. */
  readonly taskId: string;
  /** The completion status of the task. */
  readonly status: TaskStatusType;
  /** The output data produced by the worker. */
  readonly output: unknown;
  /** Optional confidence score (0.0 to 1.0) for the result. */
  readonly confidence: number | undefined;
  /** Arbitrary metadata about the task execution. */
  readonly metadata: Record<string, unknown>;
  /** Optional Ed25519 signature over the result for verification. */
  readonly signature: string | undefined;
}

export interface TaskAcknowledgment {
  /** The ID of the task being acknowledged. */
  readonly taskId: string;
  /** Whether the worker accepts the task. */
  readonly accepted: boolean;
  /** Reason for rejection, if accepted is false. */
  readonly rejectionReason: string | undefined;
  /** Estimated time to completion in seconds, if accepted. */
  readonly estimatedCompletionSeconds: number | undefined;
}

export interface TaskProgress {
  /** The ID of the task this progress report corresponds to. */
  readonly taskId: string;
  /** Completion percentage (0.0 to 100.0). */
  readonly percentage: number;
  /** Human-readable status message. */
  readonly message: string;
}

export const InterruptType /* type inferred in source */;

export type InterruptTypeType =
  (typeof InterruptType)[keyof typeof InterruptType];

export interface Interrupt {
  /** Unique identifier for this interrupt. */
  readonly interruptId: string;
  /** The type of interrupt. */
  readonly interruptType: InterruptTypeType;
  /** The OAS DID of the agent that sent the interrupt. */
  readonly source: string;
  /** Priority of the interrupt. */
  readonly priority: TaskPriorityType;
  /** Arbitrary payload data for the interrupt. */
  readonly payload: unknown;
  /** ISO 8601 timestamp when the interrupt was created. */
  readonly timestamp: string;
}

export interface InterruptResponse {
  /** The ID of the interrupt being responded to. */
  readonly interruptId: string;
  /** Whether the agent acknowledged and handled the interrupt. */
  readonly acknowledged: boolean;
  /** The agent's state at the time of interruption, if applicable. */
  readonly currentState: InterruptedState | undefined;
}

export interface InterruptedState {
  /** The ID of the task that was interrupted, if any. */
  readonly taskId: string | undefined;
  /** The number of steps completed before interruption. */
  readonly stepCount: number;
  /** Progress percentage at the time of interruption (0.0 to 100.0). */
  readonly progressPercentage: number;
  /** Whether the task can be resumed from this state. */
  readonly canResume: boolean;
}

export const ContextVisibility /* type inferred in source */;

export type ContextVisibilityType =
  (typeof ContextVisibility)[keyof typeof ContextVisibility];

export interface ContextEntry {
  /** The key identifying this context entry. */
  readonly key: string;
  /** The value stored in this entry. */
  readonly value: unknown;
  /** The type of the value (e.g., "json", "text", "binary"). */
  readonly valueType: string;
  /** The OAS DID of the agent that wrote this entry. */
  readonly author: string;
  /** Monotonically increasing version number for this key. */
  readonly version: number;
  /** ISO 8601 timestamp when this version was written. */
  readonly timestamp: string;
  /** Visibility scope for this entry. */
  readonly visibility: ContextVisibilityType;
  /** Role for role-scoped visibility, or agent DID for agent-scoped. */
  readonly visibilityTarget: string | undefined;
}

export interface AgentCapabilityProfile {
  /** The OAS DID of the agent. */
  readonly agentDid: string;
  /** Collaboration roles this agent supports. */
  readonly supportedRoles: readonly CollaborationRoleType[];
  /** Task types this agent can handle. */
  readonly supportedTaskTypes: readonly string[];
  /** Tool names available to this agent. */
  readonly availableTools: readonly string[];
  /** Current load factor (0.0 = idle, 1.0 = fully loaded). */
  readonly currentLoad: number;
  /** Maximum number of tasks this agent can execute concurrently. */
  readonly maxConcurrentTasks: number;
}