cli-swarm 7.0.36 → 7.0.38

package/swarm-task-routing-model.mjs

@@ -0,0 +1,163 @@
+import { createHash } from 'node:crypto'
+import { coordinatorError, identifier, relativePath } from './swarm-coordinator-fs.mjs'
+import { findTask, requireString } from './swarm-coordinator-model.mjs'
+
+export const ROUTING_SCHEMA = 'swarm.task-routing/1.0'
+export const REQUEST_SCHEMA = 'swarm.task-request/1.0'
+export const TASKS_SCHEMA = 'swarm.task-message-result/1.0'
+export const MAX_MESSAGE_LENGTH = 100_000
+export const MAX_MESSAGE_ITEMS = 50
+export const TERMINAL_REQUESTS = new Set(['completed', 'rejected'])
+const MATCH_SIGNAL_MINIMUM = 2
+const IDENTITY_FIELDS = ['taskId', 'agentId', 'chainId']
+
+export function routingError(code, message) { coordinatorError('SWARM_ROUTING_' + code, message) }
+export function digest(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex') }
+export function exactObject(value, keys, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || keys.some(key => !Object.hasOwn(value, key)) || Object.keys(value).some(key => !keys.includes(key))) {
+    routingError('INPUT_INVALID', label + ' has missing or unsupported fields')
+  }
+  return value
+}
+export function strings(value, label) {
+  if (!Array.isArray(value) || value.length > MAX_MESSAGE_ITEMS) routingError('INPUT_INVALID', label + ' must be a bounded array')
+  const values = value.map(item => requireString(item, label))
+  if (new Set(values).size !== values.length) routingError('INPUT_INVALID', label + ' contains duplicates')
+  return values
+}
+export function identity(task) { return Object.fromEntries(IDENTITY_FIELDS.map(key => [key, task[key]])) }
+export function describedTask(state, input) {
+  const task = findTask(state, input)
+  if (!task.routing || task.routing.schemaVersion !== ROUTING_SCHEMA) {
+    routingError('TASK_UNDESCRIBED', 'register the task goal and host identity before routing messages')
+  }
+  return task
+}
+export function requests(state) { return state.messages.filter(message => message.schemaVersion === REQUEST_SCHEMA) }
+export function visibleTo(source, task) {
+  return task.routing && task.routing.schemaVersion === ROUTING_SCHEMA
+    && task.routing.ownerId === source.routing.ownerId && task.routing.projectId === source.routing.projectId
+}
+export function requestedTask(state, source, taskId) {
+  const task = state.tasks.find(entry => entry.taskId === identifier(taskId, 'targetTaskId'))
+  if (!task || !visibleTo(source, task)) routingError('TARGET_UNAVAILABLE', 'target task is outside this registered collaboration scope')
+  return task
+}
+export function accessRequest(state, task, requestId) {
+  const request = requests(state).find(entry => entry.requestId === identifier(requestId, 'requestId'))
+  if (!request || request.ownerId !== task.routing.ownerId || request.projectId !== task.routing.projectId
+    || ![request.sourceTaskId, request.targetTaskId, request.handoffTaskId].includes(task.taskId)) {
+    routingError('REQUEST_UNAVAILABLE', 'request is not available to this task')
+  }
+  return request
+}
+export function sourceRequest(state, input) {
+  const task = describedTask(state, input), request = accessRequest(state, task, input.requestId)
+  if (request.sourceTaskId !== task.taskId) routingError('SOURCE_REQUIRED', 'only the source task can coordinate this delivery')
+  return { task, request }
+}
+export function targetRequest(state, input) {
+  const task = describedTask(state, input), request = accessRequest(state, task, input.requestId)
+  if (request.targetTaskId !== task.taskId) routingError('TARGET_REQUIRED', 'only the assigned task can accept or complete this request')
+  return { task, request }
+}
+export function event(request, type, details) {
+  request.history.push({ type, details, recordedAt: new Date().toISOString() })
+}
+export function receipt(request) {
+  return request.receiptId === null ? null : {
+    requestId: request.requestId, receiptId: request.receiptId, targetTaskId: request.targetTaskId,
+  }
+}
+export function requestView(request) {
+  return { requestId: request.requestId, messageId: request.messageId, itemId: request.itemId,
+    text: request.text, sourceTaskId: request.sourceTaskId, targetTaskId: request.targetTaskId,
+    handoffTaskId: request.handoffTaskId, status: request.status, reason: request.reason,
+    candidates: request.candidates, receipt: receipt(request), deliveryAttempt: request.deliveryAttempt,
+    resultSummary: request.resultSummary }
+}
+export function deliveryView(state, request) {
+  const target = state.tasks.find(task => task.taskId === request.targetTaskId)
+  if (!target || !target.routing) routingError('TARGET_UNAVAILABLE', 'delivery target registration is missing')
+  return { requestId: request.requestId, messageId: request.messageId, itemId: request.itemId,
+    text: request.text, targetTaskId: target.taskId, targetAgentId: target.agentId, targetChainId: target.chainId,
+    targetHostId: target.routing.hostId, targetThreadId: target.routing.threadId, status: request.status }
+}
+export function initialRouting(input) {
+  const keys = ['ownerId', 'projectId', 'hostId', 'threadId', 'goal', 'keywords', 'requirements']
+  const description = Object.fromEntries(keys.map(key => [key, input[key]]))
+  for (const key of ['ownerId', 'projectId', 'hostId', 'threadId']) identifier(description[key], key)
+  description.goal = requireString(description.goal, 'goal')
+  description.keywords = strings(description.keywords, 'keywords')
+  if (!Array.isArray(description.requirements) || !description.requirements.length
+    || description.requirements.length > MAX_MESSAGE_ITEMS) routingError('INPUT_INVALID', 'original requirements are required')
+  description.requirements = description.requirements.map(requirement => {
+    exactObject(requirement, ['id', 'text'], 'requirement')
+    return { id: identifier(requirement.id, 'requirementId'), text: requireString(requirement.text, 'requirement text') }
+  })
+  if (new Set(description.requirements.map(item => item.id)).size !== description.requirements.length) {
+    routingError('INPUT_INVALID', 'original requirement IDs must be unique')
+  }
+  return { schemaVersion: ROUTING_SCHEMA, ...description, descriptionDigest: digest(description), revision: 1,
+    completedRequirementIds: [], nextAction: description.goal, checkpointAt: new Date().toISOString(), handoff: null }
+}
+export function normalizeMessage(input) {
+  identifier(input.messageId, 'messageId')
+  if (input.origin !== 'user') routingError('USER_EVENT_REQUIRED', 'documents and tool outputs cannot issue task-routing instructions')
+  const text = requireString(input.text, 'message text')
+  if (text.length > MAX_MESSAGE_LENGTH || !Array.isArray(input.items) || !input.items.length
+    || input.items.length > MAX_MESSAGE_ITEMS) routingError('INPUT_INVALID', 'message or item count exceeds the protocol limit')
+  let coveredUntil = 0
+  const items = input.items.map(item => {
+    exactObject(item, ['itemId', 'text', 'explicitTaskId', 'forceCurrent', 'targetPaths'], 'message item')
+    identifier(item.itemId, 'itemId')
+    const content = requireString(item.text, 'item text')
+    const start = text.indexOf(content, coveredUntil)
+    if (start < 0) routingError('CONTENT_MISMATCH', 'items must quote the original message in order without overlap')
+    if (/\S/u.test(text.slice(coveredUntil, start))) routingError('CONTENT_INCOMPLETE', 'extracted items must cover every non-whitespace part of the original message')
+    coveredUntil = start + content.length
+    if (typeof item.forceCurrent !== 'boolean') routingError('INPUT_INVALID', 'forceCurrent must be an explicit boolean')
+    if (item.explicitTaskId !== null) identifier(item.explicitTaskId, 'explicitTaskId')
+    return { ...item, text: content, targetPaths: strings(item.targetPaths, 'targetPaths').map(path => relativePath(path)) }
+  })
+  if (/\S/u.test(text.slice(coveredUntil))) routingError('CONTENT_INCOMPLETE', 'extracted items omit part of the original user message')
+  if (new Set(items.map(item => item.itemId)).size !== items.length) routingError('INPUT_INVALID', 'item IDs must be unique')
+  return { messageId: input.messageId, origin: input.origin, text, items }
+}
+function overlap(left, right) { return left === right || left.startsWith(right + '/') || right.startsWith(left + '/') }
+function containsKeyword(text, keyword) {
+  const normalized = text.toLocaleLowerCase(), term = keyword.toLocaleLowerCase()
+  if (/[\u3400-\u9fff]/u.test(term)) return normalized.includes(term)
+  const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp('(?:^|[^\\p{L}\\p{N}_])' + escaped + '(?:$|[^\\p{L}\\p{N}_])', 'u').test(normalized)
+}
+export function selectOwner(state, source, item) {
+  if (item.explicitTaskId !== null) {
+    const explicit = requestedTask(state, source, item.explicitTaskId)
+    return { target: explicit, reason: 'explicit-task', candidates: [explicit.taskId] }
+  }
+  const candidates = state.tasks.filter(task => visibleTo(source, task)
+    && !['completed', 'failed', 'reclaimed'].includes(task.status)).map(task => {
+    const keywords = task.routing.keywords.filter(keyword => containsKeyword(item.text, keyword))
+    const paths = item.targetPaths.filter(path => task.taskScope.some(scope => overlap(path, scope)))
+    return { task, keywords, paths, signals: keywords.length + (paths.length ? 1 : 0) }
+  }).filter(candidate => candidate.keywords.length > 0 && candidate.signals >= MATCH_SIGNAL_MINIMUM)
+  if (candidates.length !== 1) return { target: null, reason: candidates.length ? 'ambiguous-ownership' : 'ownership-unresolved',
+    candidates: candidates.map(candidate => candidate.task.taskId) }
+  return { target: candidates[0].task, reason: 'unique-goal-and-scope-evidence', candidates: [candidates[0].task.taskId] }
+}
+export function completionPending(state, task) {
+  const original = task.routing.requirements.filter(item => !task.routing.completedRequirementIds.includes(item.id))
+  const pending = requests(state).filter(request => !TERMINAL_REQUESTS.has(request.status)
+    && (request.targetTaskId === task.taskId || (request.sourceTaskId === task.taskId && request.receiptId === null)))
+  return { original, pending }
+}
+export function assertTaskRequestsCompleted(state, task) {
+  if (!task.routing) return
+  if (task.routing.schemaVersion !== ROUTING_SCHEMA) routingError('STATE_INVALID', 'unknown task routing schema')
+  const remaining = completionPending(state, task)
+  if (remaining.original.length || remaining.pending.length || task.routing.handoff !== null) {
+    routingError('TASK_INCOMPLETE', 'original requirements or routed requests remain unfinished')
+  }
+}

package/swarm-task-routing-schemas.mjs

@@ -0,0 +1,24 @@
+const string = { type: 'string', minLength: 1 }
+const strings = { type: 'array', items: string }
+const object = (required, properties) => ({ type: 'object', additionalProperties: false, required, properties })
+const identity = { taskId: string, agentId: string, chainId: string }
+const fields = (properties) => object(Object.keys(properties), properties)
+const request = { ...identity, requestId: string }
+export const TASK_ROUTING_SCHEMAS = Object.freeze({
+  'task-describe': fields({ ...identity, ownerId: string, projectId: string, hostId: string, threadId: string,
+    goal: string, keywords: strings, requirements: { type: 'array', items: fields({ id: string, text: string }) } }),
+  'task-checkpoint': fields({ ...identity, expectedRevision: { type: 'integer', minimum: 1 },
+    completedRequirementIds: strings, nextAction: string }),
+  'task-resume': fields(identity),
+  'message-route': fields({ ...identity, messageId: string, origin: { const: 'user' }, text: string,
+    items: { type: 'array', items: fields({ itemId: string, text: string, explicitTaskId: { type: ['string', 'null'] },
+      forceCurrent: { type: 'boolean' }, targetPaths: strings }) } }),
+  'message-status': fields(request),
+  'message-delivery-start': fields(request),
+  'message-delivery-report': fields({ ...request, errorCode: string, errorMessage: string }),
+  'message-accept': fields(request),
+  'message-complete': fields({ ...request, resultSummary: string }),
+  'message-resolve': fields({ ...request, targetTaskId: string, userMessageId: string, userText: string }),
+  'handoff-resume': fields(request),
+  'handoff-release': fields({ ...request, checkpointSummary: string }),
+})

package/swarm-task-routing.mjs

@@ -0,0 +1,175 @@
+import { randomUUID } from 'node:crypto'
+import { withCoordinationState, withCoordinationReadLock } from './swarm-coordinator-fs.mjs'
+import { findTask, requireString } from './swarm-coordinator-model.mjs'
+import { pendingDecision, hasActiveWait } from './swarm-coordinator-waits.mjs'
+import { TASK_HANDOFF_HANDLERS } from './swarm-task-handoff.mjs'
+import { TASKS_SCHEMA, REQUEST_SCHEMA, TERMINAL_REQUESTS, routingError, digest, strings, identity,
+  describedTask, requests, requestedTask, accessRequest, sourceRequest, targetRequest, event,
+  receipt, requestView, deliveryView, initialRouting, normalizeMessage, selectOwner, completionPending } from './swarm-task-routing-model.mjs'
+
+function changed(state, output, type, taskId, requestId = null) {
+  return { state, output: { schemaVersion: TASKS_SCHEMA, ...output }, audit: [{ event: type, taskId, requestId }] }
+}
+export function resumeView(state, task) {
+  const routing = task.routing
+  const relevant = requests(state)
+  const remaining = completionPending(state, task)
+  return { ...identity(task), schemaVersion: TASKS_SCHEMA, goal: routing.goal,
+    goalDigest: routing.descriptionDigest, goalRevision: routing.revision,
+    remainingRequirements: remaining.original, nextAction: routing.nextAction,
+    checkpointAt: routing.checkpointAt, status: task.status,
+    canContinue: task.status === 'active' && routing.handoff === null
+      && !pendingDecision(state, task) && !hasActiveWait(state, task),
+    completionAllowed: !remaining.original.length && !remaining.pending.length && routing.handoff === null,
+    inbox: relevant.filter(item => item.targetTaskId === task.taskId && !TERMINAL_REQUESTS.has(item.status)).map(requestView),
+    outbox: relevant.filter(item => item.sourceTaskId === task.taskId && !TERMINAL_REQUESTS.has(item.status)).map(requestView),
+    handoffs: relevant.filter(item => item.handoffTaskId === task.taskId && !TERMINAL_REQUESTS.has(item.status)).map(requestView) }
+}
+async function describeTask(root, input) {
+  return withCoordinationState(root, state => {
+    const task = findTask(state, input), routing = initialRouting(input)
+    if (task.routing) {
+      describedTask(state, input)
+      if (task.routing.descriptionDigest !== routing.descriptionDigest) {
+        routingError('GOAL_IMMUTABLE', 'a new message cannot replace this task goal, host identity or original requirements')
+      }
+    } else {
+      if (['completed', 'failed', 'reclaimed'].includes(task.status)) routingError('TASK_TERMINAL', 'a terminal task cannot register new work')
+      task.routing = routing
+    }
+    return changed(state, { task: resumeView(state, task) }, 'task-described', task.taskId)
+  })
+}
+async function checkpointTask(root, input) {
+  return withCoordinationState(root, state => {
+    const task = describedTask(state, input), routing = task.routing
+    if (!Number.isSafeInteger(input.expectedRevision) || routing.revision !== input.expectedRevision) {
+      routingError('REVISION_CONFLICT', 'reload the current checkpoint before updating it')
+    }
+    if (task.status !== 'active' || routing.handoff !== null || pendingDecision(state, task) || hasActiveWait(state, task)) {
+      routingError('TASK_SUSPENDED', 'a suspended task cannot advance its checkpoint')
+    }
+    const completed = strings(input.completedRequirementIds, 'completedRequirementIds')
+    if (completed.some(id => !routing.requirements.some(item => item.id === id))
+      || routing.completedRequirementIds.some(id => !completed.includes(id))) {
+      routingError('CHECKPOINT_INVALID', 'completed requirements must belong to the original goal and cannot be silently discarded')
+    }
+    routing.completedRequirementIds = completed
+    routing.nextAction = requireString(input.nextAction, 'nextAction')
+    routing.checkpointAt = new Date().toISOString()
+    routing.revision += 1
+    return changed(state, { task: resumeView(state, task) }, 'task-checkpoint', task.taskId)
+  })
+}
+async function resumeTask(root, input) {
+  return withCoordinationReadLock(root, state => resumeView(state, describedTask(state, input)))
+}
+function newRequest(state, source, message, item) {
+  const selected = selectOwner(state, source, item)
+  const target = item.forceCurrent ? source : selected.target
+  const handoff = item.forceCurrent && selected.target && selected.target.taskId !== source.taskId ? selected.target : null
+  const unavailable = target && ['completed', 'failed', 'reclaimed'].includes(target.status)
+  const requestId = 'request-' + digest([source.taskId, message.messageId, item.itemId])
+  const request = { schemaVersion: REQUEST_SCHEMA, requestId, messageId: message.messageId, itemId: item.itemId,
+    messageDigest: digest(message), sourceTaskId: source.taskId, sourceAgentId: source.agentId, sourceChainId: source.chainId,
+    ownerId: source.routing.ownerId, projectId: source.routing.projectId, text: item.text, targetPaths: item.targetPaths,
+    targetTaskId: target ? target.taskId : null, handoffTaskId: handoff ? handoff.taskId : null,
+    forceCurrent: item.forceCurrent, status: unavailable || !target ? 'pending-routing' : handoff ? 'pending-handoff' : 'pending-delivery',
+    reason: unavailable ? 'target-task-terminal' : item.forceCurrent ? 'explicit-current-task' : selected.reason,
+    candidates: selected.candidates, receiptId: null, deliveryAttempt: null, resultSummary: null,
+    createdAt: new Date().toISOString(), acceptedAt: null, completedAt: null, history: [] }
+  event(request, 'message-recorded', { source: identity(source), selectedTaskId: request.targetTaskId, reason: request.reason })
+  return request
+}
+async function routeMessage(root, input) {
+  return withCoordinationState(root, state => {
+    const source = describedTask(state, input), message = normalizeMessage(input)
+    if (['completed', 'failed', 'reclaimed'].includes(source.status)) routingError('TASK_TERMINAL', 'resume or register a follow-up before submitting new work')
+    const existing = requests(state).filter(item => item.sourceTaskId === source.taskId && item.messageId === message.messageId)
+    if (existing.length && (existing.length !== message.items.length || existing.some(item => item.messageDigest !== digest(message)))) {
+      routingError('MESSAGE_CONFLICT', 'this message ID already has different content or routing instructions; use explicit resolution')
+    }
+    const recorded = existing.length ? existing : message.items.map(item => newRequest(state, source, message, item))
+    if (!existing.length) state.messages.push(...recorded)
+    const deliveries = recorded.filter(item => item.status === 'pending-delivery').map(item => deliveryView(state, item))
+    return changed(state, { messageId: message.messageId, source: identity(source), replayed: existing.length > 0,
+      requests: recorded.map(requestView), deliveries, continuation: resumeView(state, source) }, 'message-routed', source.taskId)
+  })
+}
+async function messageStatus(root, input) {
+  return withCoordinationReadLock(root, state => {
+    const task = describedTask(state, input), request = accessRequest(state, task, input.requestId)
+    return { schemaVersion: TASKS_SCHEMA, request: requestView(request), receipt: receipt(request) }
+  })
+}
+async function startDelivery(root, input) {
+  return withCoordinationState(root, state => {
+    const { task, request } = sourceRequest(state, input)
+    let claimed = false
+    if (request.status === 'pending-delivery' && request.deliveryAttempt === null) {
+      request.deliveryAttempt = { attemptId: 'delivery-' + randomUUID(), startedAt: new Date().toISOString(),
+        status: 'started', errorCode: null, errorMessage: null }
+      event(request, 'delivery-started', { attemptId: request.deliveryAttempt.attemptId })
+      claimed = true
+    }
+    return changed(state, { claimed, attemptId: request.deliveryAttempt === null ? null : request.deliveryAttempt.attemptId,
+      request: requestView(request) }, 'delivery-claim', task.taskId, request.requestId)
+  })
+}
+async function reportDelivery(root, input) {
+  return withCoordinationState(root, state => {
+    const { task, request } = sourceRequest(state, input)
+    const errorCode = requireString(input.errorCode, 'errorCode'), errorMessage = requireString(input.errorMessage, 'errorMessage')
+    if (request.deliveryAttempt === null) routingError('DELIVERY_NOT_STARTED', 'cannot report an unclaimed delivery')
+    request.deliveryAttempt.status = request.receiptId === null ? 'uncertain' : 'received'
+    request.deliveryAttempt.errorCode = errorCode
+    request.deliveryAttempt.errorMessage = errorMessage
+    event(request, 'delivery-reported', { attemptId: request.deliveryAttempt.attemptId, errorCode, errorMessage })
+    return changed(state, { request: requestView(request), receipt: receipt(request) }, 'delivery-reported', task.taskId, request.requestId)
+  })
+}
+function checkTargetScope(task, request) {
+  if (!request.targetPaths.every(path => task.taskScope.some(scope => path === scope || path.startsWith(scope + '/')))) {
+    routingError('SCOPE_REQUIRED', 'the target must approve an updated task scope before accepting these paths')
+  }
+}
+async function acceptMessage(root, input) {
+  return withCoordinationState(root, state => {
+    const { task, request } = targetRequest(state, input)
+    if (request.receiptId !== null) return changed(state, { ...receipt(request), status: request.status }, 'message-accept-replayed', task.taskId, request.requestId)
+    if (request.status !== 'pending-delivery') routingError('DELIVERY_NOT_READY', 'resolve ownership and complete any handoff before accepting')
+    if (!resumeView(state, task).canContinue) routingError('TASK_SUSPENDED', 'target task is not ready to accept work')
+    checkTargetScope(task, request)
+    request.receiptId = 'receipt-' + randomUUID()
+    request.acceptedAt = new Date().toISOString()
+    request.status = 'accepted'
+    if (request.deliveryAttempt !== null) request.deliveryAttempt.status = 'received'
+    event(request, 'message-accepted', { ...identity(task), receiptId: request.receiptId })
+    return changed(state, { ...receipt(request), status: 'accepted' }, 'message-accepted', task.taskId, request.requestId)
+  })
+}
+async function resolveMessage(root, input) {
+  return withCoordinationState(root, state => {
+    const { task, request } = sourceRequest(state, input)
+    const target = requestedTask(state, task, input.targetTaskId)
+    const userMessageId = requireString(input.userMessageId, 'userMessageId'), userText = requireString(input.userText, 'userText')
+    const previous = request.history.find(entry => entry.type === 'user-resolution' && entry.details.userMessageId === userMessageId)
+    if (previous) {
+      if (previous.details.targetTaskId !== target.taskId || previous.details.userText !== userText) routingError('MESSAGE_CONFLICT', 'resolution ID was already used with different content')
+      return changed(state, { request: requestView(request) }, 'message-resolution-replayed', task.taskId, request.requestId)
+    }
+    if (request.status !== 'pending-routing' || request.receiptId !== null || request.deliveryAttempt !== null) routingError('ALREADY_ROUTED', 'an active delivery cannot be silently redirected')
+    if (['completed', 'failed', 'reclaimed'].includes(target.status)) routingError('TASK_TERMINAL', 'select an active follow-up task')
+    request.targetTaskId = target.taskId
+    request.status = 'pending-delivery'
+    request.reason = 'explicit-user-resolution'
+    event(request, 'user-resolution', { userMessageId, userText, targetTaskId: target.taskId })
+    return changed(state, { request: requestView(request), delivery: deliveryView(state, request) }, 'message-resolved', task.taskId, request.requestId)
+  })
+}
+export const TASK_ROUTING_HANDLERS = Object.freeze({
+  'task-describe': describeTask, 'task-checkpoint': checkpointTask, 'task-resume': resumeTask,
+  'message-route': routeMessage, 'message-status': messageStatus, 'message-delivery-start': startDelivery,
+  'message-delivery-report': reportDelivery, 'message-accept': acceptMessage, 'message-resolve': resolveMessage,
+  ...TASK_HANDOFF_HANDLERS,
+})