Machine Markets: Orchestration

The orchestration surface is what makes a service execute end to end. Native skills run through registered runtime endpoints. Machine-side runtime agents register and heartbeat their own endpoints. Tasks model a discover-resolve-execute lifecycle and emit Routes, Outcomes, and Runs. Policies enforce cross-cutting rules. Audit events log every state change. See the Machine Markets overview for base path, auth model, and common envelopes. Every endpoint below that names a machine (in the path, the body, or the machineId query) requires the machine to be active and identity-verified. Errors MACHINE_NOT_ACTIVE and MACHINE_NOT_ACTIVATED are uniform across that group. Policies and audit events are not tied to a machine and skip this check.

Runtime endpoints

`GET /machines/:machineId/runtime-endpoints`

type ListRuntimeEndpointsResponse = ListResponse<RuntimeEndpointView>;

`GET /machines/:machineId/runtime-endpoints/:providerKey`

type GetRuntimeEndpointResponse = ItemResponse<RuntimeEndpointView>;

`PUT /machines/:machineId/runtime-endpoints/:providerKey`

Upsert a manual runtime endpoint. source is forced to manual. Returns 201 on create, 200 on update. The server lowercases providerKey in the path.

type UpsertRuntimeEndpointRequest = {
  endpointBaseUrl: string;          // http/https URL, path/query/hash stripped
  label?: string;                   // default `${providerKey.toUpperCase()} runtime`
  authType?: "none" | "api-key" | "bearer";
  authToken?: string;
  modelAlias?: string;
  networkScope?: "loopback" | "lan" | "vpn" | "public";
  probePath?: string;               // default "/v1/models" for qvac, else "/health"
  status?: "active" | "degraded" | "unreachable";
  leaseExpiresAt?: string;          // ISO 8601
};

type UpsertRuntimeEndpointResponse = ItemResponse<RuntimeEndpointView>;

Errors: VALIDATION_ERROR (invalid URL).

`DELETE /machines/:machineId/runtime-endpoints/:providerKey`

Returns 204. Errors: NOT_FOUND.

`RuntimeEndpointView`

The view never echoes authToken. Use hasAuthToken to check whether one is stored.

type RuntimeEndpointView = {
  id: string;
  machineId: string;
  providerKey: string;
  source: "manual" | "agent";
  agentId: string | null;
  label: string;
  endpointBaseUrl: string;
  authType: "none" | "api-key" | "bearer";
  hasAuthToken: boolean;
  modelAlias: string | null;
  networkScope: "loopback" | "lan" | "vpn" | "public";
  probePath: string;
  status: "active" | "degraded" | "unreachable";
  leaseExpiresAt: string | null;
  lastCheckedAt: string | null;
  lastHealthyAt: string | null;
  createdAt: string;
  updatedAt: string;
};

Machine-side agents

`POST /machines/:machineId/agents/enrollment`

Enrols a new runtime agent. Returns the agent record plus a one-time agentToken.

type EnrollMachineAgentRequest = {
  label?: string;                   // default "Machine runtime agent"
  allowedProviderKeys?: string[];   // default ["qvac"], normalised to lowercase
  providerKeys?: string[];          // alias for allowedProviderKeys
};

type EnrollMachineAgentResponse = {
  item: MachineAgentView & { agentToken: string };
};

`POST /machine-agents/heartbeat`

Heartbeat from an on-machine runtime agent. Auth via agentToken body field or x-agent-pairing-token / Authorization: Bearer header. Upserts one or many endpoints with source: "agent" and a lease.

type HeartbeatRequest = {
  machineId: string;
  agentId: string;
  agentToken?: string;
  leaseSeconds?: number;            // [30, 86400], default 120
  endpoints?: Array<{
    providerKey: string;
    endpointBaseUrl: string;
    label?: string;
    authType?: "none" | "api-key" | "bearer";
    authToken?: string;
    modelAlias?: string;
    networkScope?: "loopback" | "lan" | "vpn" | "public";
    probePath?: string;
    status?: "active" | "degraded" | "unreachable";
  }>;
};

type HeartbeatResponse = {
  item: MachineAgentView;
  endpoints: RuntimeEndpointView[];
};

Errors: VALIDATION_ERROR, NOT_FOUND, AGENT_PAIRING_INACTIVE (status revoked), AGENT_AUTH_REQUIRED, AGENT_AUTH_INVALID, AGENT_POLICY_DENIED (provider key not in agent.allowedProviderKeys). Side effects: agent status flips to active, lastSeenAt updates, each endpoint upserts with leaseExpiresAt = now + leaseSeconds.

`MachineAgentView`

type MachineAgentView = {
  id: string;
  machineId: string;
  label: string;
  allowedProviderKeys: string[];
  status: "provisioned" | "active" | "revoked";
  hasAgentToken: boolean;
  lastSeenAt: string | null;
  createdAt: string;
  updatedAt: string;
};

Graph

`GET /machines/:machineId/graph`

type GetGraphResponse = {
  nodes: GraphNodeRecord[];
  edges: GraphEdgeRecord[];
};

`POST /machines/:machineId/graph/nodes`

type CreateGraphNodeRequest = {
  type: NodeType;
  title: string;
  refId?: string;
  position?: { x?: number; y?: number };
  data?: Record<string, unknown>;
};

type CreateGraphNodeResponse = ItemResponse<GraphNodeRecord>;

`PATCH /machines/:machineId/graph/nodes/:nodeId`

All fields optional; data is shallow-merged. Status accepted: "draft" | "active" | "blocked" | "degraded".

`DELETE /machines/:machineId/graph/nodes/:nodeId`

Returns 204.

`POST /machines/:machineId/graph/edges`

type CreateGraphEdgeRequest = {
  sourceNodeId: string;
  targetNodeId: string;
  type: EdgeType;
  label?: string;
  data?: Record<string, unknown>;
};

type CreateGraphEdgeResponse = ItemResponse<GraphEdgeRecord>;

`PATCH /machines/:machineId/graph/edges/:edgeId` / `DELETE /machines/:machineId/graph/edges/:edgeId`

Standard patch and delete semantics.

Graph types

type NodeType =
  | "machine" | "trigger" | "skill" | "task" | "policy" | "discovery"
  | "storage" | "memory" | "handoff" | "route" | "outcome" | "catalog-entry";

type EdgeType =
  | "connects" | "request" | "discover" | "constrain" | "candidate"
  | "route" | "result" | "route-select" | "route-source" | "execute"
  | "handoff" | "receipt" | "sync" | "allow" | "deny";

type GraphNodeRecord = {
  id: string;
  machineId: string;
  type: NodeType;
  refId?: string | null;
  title: string;
  status: "draft" | "active" | "blocked" | "degraded";
  position: { x: number; y: number };
  data: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
};

type GraphEdgeRecord = {
  id: string;
  machineId: string;
  sourceNodeId: string;
  targetNodeId: string;
  type: EdgeType;
  label?: string;
  data: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
};

Tasks

Tasks model the discover-resolve-execute pipeline that orders ride on. POST /market/orders/:orderId/execute materialises an order as a task internally, but tasks can also be driven directly.

`GET /machines/:machineId/tasks`

type ListTasksResponse = ListResponse<TaskRecord>;

`POST /machines/:machineId/tasks`

type CreateTaskRequest = {
  serviceType: ServiceType;
  taskType: string;
  operation?: string;
  input?: Record<string, unknown>;
  constraints?: {
    region?: string;
    budget?: number;                 // >= 0
    allowExternalHandoff?: boolean;  // default true
    requireNativeExecution?: boolean;// default false
    requiredCapabilities?: string[];
    preferredSkillKeys?: string[];   // must all be known skills
  };
  discovery?: { maxCandidates?: number };  // 1..25, default 10
};

type CreateTaskResponse = ItemResponse<TaskRecord>;

`GET /machines/:machineId/tasks/:taskId`

type GetTaskResponse = ItemResponse<TaskRecord>;

`POST /machines/:machineId/tasks/:taskId/discover`

Runs discovery against the catalogue for a queued task.

type DiscoverTaskRequest = {
  allowExternalHandoff?: boolean;
  requireNativeExecution?: boolean;
  maxCandidates?: number;
};

type DiscoverTaskResponse = {
  taskId: string;
  machineId: string;
  resolution: TaskResolution;
  candidates: Candidate[];
};

`POST /machines/:machineId/tasks/:taskId/resolve`

Picks a route and persists it. Returns 201.

type ResolveTaskResponse = {
  item: RouteRecord;
  resolution: TaskResolution;
};

`POST /machines/:machineId/tasks/:taskId/execute`

Executes the resolved route. HTTP status propagates from the inner execution result.

type ExecuteTaskRequest = {
  input?: Record<string, unknown>;
};

type ExecuteTaskResponse = {
  item: OutcomeRecord;
  run: RunRecord;
  resolution: TaskResolution;
};

Errors: ROUTE_REQUIRED (no route resolved), plus all downstream skill-runtime errors.

Task types

type ExternalHandoff = {
  label: string;
  url: string;
  notes: string[];
};

type Candidate = {
  service: CatalogService;          // catalogue service shape, see machine-markets-discovery
  score: number;
  reasons: string[];
};

type TaskResolution =
  | { kind: "native"; candidate: Candidate }
  | { kind: "handoff"; candidate: Candidate; handoff: ExternalHandoff }
  | { kind: "unavailable"; reason: string; candidates: Candidate[] };

type TaskStatus =
  | "draft" | "queued" | "resolving" | "resolved"
  | "executing" | "completed" | "failed" | "handed_off";

type TaskRecord = {
  id: string;
  machineId: string;
  serviceType: ServiceType;
  operation?: string;
  taskType: string;
  status: TaskStatus;
  input: Record<string, unknown>;
  constraints: {
    region?: string;
    budget?: number;
    allowExternalHandoff: boolean;
    requireNativeExecution: boolean;
    requiredCapabilities: string[];
    preferredSkillKeys?: string[];
  };
  discovery: { maxCandidates: number };
  routeId?: string | null;
  outcomeId?: string | null;
  createdAt: string;
  updatedAt: string;
};

Routes, outcomes, runs

`GET /machines/:machineId/routes`

type ListRoutesResponse = ListResponse<RouteRecord>;

`GET /machines/:machineId/outcomes`

type ListOutcomesResponse = ListResponse<OutcomeRecord>;

`GET /runs?machineId={id}&...`

type ListRunsQuery = {
  machineId: string;
  status?: RunStatus;
  skillKey?: string;
  serviceId?: string;
  executionMode?: ExecutionMode;
  limit?: number;        // default 100, max 500
};

type ListRunsResponse = ListResponse<RunRecord>;

`GET /runs/:runId`

type GetRunResponse = {
  run: RunRecord;
  outcome: OutcomeRecord | null;
};

Route / Outcome / Run types

type RouteStatus = "selected" | "blocked" | "handed_off" | "failed" | "completed";
type OutcomeStatus = "pending" | "running" | "completed" | "failed" | "external";
type RunStatus = "queued" | "running" | "completed" | "failed" | "external" | "blocked";

type RouteRecord = {
  id: string;
  machineId: string;
  taskId: string;
  selectedSkillKey: string;
  selectedServiceId: string;
  executionMode: ExecutionMode;
  integrationStatus: IntegrationStatus;
  status: RouteStatus;
  reason: string;
  score: number;
  fallbackChain: Array<{ skillKey: string; serviceId: string; executionMode: ExecutionMode }>;
  handoff: ExternalHandoff | null;
  createdAt: string;
  updatedAt: string;
};

type OutcomeRecord = {
  id: string;
  machineId: string;
  taskId: string;
  routeId: string;
  status: OutcomeStatus;
  skillKey: string;
  serviceId: string;
  executionMode: ExecutionMode;
  receiptRef?: string | null;
  logsRef?: string | null;
  externalRef?: string | null;
  errorCode?: string | null;
  errorMessage?: string | null;
  result?: unknown;
  createdAt: string;
  updatedAt: string;
};

type RunRecord = {
  id: string;
  machineId: string;
  taskId: string;
  routeId?: string | null;
  outcomeId?: string | null;
  status: RunStatus;
  executionMode?: ExecutionMode | null;
  skillKey?: string | null;
  serviceId?: string | null;
  summary?: string | null;
  createdAt: string;
  updatedAt: string;
};

Policies

Policies enforce cross-cutting rules above and beyond a ’s .

`GET /policies`

type ListPoliciesResponse = ListResponse<PolicyRecord>;

`POST /policies`

type CreatePolicyRequest = {
  name: string;
  allowedSkillKeys?: string[];
  deniedSkillKeys?: string[];
  budgetCap?: { amount: number; currency: string } | null;
  regionRules?: string[];
  nativeOnly?: boolean;
  handoffAllowed?: boolean;
  requiredCapabilities?: string[];
};

type CreatePolicyResponse = ItemResponse<PolicyRecord>;

`GET /policies/:policyId` / `PATCH /policies/:policyId`

Standard get and patch semantics.

`PolicyRecord`

type PolicyRecord = {
  id: string;
  name: string;
  allowedSkillKeys: string[];
  deniedSkillKeys: string[];
  budgetCap?: { currency: string; amount: number } | null;
  regionRules: string[];
  nativeOnly: boolean;
  handoffAllowed: boolean;
  requiredCapabilities: string[];
  createdAt: string;
  updatedAt: string;
};

Audit events

`GET /audit-events`

type ListAuditEventsQuery = {
  type?: string;
  resourceType?: string;
  resourceId?: string;
  limit?: number;        // default 100, max 500
};

type ListAuditEventsResponse = ListResponse<AuditEventRecord>;

type AuditEventRecord = {
  id: string;
  actor: string;          // "api" | "system:machine-markets"
  type: string;
  resourceType: string;
  resourceId: string;
  payload: Record<string, unknown>;
  createdAt: string;
};

Event types emitted by the orchestration surface: runtime-endpoint.upserted, runtime-endpoint.deleted, machine-agent.enrolled, machine-agent.heartbeat, graph.node.created, graph.node.updated, graph.node.deleted, graph.edge.created, graph.edge.updated, graph.edge.deleted, task.created, task.resolved, task.executed, task.execution-failed, task.handoff-recorded, policy.created, policy.updated, market.order.created, market.payment.intent-created, market.payment.proof-recorded, market.payment.settlement-recorded, market.order.executed, market.order.confirmed, market.order.disputed, market.payment.escrow-held, market.payment.released, market.payment.refunded.

​Runtime endpoints

​GET /machines/:machineId/runtime-endpoints

​GET /machines/:machineId/runtime-endpoints/:providerKey

​PUT /machines/:machineId/runtime-endpoints/:providerKey

​DELETE /machines/:machineId/runtime-endpoints/:providerKey

​RuntimeEndpointView

​Machine-side agents

​POST /machines/:machineId/agents/enrollment

​POST /machine-agents/heartbeat

​MachineAgentView

​Graph

​GET /machines/:machineId/graph

​POST /machines/:machineId/graph/nodes

​PATCH /machines/:machineId/graph/nodes/:nodeId

​DELETE /machines/:machineId/graph/nodes/:nodeId

​POST /machines/:machineId/graph/edges

​PATCH /machines/:machineId/graph/edges/:edgeId / DELETE /machines/:machineId/graph/edges/:edgeId

​Graph types

​Tasks

​GET /machines/:machineId/tasks

​POST /machines/:machineId/tasks

​GET /machines/:machineId/tasks/:taskId

​POST /machines/:machineId/tasks/:taskId/discover

​POST /machines/:machineId/tasks/:taskId/resolve

​POST /machines/:machineId/tasks/:taskId/execute

​Task types

​Routes, outcomes, runs

​GET /machines/:machineId/routes

​GET /machines/:machineId/outcomes

​GET /runs?machineId={id}&...

​GET /runs/:runId

​Route / Outcome / Run types

​Policies

​GET /policies

​POST /policies

​GET /policies/:policyId / PATCH /policies/:policyId

​PolicyRecord

​Audit events

​GET /audit-events

​Related