Resources

// Register an AI agent with capacity for 3 concurrent tasks
const { data: agent } = await client.resources.create({
  name: 'Claude Analysis Agent',
  type: 'agent',
  capacity: 3,
  metadata: { model: 'claude-opus-4-8', endpoint: 'https://api.example.com/agent' },
})
 
// Register a human specialist (one task at a time)
const { data: specialist } = await client.resources.create({
  name: 'Alice Chen — Legal',
  type: 'human',
  capacity: 1,
})

const start = new Date(Math.ceil((Date.now() + 2 * 3_600_000) / 60_000) * 60_000).toISOString()
 
/** Two independent 60-minute press runs that can both start at `start`. */
function plan(unitsPerRun: number, resourceLeveling: 'off' | 'delay') {
  return client.workflowInstances.createWithGraph({
    instance: { name: `Press plan ${suffix} ${unitsPerRun}/${resourceLeveling}`, resourceLeveling },
    resources: [{ ref: 'press', name: `Press ${suffix}`, type: 'asset', capacity: 2 }], // 2 slots
    tasks: ['run-a', 'run-b'].map((ref) => ({
      ref, name: ref, durationMinutes: 60, earliestStart: start,
      requirements: [{ resourceRef: 'press', units: unitsPerRun }],
    })),
  })
}
const peak = (r: Awaited<ReturnType<typeof plan>>) => r.data.schedule.utilization.find((u) => u.resourceRef === 'press')!.peakUnits
const startOf = (r: Awaited<ReturnType<typeof plan>>, ref: string) => r.data.schedule.tasks.find((t) => t.ref === ref)!.plannedStart
 
// 1 slot each: both runs fit side by side (1 + 1 <= 2)
const oneEach = await plan(1, 'off')
if (peak(oneEach) !== 2 || oneEach.data.schedule.conflicts.length !== 0) throw new Error('1+1 on 2 slots should fit')
if (startOf(oneEach, 'run-a') !== startOf(oneEach, 'run-b')) throw new Error('both should start together')
 
// both slots each, leveling off: the planner keeps both at the same time and REPORTS the overload
const reported = await plan(2, 'off')
if (peak(reported) !== 4) throw new Error('expected 4 units in use on a 2-slot press')
const breach = reported.data.schedule.conflicts
if (breach.length !== 1 || breach[0]!.type !== 'resource_capacity_breach') throw new Error('expected one breach: ' + JSON.stringify(breach))
console.log('off  :', breach[0]!.description)
 
// both slots each, leveling delay: one run waits for the other
const leveled = await plan(2, 'delay')
if (peak(leveled) !== 2 || leveled.data.schedule.conflicts.length !== 0) throw new Error('delay should resolve it')
const a = new Date(startOf(leveled, 'run-a')).getTime()
const b = new Date(startOf(leveled, 'run-b')).getTime()
if (Math.abs(a - b) !== 60 * 60_000) throw new Error('the second run should start 60 minutes after the first')
console.log('delay: second run starts', Math.abs(a - b) / 60_000, 'minutes after the first')

const { data: allocation } = await client.resources.allocate('res_abc123', {
  taskId: 'tsk_xyz',
})
 
console.log(allocation.id, allocation.status) // alloc_... 'allocated'

await client.resources.release('res_abc123', 'alloc_xyz')

await client.resources.update(press.id, { capacity: 3 })           // the press now has 3 slots
await client.resources.update(press.id, { capacity: null })        // no limit
await client.resources.update(operator.id, { status: 'unavailable' }) // leaves pools until active again

// ── Shared state: a dryer that two jobs may share only at similar temperatures ───────
const { data: dryer } = await client.resources.create({
  name: `Dryer ${suffix}`, type: 'asset', capacity: 2,
  stateKey: 'temperature_c', stateTolerance: 10, stateSetupMinutes: 20,
})
if (dryer.stateKey !== 'temperature_c' || dryer.stateTolerance !== 10 || dryer.stateSetupMinutes !== 20) throw new Error('state not stored')
 
await expectError('stateKey without stateTolerance', 400, () =>
  client.resources.create({ name: `Bad ${suffix}`, type: 'asset', stateKey: 'temperature_c' }))
await expectError('stateSetupMinutes without stateKey', 400, () =>
  client.resources.create({ name: `Bad ${suffix}`, type: 'asset', stateSetupMinutes: 5 }))
 
// Update: key and tolerance go together; an update that sets them also resets the setup time
// unless you send it again.
const { data: updated } = await client.resources.update(dryer.id, { stateKey: 'temperature_c', stateTolerance: 15 })
if (updated.stateTolerance !== 15 || updated.stateSetupMinutes !== null) throw new Error('expected setup minutes to be reset by this update')
// Clear all three with null
const { data: cleared } = await client.resources.update(dryer.id, { stateKey: null, stateTolerance: null, stateSetupMinutes: null })
if (cleared.stateKey !== null || cleared.stateTolerance !== null) throw new Error('state not cleared')

// ── Absolute availability windows ────────────────────────────────────────────────────
// An operator who is only on site 11:00-20:00 UTC, three days from now.
const day = new Date()
day.setUTCDate(day.getUTCDate() + 3)
const at = (h: number) => new Date(Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate(), h)).toISOString()
const windows = [{ from: at(11), to: at(20) }] // { start, end } is accepted too
 
const { data: operator } = await client.resources.create({ name: `Operator ${suffix}`, type: 'human', capacity: 1, availability: windows })
if (!Array.isArray(operator.availability) || operator.availability.length !== 1) throw new Error('availability not stored')
 
// Unusable window entries are a 400 (while planning v2 is on), not "always available"
await expectError('window ends before it starts', 400, () =>
  client.resources.create({ name: `Bad ${suffix}`, type: 'human', availability: [{ from: at(20), to: at(11) }] }))
await expectError('window is not a date', 400, () =>
  client.resources.create({ name: `Bad ${suffix}`, type: 'human', availability: [{ from: 'noon', to: 'evening' }] }))
await expectError('update with an unusable window', 400, () => client.resources.update(operator.id, { availability: [{ from: 'x', to: 'y' }] }))
 
// A 60-minute job that wants to start at 09:00, before the operator arrives
const job = (resourceLeveling: 'off' | 'delay') =>
  client.workflowInstances.createWithGraph({
    instance: { name: `Window plan ${suffix} ${resourceLeveling}`, resourceLeveling },
    resources: [{ ref: 'operator', name: `Operator ${suffix} ${resourceLeveling}`, type: 'human', capacity: 1, availability: windows }],
    tasks: [{ ref: 'setup', name: 'Set up the press', durationMinutes: 60, earliestStart: at(9), requirements: [{ resourceRef: 'operator' }] }],
  })
 
const off = await job('off')
const breach = off.data.schedule.conflicts
if (breach.length !== 1 || breach[0]!.type !== 'resource_capacity_breach' || !breach[0]!.description.includes('outside its availability')) {
  throw new Error('expected an availability breach: ' + JSON.stringify(breach))
}
console.log('off  :', breach[0]!.description)
 
const delayed = await job('delay')
const placed = delayed.data.schedule.tasks[0]!
if (delayed.data.schedule.conflicts.length !== 0 || placed.plannedStart !== at(11)) throw new Error('expected the task to wait for the window: ' + placed.plannedStart)
console.log('delay: starts at', placed.plannedStart)

type ResourceStatus = 'active' | 'unavailable' | 'retired'
 
interface Resource {
  id: string
  projectId: string | null
  organizationId?: string | null
  name: string
  type?: 'human' | 'agent' | 'service' | 'asset' | null   // deprecated tag
  resourceTypeId?: string | null
  description?: string | null
  capacity?: number | null
  availability?: unknown[] | null   // { from, to } / { start, end } windows
  properties?: Record<string, unknown> | null
  metadata?: Record<string, unknown> | null
  status?: ResourceStatus
  externalId?: string | null
  platformUserId?: string | null
  costRatePerHour?: number | null
  stateKey?: string | null
  stateTolerance?: number | null
  stateSetupMinutes?: number | null
  createdAt: string
}
 
interface ResourceAllocation {
  id: string
  resourceId: string
  executionId: string | null
  taskId: string | null
  actorId: string | null
  status: 'allocated' | 'released'
  allocatedAt: string
  releasedAt: string | null
}