com.l1fe.forge:forge-collab

import com.l1fe.forge.collab.*

public data class AgentCapability(
val name: String,
val version: String;

public data class CapabilityAdvertisement(
@SerialName("agent_did")
val agentDid: String,
val capabilities: List<AgentCapability>,
@SerialName("max_concurrent_tasks")
val maxConcurrentTasks: Int;

public class CapabilityAdvertiser

public fun publish(advertisement: CapabilityAdvertisement)

public fun withdraw(agentDid: String): Boolean =

public fun getAdvertisement(agentDid: String): CapabilityAdvertisement? =

public fun findByCapability(capabilityName: String): List<CapabilityAdvertisement> =

public fun findByAllCapabilities(capabilityNames: Set<String>): List<CapabilityAdvertisement> =

public fun allAdvertisements(): List<CapabilityAdvertisement> =

public sealed class ForgeCollabError(
message: String,
cause: Throwable?;

public class SessionNotFound(
public val sessionId: String,
) : ForgeCollabError("collaboration session '$sessionId' not found")

/**
* A session is in an invalid state for the requested operation.
*
* ANVIL Spec Section 16.2 -- Session Lifecycle
*
* @property sessionId The session identifier.
* @property currentState The current session state.
* @property requiredState The required session state.
*/
public class InvalidSessionState(
public val sessionId: String,
public val currentState: String,
public val requiredState: String,
) : ForgeCollabError(
"session '$sessionId' is in state '$currentState' but must be in " +
"'$requiredState' for this operation (see ANVIL Spec SS16.2)"
)

/**
* An agent role assignment failed.
*
* ANVIL Spec Section 16.3 -- Role Contracts

public val sessionId: String,
) : ForgeCollabError("collaboration session '$sessionId' not found")

/**
* A session is in an invalid state for the requested operation.
*
* ANVIL Spec Section 16.2 -- Session Lifecycle
*
* @property sessionId The session identifier.
* @property currentState The current session state.
* @property requiredState The required session state.
*/
public class InvalidSessionState(
public val sessionId: String,
public val currentState: String,
public val requiredState: String,
) : ForgeCollabError(
"session '$sessionId' is in state '$currentState' but must be in " +
"'$requiredState' for this operation (see ANVIL Spec SS16.2)"
)

/**
* An agent role assignment failed.
*
* ANVIL Spec Section 16.3 -- Role Contracts
*

public class InvalidSessionState(
public val sessionId: String,
public val currentState: String,
public val requiredState: String,
) : ForgeCollabError(
"session '$sessionId' is in state '$currentState' but must be in " +
"'$requiredState' for this operation (see ANVIL Spec SS16.2)"
)

/**
* An agent role assignment failed.
*
* ANVIL Spec Section 16.3 -- Role Contracts
*
* @property agentDid The agent's DID.
* @property role The role that was requested.
* @property reason The failure reason.
*/
public class RoleAssignmentFailed(
public val agentDid: String,
public val role: String,
public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)

public val sessionId: String,
public val currentState: String,
public val requiredState: String,
) : ForgeCollabError(
"session '$sessionId' is in state '$currentState' but must be in " +
"'$requiredState' for this operation (see ANVIL Spec SS16.2)"
)

/**
* An agent role assignment failed.
*
* ANVIL Spec Section 16.3 -- Role Contracts
*
* @property agentDid The agent's DID.
* @property role The role that was requested.
* @property reason The failure reason.
*/
public class RoleAssignmentFailed(
public val agentDid: String,
public val role: String,
public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)


public val currentState: String,
public val requiredState: String,
) : ForgeCollabError(
"session '$sessionId' is in state '$currentState' but must be in " +
"'$requiredState' for this operation (see ANVIL Spec SS16.2)"
)

/**
* An agent role assignment failed.
*
* ANVIL Spec Section 16.3 -- Role Contracts
*
* @property agentDid The agent's DID.
* @property role The role that was requested.
* @property reason The failure reason.
*/
public class RoleAssignmentFailed(
public val agentDid: String,
public val role: String,
public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)

/**

public val requiredState: String,
) : ForgeCollabError(
"session '$sessionId' is in state '$currentState' but must be in " +
"'$requiredState' for this operation (see ANVIL Spec SS16.2)"
)

/**
* An agent role assignment failed.
*
* ANVIL Spec Section 16.3 -- Role Contracts
*
* @property agentDid The agent's DID.
* @property role The role that was requested.
* @property reason The failure reason.
*/
public class RoleAssignmentFailed(
public val agentDid: String,
public val role: String,
public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)

/**
* A delegation request was rejected.

public class RoleAssignmentFailed(
public val agentDid: String,
public val role: String,
public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)

/**
* A delegation request was rejected.
*
* ANVIL Spec Section 16.4 -- Delegation
*
* @property delegatorDid The delegating agent's DID.
* @property delegateeDid The target agent's DID.
* @property taskId The task being delegated.
* @property reason The rejection reason.
*/
public class DelegationRejected(
public val delegatorDid: String,
public val delegateeDid: String,
public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +

public val agentDid: String,
public val role: String,
public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)

/**
* A delegation request was rejected.
*
* ANVIL Spec Section 16.4 -- Delegation
*
* @property delegatorDid The delegating agent's DID.
* @property delegateeDid The target agent's DID.
* @property taskId The task being delegated.
* @property reason The rejection reason.
*/
public class DelegationRejected(
public val delegatorDid: String,
public val delegateeDid: String,
public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"

public val role: String,
public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)

/**
* A delegation request was rejected.
*
* ANVIL Spec Section 16.4 -- Delegation
*
* @property delegatorDid The delegating agent's DID.
* @property delegateeDid The target agent's DID.
* @property taskId The task being delegated.
* @property reason The rejection reason.
*/
public class DelegationRejected(
public val delegatorDid: String,
public val delegateeDid: String,
public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"
)

public val reason: String,
) : ForgeCollabError(
"role '$role' assignment to agent '$agentDid' failed: $reason " +
"(see ANVIL Spec SS16.3)"
)

/**
* A delegation request was rejected.
*
* ANVIL Spec Section 16.4 -- Delegation
*
* @property delegatorDid The delegating agent's DID.
* @property delegateeDid The target agent's DID.
* @property taskId The task being delegated.
* @property reason The rejection reason.
*/
public class DelegationRejected(
public val delegatorDid: String,
public val delegateeDid: String,
public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"
)


public class DelegationRejected(
public val delegatorDid: String,
public val delegateeDid: String,
public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"
)

/**
* A shared context operation failed.
*
* @property sessionId The session identifier.
* @property key The context key that caused the error.
* @property reason The failure reason.
*/
public class SharedContextError(
public val sessionId: String,
public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**

public val delegatorDid: String,
public val delegateeDid: String,
public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"
)

/**
* A shared context operation failed.
*
* @property sessionId The session identifier.
* @property key The context key that caused the error.
* @property reason The failure reason.
*/
public class SharedContextError(
public val sessionId: String,
public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.

public val delegateeDid: String,
public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"
)

/**
* A shared context operation failed.
*
* @property sessionId The session identifier.
* @property key The context key that caused the error.
* @property reason The failure reason.
*/
public class SharedContextError(
public val sessionId: String,
public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.
*

public val taskId: String,
public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"
)

/**
* A shared context operation failed.
*
* @property sessionId The session identifier.
* @property key The context key that caused the error.
* @property reason The failure reason.
*/
public class SharedContextError(
public val sessionId: String,
public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.
*
* ANVIL Spec Section 16.5 -- Interrupts

public val reason: String,
) : ForgeCollabError(
"delegation of task '$taskId' from '$delegatorDid' to '$delegateeDid' " +
"rejected: $reason (see ANVIL Spec SS16.4)"
)

/**
* A shared context operation failed.
*
* @property sessionId The session identifier.
* @property key The context key that caused the error.
* @property reason The failure reason.
*/
public class SharedContextError(
public val sessionId: String,
public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.
*
* ANVIL Spec Section 16.5 -- Interrupts
*

public class SharedContextError(
public val sessionId: String,
public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.
*
* ANVIL Spec Section 16.5 -- Interrupts
*
* @property targetDid The target agent's DID.
* @property interruptType The type of interrupt.
* @property reason The failure reason.
*/
public class InterruptFailed(
public val targetDid: String,
public val interruptType: String,
public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public val sessionId: String,
public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.
*
* ANVIL Spec Section 16.5 -- Interrupts
*
* @property targetDid The target agent's DID.
* @property interruptType The type of interrupt.
* @property reason The failure reason.
*/
public class InterruptFailed(
public val targetDid: String,
public val interruptType: String,
public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public val key: String,
public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.
*
* ANVIL Spec Section 16.5 -- Interrupts
*
* @property targetDid The target agent's DID.
* @property interruptType The type of interrupt.
* @property reason The failure reason.
*/
public class InterruptFailed(
public val targetDid: String,
public val interruptType: String,
public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public val reason: String,
) : ForgeCollabError(
"shared context error in session '$sessionId' for key '$key': $reason"
)

/**
* An interrupt could not be delivered.
*
* ANVIL Spec Section 16.5 -- Interrupts
*
* @property targetDid The target agent's DID.
* @property interruptType The type of interrupt.
* @property reason The failure reason.
*/
public class InterruptFailed(
public val targetDid: String,
public val interruptType: String,
public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public class InterruptFailed(
public val targetDid: String,
public val interruptType: String,
public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public val targetDid: String,
public val interruptType: String,
public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public val interruptType: String,
public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public val reason: String,
) : ForgeCollabError(
"interrupt '$interruptType' to agent '$targetDid' failed: $reason " +
"(see ANVIL Spec SS16.5)"
)
}

public enum class SessionState(public val value: String)

public fun isTerminal(): Boolean;

public enum class CollaborationRole

public data class SessionParticipant(
@SerialName("agent_did")
val agentDid: String,
val role: CollaborationRole,
val capabilities: Set<String>;

public enum class TaskStatus

public data class CollaborationTask(
val id: String,
val description: String,
@SerialName("assignee_did")
val assigneeDid: String?;

public enum class InterruptType

public data class Interrupt(
val id: String,
@SerialName("target_did")
val targetDid: String,
val type: InterruptType,
val reason: String,
val payload: String?;

public class DelegationManager(
private val sessionId: String,
)

public fun createTask(
id: String,
description: String,
delegatorDid: String,
priority: Int;

public fun assignTask(taskId: String, assigneeDid: String): CollaborationTask

public fun startTask(taskId: String): CollaborationTask

public fun completeTask(taskId: String, result: String): CollaborationTask

public fun failTask(taskId: String, reason: String): CollaborationTask

public fun getTask(taskId: String): CollaborationTask?;

public fun allTasks(): List<CollaborationTask>;

public fun tasksByStatus(status: TaskStatus): List<CollaborationTask> =

public fun interface InterruptReceiver

public suspend fun onInterrupt(interrupt: Interrupt)
}

/**
* Dispatches interrupt signals to registered agent handlers.
*
* Thread-safe. Agents register receivers identified by their DID,
* and the dispatcher routes interrupts to the appropriate receiver.
*
* ANVIL Spec Section 16.5
*/
public class InterruptDispatcher

public class InterruptDispatcher

public fun register(agentDid: String, receiver: InterruptReceiver)

public fun unregister(agentDid: String)

public suspend fun dispatch(interrupt: Interrupt)

public fun hasReceiver(agentDid: String): Boolean;

public interface CoordinatorContract

public suspend fun distributeTask(
task: CollaborationTask,
participants: List<SessionParticipant>,
): String?

/**
* Handle a completed task from a worker.
*
* @param task The completed task with result.
*/
public suspend fun onTaskCompleted(task: CollaborationTask)

/**
* Handle a failed task from a worker.
*
* @param task The failed task.
* @param reason The failure reason.
*/
public suspend fun onTaskFailed(task: CollaborationTask, reason: String)

/**
* Determine whether the session should complete.
*
* @param tasks All tasks in the session.
* @return `true` if the session should transition to completing.
*/

public suspend fun onTaskCompleted(task: CollaborationTask)

/**
* Handle a failed task from a worker.
*
* @param task The failed task.
* @param reason The failure reason.
*/
public suspend fun onTaskFailed(task: CollaborationTask, reason: String)

/**
* Determine whether the session should complete.
*
* @param tasks All tasks in the session.
* @return `true` if the session should transition to completing.
*/
public suspend fun shouldComplete(tasks: List<CollaborationTask>): Boolean
}

/**
* Contract for an agent acting as a worker.
*
* Workers execute delegated tasks and report results back to
* the coordinator.
*
* ANVIL Spec Section 16.3

public suspend fun onTaskFailed(task: CollaborationTask, reason: String)

/**
* Determine whether the session should complete.
*
* @param tasks All tasks in the session.
* @return `true` if the session should transition to completing.
*/
public suspend fun shouldComplete(tasks: List<CollaborationTask>): Boolean
}

/**
* Contract for an agent acting as a worker.
*
* Workers execute delegated tasks and report results back to
* the coordinator.
*
* ANVIL Spec Section 16.3
*/
public interface WorkerContract

public suspend fun shouldComplete(tasks: List<CollaborationTask>): Boolean
}

/**
* Contract for an agent acting as a worker.
*
* Workers execute delegated tasks and report results back to
* the coordinator.
*
* ANVIL Spec Section 16.3
*/
public interface WorkerContract

public interface WorkerContract

public suspend fun executeTask(task: CollaborationTask): String

/**
* Whether the worker can accept a new task.
*
* Workers may reject tasks if they are at capacity or lack
* the required capabilities.
*
* @param task The proposed task.
* @return `true` if the worker can accept the task.
*/
public suspend fun canAccept(task: CollaborationTask): Boolean

/**
* Handle an interrupt from the coordinator.
*
* @param interrupt The interrupt signal.
*/
public suspend fun onInterrupt(interrupt: Interrupt)
}

/**
* Contract for an agent acting as a reviewer.
*
* Reviewers validate the outputs of workers before the coordinator
* accepts them.

public suspend fun canAccept(task: CollaborationTask): Boolean

/**
* Handle an interrupt from the coordinator.
*
* @param interrupt The interrupt signal.
*/
public suspend fun onInterrupt(interrupt: Interrupt)
}

/**
* Contract for an agent acting as a reviewer.
*
* Reviewers validate the outputs of workers before the coordinator
* accepts them.
*
* ANVIL Spec Section 16.3
*/
public interface ReviewerContract

public suspend fun onInterrupt(interrupt: Interrupt)
}

/**
* Contract for an agent acting as a reviewer.
*
* Reviewers validate the outputs of workers before the coordinator
* accepts them.
*
* ANVIL Spec Section 16.3
*/
public interface ReviewerContract

public interface ReviewerContract

public suspend fun review(task: CollaborationTask): ReviewResult
}

/**
* The result of a task review.
*
* ANVIL Spec Section 16.3
*/
public sealed class ReviewResult

public sealed class ReviewResult

public data class Approved(val feedback: String;

public data class Rejected(
val reason: String,
val suggestions: List<String>;

public data class CollaborationSession(
val id: String,
val name: String,
val state: SessionState;

public class SessionManager

public fun createSession(
id: String,
name: String,
coordinatorDid: String,
): CollaborationSession

public fun getSession(sessionId: String): CollaborationSession?;

public fun requireSession(sessionId: String): CollaborationSession =

public fun addParticipant(
sessionId: String,
participant: SessionParticipant,
): CollaborationSession

public fun transitionSession(
sessionId: String,
newState: SessionState,
): CollaborationSession

public fun addTask(
sessionId: String,
task: CollaborationTask,
): CollaborationSession

public fun activeSessions(): List<CollaborationSession> =

public fun removeSession(sessionId: String): Boolean =

public data class ContextEntry(
val key: String,
val value: String,
val version: Long;

public class SharedContext(
private val sessionId: String,
)

public fun get(key: String): ContextEntry?;

public fun require(key: String): ContextEntry =

public fun set(key: String, value: String, authorDid: String): ContextEntry

public fun compareAndSet(
key: String,
value: String,
expectedVersion: Long,
authorDid: String,
): ContextEntry

public fun remove(key: String): ContextEntry?;

public fun entries(): List<ContextEntry>;

public fun size(): Int;

public fun clear()