cli-aimlock 7.0.33 → 7.0.34

package/aimlock-chain-calls.mjs

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto'
+import { resolve } from 'node:path'
+import { executeCoordinatorOperation } from 'cli-swarm/coordinator'
+import { loadOfficialSkillContext } from './installer.mjs'
+import { invokeOfficialSkill } from './broker.mjs'
+import { fail, sha256 } from './aimlock-local-fs.mjs'
+import { errorRecord } from './aimlock-chain-model.mjs'
+import { saveExecution } from './aimlock-chain-store.mjs'
+import { executeCommand } from './aimlock-chain-process.mjs'
+
+export function resolveContexts(root, plan) {
+  return plan.skills.map((skill) => {
+    const context = loadOfficialSkillContext(resolve(root, skill.packageRoot))
+    if (context.skillName !== skill.skillId) fail('AIMLOCK_CHAIN_SKILL_INVALID', 'installed skill does not match plan skillId')
+    return { skillId: skill.skillId, context }
+  })
+}
+
+export function verifyContexts(root, state) {
+  if (JSON.stringify(resolveContexts(root, state.plan)) !== JSON.stringify(state.contexts)) {
+    fail('AIMLOCK_CHAIN_SKILL_CHANGED', 'installed package metadata changed after execution initialization')
+  }
+}
+
+function skillContext(state, skillId) {
+  const found = state.contexts.find((entry) => entry.skillId === skillId)
+  if (!found) fail('AIMLOCK_CHAIN_SKILL_MISSING', 'execution needs an explicitly declared ' + skillId + ' package')
+  return found.context
+}
+
+async function startCall(session, kind, operation, input) {
+  const call = { callId: 'call-' + randomUUID(), kind, operation, inputDigest: sha256(JSON.stringify(input)),
+    requestId: null, status: 'started', pid: null, receipt: null, error: null,
+    startedAt: new Date().toISOString(), completedAt: null }
+  session.record.calls.push(call)
+  await saveExecution(session.file, session.state)
+  return call
+}
+
+async function failCall(session, call, error) {
+  call.status = call.requestId || call.pid !== null ? 'uncertain' : 'failed'
+  call.error = errorRecord(error)
+  call.completedAt = new Date().toISOString()
+  await saveExecution(session.file, session.state)
+}
+
+export async function callSkill(session, skillId, operation, input) {
+  const context = skillContext(session.state, skillId)
+  const call = await startCall(session, 'skill', operation, input)
+  try {
+    const dependencies = session.dependencies
+    const invocation = await invokeOfficialSkill(context, operation, input, {
+      environment: dependencies.environment, credentialAccess: dependencies.credentialAccess,
+      request: async (url, options) => {
+        const request = JSON.parse(options.body).input
+        call.requestId = request.requestId
+        call.status = 'dispatched'
+        await saveExecution(session.file, session.state)
+        return dependencies.request(url, options)
+      },
+    })
+    call.receipt = invocation
+    call.status = 'recorded'
+    call.completedAt = new Date().toISOString()
+    await saveExecution(session.file, session.state)
+    return invocation.response.output
+  } catch (error) {
+    await failCall(session, call, error)
+    throw error
+  }
+}
+
+export async function callCoordinator(session, operation, input) {
+  const call = await startCall(session, 'coordinator', operation, input)
+  try {
+    const output = await executeCoordinatorOperation(operation, session.root, input)
+    call.status = 'recorded'
+    call.receipt = output
+    call.completedAt = new Date().toISOString()
+    await saveExecution(session.file, session.state)
+    return output
+  } catch (error) {
+    await failCall(session, call, error)
+    throw error
+  }
+}
+
+export async function callCommand(session, input) {
+  const call = await startCall(session, 'command', 'exec', input)
+  try {
+    const output = await executeCommand(session.root, input, call.callId, async (pid) => {
+      call.pid = pid
+      call.status = 'dispatched'
+      await saveExecution(session.file, session.state)
+    })
+    call.status = output.status === 'uncertain' ? 'uncertain' : 'recorded'
+    call.receipt = output
+    call.completedAt = new Date().toISOString()
+    await saveExecution(session.file, session.state)
+    return output
+  } catch (error) {
+    await failCall(session, call, error)
+    throw error
+  }
+}

package/aimlock-chain-cli.mjs

@@ -0,0 +1,49 @@
+import { stdin, stdout } from 'node:process'
+import { answerExecution, executionStatus, initializeExecution, resumeExecution } from './aimlock-chain-executor.mjs'
+import { errorRecord } from './aimlock-chain-model.mjs'
+import { fail } from './aimlock-local-fs.mjs'
+
+const PLAN_MAX_BYTES = 1_048_576
+export const CHAIN_USAGE = [
+  '  cli-aimlock chain init <repositoryRoot> < execution-plan.json',
+  '  cli-aimlock chain resume <repositoryRoot> <chainId>',
+  '  cli-aimlock chain status <repositoryRoot> <chainId>',
+  '  cli-aimlock chain answer <repositoryRoot> <chainId> <actorId>',
+  '      Persist explicit steps; resume invokes real broker/coordinator/process operations.',
+  '      answer requires a live terminal. Recorded results and nextStep never imply execution.',
+].join('\n')
+
+async function readPlan(input) {
+  let source = ''
+  for await (const chunk of input) {
+    source += chunk
+    if (Buffer.byteLength(source) > PLAN_MAX_BYTES) fail('AIMLOCK_CHAIN_INPUT_TOO_LARGE', 'execution plan exceeds 1 MiB')
+  }
+  if (!source.trim()) fail('AIMLOCK_CHAIN_INPUT_REQUIRED', 'execution plan is required on stdin')
+  return JSON.parse(source)
+}
+
+export async function dispatchChain(args) {
+  const [operation, repositoryRoot, chainId, actorId] = args
+  const expected = { init: 2, status: 3, resume: 3, answer: 4 }
+  if (!Object.hasOwn(expected, operation) || args.length !== expected[operation]) {
+    fail('AIMLOCK_CHAIN_USAGE_INVALID', CHAIN_USAGE)
+  }
+  const dependencies = { environment: process.env, request: fetch }
+  if (operation === 'init') return initializeExecution(repositoryRoot, await readPlan(stdin))
+  if (operation === 'status') return executionStatus(repositoryRoot, chainId)
+  if (operation === 'resume') return resumeExecution(repositoryRoot, chainId, dependencies)
+  return answerExecution(repositoryRoot, chainId, { input: stdin, output: stdout, actorId }, dependencies)
+}
+
+export async function runChainCli(args) {
+  try {
+    const state = await dispatchChain(args)
+    stdout.write(JSON.stringify(state) + '\n')
+    if (state.status === 'blocked') process.exitCode = 2
+    else if (state.status === 'failed' || state.status === 'uncertain') process.exitCode = 1
+  } catch (error) {
+    stdout.write(JSON.stringify({ status: 'failed', error: errorRecord(error) }) + '\n')
+    process.exitCode = 1
+  }
+}

package/aimlock-chain-executor.mjs

@@ -0,0 +1,233 @@
+import { randomUUID } from 'node:crypto'
+import { assertChainNotSuspended } from './aimlock-coordination.mjs'
+import { fail } from './aimlock-local-fs.mjs'
+import { bindInput, errorRecord, validatePlan } from './aimlock-chain-model.mjs'
+import { assertNewExecution, executionStatus, initialState, loadExecution, recoverInterrupted,
+  saveExecution, withExecutionLock } from './aimlock-chain-store.mjs'
+import { callCommand, callCoordinator, callSkill, resolveContexts, verifyContexts } from './aimlock-chain-calls.mjs'
+import { answerPending, prepareHuman } from './aimlock-chain-human.mjs'
+import { skillOutcome } from './aimlock-chain-outcomes.mjs'
+
+const COORDINATION_CODES = new Set(['AIMLOCK_COORDINATION_WAITING', 'AIMLOCK_COORDINATION_BLOCKED'])
+const BLOCKED_LOCAL_STATUSES = new Set(['blocked', 'queued', 'denied'])
+const FAILED_LOCAL_STATUSES = new Set(['failed', 'reclaimed'])
+const QUEUE_BLOCK_CODES = new Set(['SWARM_COORD_QUEUE_GRANT_INVALID', 'SWARM_COORD_QUEUE_GRANT_EXPIRED',
+  'SWARM_COORD_QUEUE_NOT_FOUND', 'SWARM_COORD_QUEUE_STATE_INVALID', 'SWARM_COORD_TASK_BLOCKED',
+  'SWARM_COORD_BASELINE_HANDSHAKE_REQUIRED'])
+
+export async function initializeExecution(repositoryRoot, planInput) {
+  const plan = validatePlan(planInput)
+  return withExecutionLock(repositoryRoot, plan.chainId, async (root, file) => {
+    await assertNewExecution(file)
+    const state = initialState(plan, resolveContexts(root, plan))
+    await saveExecution(file, state)
+    return state
+  })
+}
+
+async function failedStep(session, error) {
+  const { record, state, file } = session
+  record.error = errorRecord(error)
+  record.status = record.calls.at(-1)?.status === 'uncertain' ? 'uncertain' : 'failed'
+  record.completedAt = new Date().toISOString()
+  await saveExecution(file, state)
+}
+
+async function readyForWork(session, step) {
+  if (step.kind === 'coordinator' || step.skillId === 'confirm-protocol') return true
+  try {
+    await assertChainNotSuspended({ repositoryRoot: session.root, chainId: session.state.chainId })
+    return true
+  } catch (error) {
+    if (!COORDINATION_CODES.has(error.code)) throw error
+    session.record.status = 'blocked'
+    session.record.error = errorRecord(error)
+    session.record.pending = { kind: 'coordination-guard' }
+    await saveExecution(session.file, session.state)
+    return false
+  }
+}
+
+function finish(record, output, status) {
+  record.output = output
+  record.status = status
+  record.pending = null
+  record.completedAt = new Date().toISOString()
+}
+
+async function stillWaiting(session, output, pending) {
+  if (output.status === 'waiting') return true
+  const releasedByHuman = pending.decision?.status === 'resolved'
+    && pending.decision.answer === 'resume:' + pending.input.agentId
+  if (output.status !== 'blocked' || (output.wakePackage?.reason !== 'event-received' && !releasedByHuman)) return false
+  const current = (await callCoordinator(session, 'status', {})).state
+  const task = current.tasks.find((item) => item.taskId === pending.input.taskId)
+  if (!task || ['completed', 'failed', 'reclaimed'].includes(task.status)) return false
+  return current.waits.some((wait) => wait.taskId === task.taskId && wait.status === 'active')
+    || current.decisions.some((decision) => decision.status === 'pending' && decision.agents.includes(task.agentId))
+}
+
+async function driveWait(session) {
+  const pending = session.record.pending
+  const output = await callCoordinator(session, 'wait-for-event', pending.input)
+  session.record.output = output
+  if (await stillWaiting(session, output, pending)) {
+    session.record.status = 'waiting'
+    await saveExecution(session.file, session.state)
+    return
+  }
+  if (output.confirmProtocolRequests.length) {
+    await prepareHuman(session, output.confirmProtocolRequests[0].input.interaction, pending.input)
+    return
+  }
+  const releasedByHuman = pending.decision?.status === 'resolved'
+    && pending.decision.answer === 'resume:' + pending.input.agentId
+    && output.status === 'resolved'
+  if (releasedByHuman) {
+    finish(session.record, { ...output, status: 'resolved-by-human',
+      humanDecision: pending.decision, confirmation: pending.confirmation }, 'succeeded')
+  } else if (output.status === 'resolved' && output.wakePackage.reason === 'event-received') {
+    finish(session.record, output, 'succeeded')
+  } else {
+    finish(session.record, output, 'blocked')
+    session.record.error = { code: 'AIMLOCK_CHAIN_DEPENDENCY_UNFULFILLED',
+      message: 'Dependency ended without its event or a human decision releasing this task' }
+  }
+  await saveExecution(session.file, session.state)
+}
+
+function saveQueuePending(record, output, input) {
+  record.pending = { kind: 'coordinator-lock-queue', input: { queueId: output.queued.queueId,
+    taskId: input.taskId, agentId: input.agentId, chainId: input.chainId } }
+  record.status = 'waiting'
+  record.completedAt = null
+}
+
+async function driveQueue(session) {
+  await callCoordinator(session, 'tick', { now: new Date().toISOString() })
+  try {
+    const output = await callCoordinator(session, 'lock-queue-status', session.record.pending.input)
+    session.record.output = output
+    if (output.status === 'queued') session.record.status = 'waiting'
+    else finish(session.record, output, output.status === 'granted' ? 'succeeded' : 'blocked')
+  } catch (error) {
+    if (!QUEUE_BLOCK_CODES.has(error.code)) throw error
+    session.record.error = errorRecord(error)
+    finish(session.record, { status: 'blocked', queueId: session.record.pending.input.queueId,
+      error: session.record.error }, 'blocked')
+  }
+  await saveExecution(session.file, session.state)
+}
+
+async function coordinatorStep(session, step, input) {
+  const output = await callCoordinator(session, step.operation, input)
+  session.record.output = output
+  if (step.operation === 'lock-acquire' && output.status === 'queued') {
+    saveQueuePending(session.record, output, input)
+  } else if (step.operation === 'dependency-wait') {
+    const waitInput = { taskId: input.taskId, agentId: input.waiter, chainId: input.chainId, waitId: output.wait.waitId }
+    session.record.pending = { kind: 'coordinator-wait', input: waitInput }
+    session.record.status = 'waiting'
+    await saveExecution(session.file, session.state)
+    await driveWait(session)
+  } else if (step.operation === 'wait-for-event') {
+    session.record.pending = { kind: 'coordinator-wait', input }
+    session.record.status = 'waiting'
+    await saveExecution(session.file, session.state)
+    if (await stillWaiting(session, output, session.record.pending)) {
+      session.record.status = 'waiting'
+    } else if (output.confirmProtocolRequests.length) {
+      await prepareHuman(session, output.confirmProtocolRequests[0].input.interaction, input)
+    } else if (output.status === 'resolved' && output.wakePackage.reason === 'event-received') {
+      finish(session.record, output, 'succeeded')
+    } else finish(session.record, output, 'blocked')
+  } else {
+    const status = BLOCKED_LOCAL_STATUSES.has(output.status) || output.allowed === false
+      || output.undeclaredWait === true || output.decisions?.some((item) => item.confirmationRequired)
+      ? 'blocked' : FAILED_LOCAL_STATUSES.has(output.status) ? 'failed' : 'succeeded'
+    finish(session.record, output, status)
+  }
+}
+
+async function executeStep(session, step) {
+  if (!await readyForWork(session, step)) return
+  const input = bindInput(step, session.state)
+  session.record.input = input
+  session.record.status = 'running'
+  session.record.error = null
+  session.record.startedAt = new Date().toISOString()
+  session.record.attemptId = 'attempt-' + randomUUID()
+  await saveExecution(session.file, session.state)
+  if (step.kind === 'command') {
+    const output = await callCommand(session, input)
+    finish(session.record, output, output.status)
+  } else if (step.kind === 'coordinator') await coordinatorStep(session, step, input)
+  else {
+    const output = await callSkill(session, step.skillId, step.operation, input)
+    if (step.skillId === 'confirm-protocol' && step.operation === 'interaction-request' && output.status === 'succeeded') {
+      session.record.status = 'waiting'
+      session.record.output = output
+      session.record.pending = { kind: 'human', interaction: output.interaction, waitInput: null,
+        presentation: output.chatFallback, response: output,
+        continueWhen: Object.hasOwn(step, 'continueWhen') ? step.continueWhen : null }
+    } else {
+      const outcome = skillOutcome(step, output)
+      finish(session.record, output, outcome.status)
+      session.record.error = outcome.error
+    }
+  }
+  await saveExecution(session.file, session.state)
+}
+
+async function advance(root, file, state, dependencies) {
+  for (const step of state.plan.steps) {
+    const record = state.steps.find((item) => item.stepId === step.stepId)
+    if (record.status === 'succeeded') continue
+    if (record.status === 'blocked' && step.kind === 'coordinator' && step.operation === 'lock-acquire'
+      && record.output?.status === 'queued' && record.input) saveQueuePending(record, record.output, record.input)
+    const session = { root, file, state, record, dependencies }
+    if (['failed', 'uncertain'].includes(record.status)) return state
+    if (record.status === 'waiting' && record.pending?.kind === 'human') return state
+    if (record.status === 'blocked' && record.pending?.kind !== 'coordination-guard') return state
+    if (step.dependsOn.some((id) => state.steps.find((item) => item.stepId === id).status !== 'succeeded')) {
+      fail('AIMLOCK_CHAIN_DEPENDENCY_INVALID', 'previous dependency has not succeeded')
+    }
+    try {
+      if (record.status === 'waiting' && record.pending?.kind === 'coordinator-lock-queue') await driveQueue(session)
+      else if (record.status === 'waiting' && record.pending?.kind === 'coordinator-wait') await driveWait(session)
+      else await executeStep(session, step)
+    } catch (error) { await failedStep(session, error) }
+    if (record.status !== 'succeeded') return state
+  }
+  return state
+}
+
+export async function resumeExecution(repositoryRoot, chainId, dependencies) {
+  return withExecutionLock(repositoryRoot, chainId, async (root, file) => {
+    const state = await loadExecution(file)
+    verifyContexts(root, state)
+    recoverInterrupted(state)
+    await saveExecution(file, state)
+    return advance(root, file, state, dependencies)
+  })
+}
+
+export async function answerExecution(repositoryRoot, chainId, terminal, dependencies) {
+  return withExecutionLock(repositoryRoot, chainId, async (root, file) => {
+    const state = await loadExecution(file)
+    verifyContexts(root, state)
+    recoverInterrupted(state)
+    await saveExecution(file, state)
+    const record = state.steps.find((item) => item.status !== 'succeeded')
+    if (!record) fail('AIMLOCK_CHAIN_NOT_WAITING_FOR_HUMAN', 'execution is complete')
+    const session = { root, file, state, record, dependencies }
+    try { await answerPending(session, terminal) } catch (error) {
+      if (record.status !== 'running') throw error
+      await failedStep(session, error)
+      return state
+    }
+    return advance(root, file, state, dependencies)
+  })
+}
+
+export { executionStatus }

package/aimlock-chain-human.mjs

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto'
+import { createInterface } from 'node:readline/promises'
+import { fail, identifier } from './aimlock-local-fs.mjs'
+import { callCoordinator, callSkill } from './aimlock-chain-calls.mjs'
+import { saveExecution } from './aimlock-chain-store.mjs'
+import { answerMatchesContinuation } from './aimlock-chain-outcomes.mjs'
+
+const ANSWER_PROMPT = '答案 / Answer / Ответ > '
+
+export async function prepareHuman(session, interaction, waitInput) {
+  const output = await callSkill(session, 'confirm-protocol', 'interaction-request', { interaction })
+  if (output.status !== 'succeeded' || JSON.stringify(output.interaction) !== JSON.stringify(interaction)) {
+    fail('AIMLOCK_CHAIN_CONFIRM_REJECTED', 'Confirm Protocol did not accept the bound interaction')
+  }
+  session.record.status = 'waiting'
+  session.record.pending = { kind: 'human', interaction: output.interaction, waitInput,
+    presentation: output.chatFallback, response: output }
+  await saveExecution(session.file, session.state)
+}
+
+function normalizeSelection(interaction, source) {
+  const text = source.trim()
+  if (!text) fail('AIMLOCK_CHAIN_ANSWER_REQUIRED', 'an explicit answer is required')
+  if (interaction.type === 'input') return text
+  const selected = interaction.type === 'multi' ? text.split(',').map((part) => part.trim()) : [text]
+  const ids = interaction.options.map((option) => option.id)
+  if (new Set(selected).size !== selected.length || selected.some((item) => !ids.includes(item))) {
+    fail('AIMLOCK_CHAIN_ANSWER_INVALID', 'answer must use the displayed option IDs')
+  }
+  return interaction.type === 'multi' ? selected : selected[0]
+}
+
+async function readHumanAnswer(pending, input, output) {
+  if (input.isTTY !== true || output.isTTY !== true) {
+    fail('AIMLOCK_CHAIN_TTY_REQUIRED', 'the answer command requires an interactive terminal; redirected answers are not accepted')
+  }
+  output.write(pending.interaction.question + '\n')
+  if (pending.interaction.riskDescription) output.write(pending.interaction.riskDescription + '\n')
+  for (const option of pending.interaction.options) output.write(option.id + ': ' + option.label + '\n')
+  const terminal = createInterface({ input, output })
+  try {
+    return normalizeSelection(pending.interaction, await terminal.question(ANSWER_PROMPT))
+  } finally { terminal.close() }
+}
+
+function verifyAnswer(output, pending, submitted) {
+  const audit = output.auditEntry
+  const callback = output.callbackRequest
+  if (output.status !== 'succeeded' || !audit || !callback
+    || audit.requestId !== pending.interaction.requestId || audit.actorId !== submitted.actorId
+    || JSON.stringify(audit.answer) !== JSON.stringify(submitted.answer) || audit.remembered !== false
+    || audit.question !== pending.interaction.question
+    || audit.risk !== pending.interaction.risk || audit.answeredAt !== submitted.answeredAt
+    || audit.auditId !== submitted.auditId || callback.operation !== pending.interaction.callback.operation
+    || callback.payload.requestId !== pending.interaction.requestId
+    || JSON.stringify(callback.payload.answer) !== JSON.stringify(submitted.answer)) {
+    fail('AIMLOCK_CHAIN_CONFIRM_BINDING_INVALID', 'confirmed response is not bound to the displayed question and actual answer')
+  }
+  for (const [key, value] of Object.entries(pending.interaction.callback.payload)) {
+    if (JSON.stringify(callback.payload[key]) !== JSON.stringify(value)) {
+      fail('AIMLOCK_CHAIN_CONFIRM_BINDING_INVALID', 'callback payload changed')
+    }
+  }
+}
+
+export async function answerPending(session, terminal) {
+  const pending = session.record.pending
+  if (session.record.status !== 'waiting' || pending?.kind !== 'human') {
+    fail('AIMLOCK_CHAIN_NOT_WAITING_FOR_HUMAN', 'this step has no pending human question')
+  }
+  const actorId = identifier(terminal.actorId, 'actorId')
+  const answer = await readHumanAnswer(pending, terminal.input, terminal.output)
+  const submitted = { interaction: pending.interaction, answer, actorId, remembered: false,
+    answeredAt: new Date().toISOString(), auditId: 'audit-' + randomUUID() }
+  session.record.status = 'running'
+  await saveExecution(session.file, session.state)
+  const output = await callSkill(session, 'confirm-protocol', 'interaction-answer', submitted)
+  verifyAnswer(output, pending, submitted)
+  if (pending.waitInput !== null) {
+    const decisionId = pending.interaction.callback.payload.decisionId
+    if (pending.interaction.callback.operation !== 'resolve-human' || decisionId !== pending.interaction.requestId) {
+      fail('AIMLOCK_CHAIN_CONFIRM_BINDING_INVALID', 'coordinator decision callback does not match')
+    }
+    const resolution = await callCoordinator(session, 'resolve-human', { decisionId, answer, actorId })
+    session.record.output = { ...session.record.output, humanResolution: resolution, confirmation: output }
+    session.record.pending = { kind: 'coordinator-wait', input: pending.waitInput,
+      decision: resolution.decision, confirmation: output }
+    session.record.status = 'waiting'
+  } else {
+    session.record.output = { interaction: pending.interaction, ...output }
+    session.record.pending = null
+    const authorized = answerMatchesContinuation(pending.continueWhen, output.auditEntry.answer)
+    session.record.status = authorized ? 'succeeded' : 'blocked'
+    session.record.error = authorized ? null : { code: 'AIMLOCK_CHAIN_CONTINUATION_NOT_AUTHORIZED',
+      message: 'The actual answer did not satisfy an explicit continuation condition' }
+    session.record.completedAt = new Date().toISOString()
+  }
+  await saveExecution(session.file, session.state)
+}