@agent-assistant/continuation

The bounded runtime primitive that turns resumable harness outcomes into explicit state, validated resume triggers, and real follow-up delivery.

Overview

A continuation begins when @agent-assistant/harness stops a turn honestly but not finally — the assistant asked a clarifying question, an action is waiting for approval, or work was deferred because an external process is still pending. The continuation package owns everything that happens after that stop:

• persisting the resumable turn state as a typed ContinuationRecord
• accepting an explicit resume trigger that matches what the continuation is waiting for
• validating liveness (not expired, not already terminal, within max attempt bounds)
• re-entering harness with a new bounded turn
• recording follow-up delivery state

What it does not own:

• bounded turn execution → @agent-assistant/harness
• session identity/lifecycle → @agent-assistant/sessions
• transport delivery → @agent-assistant/surfaces
• approval/risk decisions → @agent-assistant/policy
• long-term memory → @agent-assistant/memory
• generic scheduled nudges → @agent-assistant/proactive

Installation

npm install @agent-assistant/continuation

Quick start

import { createContinuationRuntime, InMemoryContinuationStore } from '@agent-assistant/continuation';

const runtime = createContinuationRuntime({
  store: new InMemoryContinuationStore(),
  harness: myHarnessAdapter,    // implements ContinuationHarnessAdapter
  delivery: myDeliveryAdapter,  // optional: implements ContinuationDeliveryAdapter
});

// 1. After harness returns needs_clarification:
const { continuation } = await runtime.create({
  assistantId: 'sage',
  sessionId: 'session-123',
  originTurnId: 'turn-abc',
  harnessResult,  // the HarnessResult with outcome: 'needs_clarification'
});
// continuation.status === 'pending'
// continuation.waitFor.type === 'user_reply'

// 2. When the user replies:
const result = await runtime.resume({
  continuationId: continuation.id,
  trigger: {
    type: 'user_reply',
    message: { id: 'msg-2', text: 'London', receivedAt: new Date().toISOString() },
    receivedAt: new Date().toISOString(),
  },
});
// result.continuation.status === 'completed'
// result.harnessResult — the result of the resumed bounded turn

// 3. Cancel when no longer needed:
await runtime.stop({
  continuationId: continuation.id,
  reason: 'cancelled_by_user',
});

API Reference

createContinuationRuntime(config)

Returns a ContinuationRuntime bound to the provided config.

interface ContinuationConfig {
  store: ContinuationStore;
  harness: ContinuationHarnessAdapter;
  delivery?: ContinuationDeliveryAdapter;
  scheduler?: ContinuationSchedulerAdapter;
  clock?: ContinuationClock;
  trace?: ContinuationTraceSink;
  defaults?: ContinuationDefaults;
}

ContinuationRuntime

create(input)

Accepts a resumable HarnessResult (needs_clarification, awaiting_approval, deferred) and returns a ContinuationCreateResult containing the new ContinuationRecord.

Rejects non-resumable outcomes (completed, failed) with ContinuationInvalidInputError.

The wait condition is derived from the outcome:

resume(input)

Accepts a ContinuationResumeTrigger and re-enters harness if all validation passes:

1. Record exists
2. Record status is pending
3. Current time is before expiresAt
4. Trigger type matches waitFor.type
5. Correlation identifiers match (approvalId, operationId)
6. resumeAttempts < maxResumeAttempts

Approval denied: if trigger is approval_resolution with decision: 'denied', harness is not called and the record is marked cancelled with reason approval_denied.

Re-pending: if harness returns another resumable outcome, the record is re-pended with a new wait condition (not a new record).

stop(input)

Terminal reasons map to statuses:

Stop is idempotent: calling stop on an already-terminal record returns it unchanged.

Continuation lifecycle

                    ┌─────────────┐
                    │   pending    │
                    └──────┬───────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                  │
         ▼                 ▼                  ▼
  ┌────────────┐  ┌────────────────┐  ┌──────────────┐
  │  resuming   │  │    expired     │  │  cancelled/  │
  └──────┬─────┘  └────────────────┘  │  superseded  │
         │                            └──────────────┘
  ┌──────┼──────┐
  │      │      │
  ▼      ▼      ▼
completed failed pending (re-pend)

Wait conditions and triggers

TTL defaults

Override defaults via config.defaults or per-record via create({ bounds }).

Adapters

ContinuationHarnessAdapter

interface ContinuationHarnessAdapter {
  runResumedTurn(input: ContinuationResumedTurnInput): Promise<HarnessResult>;
}

Products implement this to wire turn-context assembly before calling harness.

ContinuationDeliveryAdapter

interface ContinuationDeliveryAdapter {
  deliver(input: ContinuationDeliveryInput): Promise<ContinuationDeliveryResult>;
}

Optional. When present, called after a resumed turn produces a user-visible terminal result.

ContinuationSchedulerAdapter

interface ContinuationSchedulerAdapter {
  scheduleWake(input: { continuationId: string; wakeAtMs: number }): Promise<{ wakeUpId: string }>;
  cancelWake?(wakeUpId: string): Promise<void>;
}

Optional. Required only for scheduled_wake continuations.

ContinuationStore

interface ContinuationStore {
  put(record: ContinuationRecord): Promise<void>;
  get(continuationId: string): Promise<ContinuationRecord | null>;
  delete?(continuationId: string): Promise<void>;
  listBySession?(sessionId: string): Promise<ContinuationRecord[]>;
}

Only put and get are required. Use InMemoryContinuationStore for tests and development.

Delivery state

Error types

Boundaries

• Harness emits resumable outcomes. Continuation operationalizes them. Harness is not affected by this package.
• Proactive vs continuation: if there is no originating stopped turn id, it is proactive. If the assistant is resuming a known unfinished turn lineage, it is continuation.
• Continuation is not a scheduler. Scheduled wake is a trigger type, not a scheduler implementation.
• Continuation is not a memory system. It stores short-lived operational state for one unfinished turn lineage only.
• v1 scope: one live record per origin turn. Multi-branch continuation graphs are explicitly out of scope.