Execution Plans

Execution plans are contract-driven workflow runs. Agents define a compiled workflow specification up front, then the runtime executor owns node transitions, validation, approvals, checkpoints, and artifact tracking.

Overview

The execution-plan runtime stores data across spec, run, and support tables:

Table	Purpose
planSpec	Immutable compiled workflow specification for a workstream version
planNodeSpec	Contract for each node in the specification
planRun	Active or completed execution instance for a spec
planNodeRun	Per-node runtime state within a run
planNodeAttempt	Submitted execution attempts for a node
planArtifact	First-class outputs produced by attempts
planApproval	Durable human approval records
planCheckpoint	Restart-safe execution snapshots
planValidationIssue	Blocking or warning validation findings
planEvent	Audit trail for plan, node, approval, and checkpoint changes

Each workstream can have at most one active execution run.

Plan Draft

Agents create plans with a PlanDraft. A draft defines the workflow title, objective, schemas, nodes, edges, and entry nodes.

{
  title: 'Launch marketing campaign',
  objective: 'Produce launch assets, collect approval, and publish',
  schemas: {
    launchBrief: {
      type: 'object',
      required: true,
      properties: {
        headline: { type: 'string', required: true },
        channels: { type: 'array', items: { type: 'string' } },
      },
    },
  },
  nodes: [
    {
      id: 'draft-brief',
      type: 'action',
      label: 'Draft launch brief',
      owner: { executorType: 'agent', ref: 'cmo' },
      objective: 'Create the initial launch brief',
      instructions: 'Draft the brief using the current product positioning.',
      outputSchemaRef: 'launchBrief',
      deliverables: [
        {
          name: 'launch-brief',
          kind: 'markdown',
          required: true,
          description: 'Markdown brief ready for review',
        },
      ],
      successCriteria: ['Brief covers positioning, audience, and rollout channels'],
      completionChecks: [
        {
          type: 'schema',
          description: 'Structured output matches launchBrief schema',
          config: { schemaRef: 'launchBrief' },
          blocking: true,
        },
      ],
      retryPolicy: { maxAttempts: 1, retryOn: ['schema_validation_failed'] },
      failurePolicy: [{ on: 'human_rejected', action: 'replan', note: 'Revise the workflow if strategy changes' }],
      toolPolicy: { allow: ['searchWeb'], deny: [] },
      contextPolicy: {
        retrievalScopes: ['organization', 'workstream'],
        attachmentPolicy: 'referenced-only',
        webPolicy: 'allowed',
      },
    },
    {
      id: 'approve-brief',
      type: 'human-approval',
      label: 'Approve launch brief',
      owner: { executorType: 'user', ref: 'founder' },
      objective: 'Approve or request changes to the brief',
      instructions: 'Review the launch brief and respond with approval or edits.',
      deliverables: [],
      successCriteria: ['Founder approves the brief'],
      completionChecks: [],
      retryPolicy: { maxAttempts: 0, retryOn: [] },
      failurePolicy: [{ on: 'human_rejected', action: 'replan', note: 'Adjust the plan after review feedback' }],
      toolPolicy: { allow: [], deny: [] },
      contextPolicy: {
        retrievalScopes: ['workstream'],
        attachmentPolicy: 'referenced-only',
        webPolicy: 'forbidden',
      },
    },
  ],
  edges: [{ id: 'brief-to-approval', source: 'draft-brief', target: 'approve-brief', map: {} }],
  entryNodeIds: ['draft-brief'],
}

Node Contracts

Each node contract defines:

• objective and instructions
• owner (agent, plugin, user, or system)
• expected structured output via inputSchemaRef and outputSchemaRef
• required deliverables
• successCriteria
• machine-readable completionChecks
• retryPolicy, failurePolicy, timeoutMs, toolPolicy, and contextPolicy

Run State

PlanRunStatus values are:

Status	Description
running	The executor has active or ready nodes and can continue automatically
awaiting-human	Execution is paused on a human-owned node
blocked	Execution cannot continue without intervention
completed	All required work finished successfully
failed	Execution terminated with an unrecoverable failure
aborted	The run was superseded or explicitly stopped

PlanNodeRunStatus values are:

Status	Description
pending	Node exists in the run but is not yet ready
ready	Node can be picked up by its executor
running	Node is currently being executed
awaiting-human	Waiting on human input, review, approval, or decision
completed	Node completed successfully
partial	Node produced a partial result that still advanced the run
blocked	Node cannot proceed without intervention
failed	Node failed terminally
skipped	Node was intentionally bypassed

Execution Tools

Agents interact with execution plans through five tools:

createExecutionPlan

Creates the first compiled plan and starts a new execution run from its entry nodes.

replaceExecutionPlan

Supersedes the active run with a newly compiled plan. The prior run is marked aborted, and the new run references it through replacedRunId.

{
  runId: 'planRun:abc123',
  reason: 'The strategy changed after stakeholder review',
  ...nextDraft,
}

submitExecutionNodeResult

Submits the result for a running node. The executor validates structured output, required artifacts, completion checks, and failure policy before advancing the run.

{
  runId: 'planRun:abc123',
  nodeId: 'draft-brief',
  result: {
    structuredOutput: {
      headline: 'Lota launches its contract-driven runtime',
      channels: ['email', 'blog', 'social'],
    },
    artifacts: [
      {
        name: 'launch-brief',
        kind: 'markdown',
        pointer: 'generated-documents/launch-brief.md',
        description: 'Drafted brief in markdown',
      },
    ],
    notes: 'Brief drafted and attached for review.',
  },
}

getActiveExecutionPlan

Loads the active run. Callers can opt into events, artifacts, approvals, checkpoints, and validation issues.

{
  includeEvents: true,
  includeArtifacts: true,
  includeApprovals: true,
  includeCheckpoints: false,
  includeValidationIssues: true,
}

resumeExecutionPlanRun

Resumes an interrupted run from its latest checkpoint after the executor reconciles runtime state.

{ runId: 'planRun:abc123' }

Events and Supporting Records

planEvent records cover plan creation, replacement, run status changes, node readiness and completion, approvals, checkpoints, resume events, and validation reports.

Related support records provide durable execution truth:

• planNodeAttempt stores every submitted node attempt
• planArtifact stores attempt outputs and artifact lineage
• planApproval stores human review state and responses
• planCheckpoint stores restart-safe snapshots
• planValidationIssue stores warnings and blocking validation findings

Context Injection

When an active execution run exists, the runtime injects two sections into the agent prompt:

• <execution-plan-protocol>: rules that tell the model to create contract-driven plans and treat executor state as authoritative
• <execution-plan-state>: a JSON payload containing executor policy and the serialized SerializableExecutionPlan

The prompt payload includes run metadata, node contracts, progress, artifacts, approvals, checkpoints, validation issues, and recent events.