Run Terminal

Fold racing terminal signals into one authoritative outcome — no last-writer-wins

Several observers can watch the same run at once — an idle watchdog, a run-budget timer, an external /stop, a provider client — and RunTerminal folds their racing signals into one authoritative outcome that only ever refines toward stronger attribution.

Quick Start

1. Simplest merge (no current)

   With no recorded outcome, the observation becomes authoritative.

   Python

   from praisonaiagents import RunTerminal, merge_run_terminal
   
   observed = RunTerminal("failed", "provider")
   outcome = merge_run_terminal(None, observed)
   print(outcome)  # RunTerminal(kind='failed', source='provider', detail=None)

   TypeScript

   import { RunTerminal, mergeRunTerminal } from 'praisonai';
   
   const observed = new RunTerminal({ kind: 'failed', source: 'provider' });
   const outcome = mergeRunTerminal(null, observed);
   console.log(outcome);
   // RunTerminal { kind: 'failed', source: 'provider', detail: undefined }

2. Deliberate cancel is never downgraded

   A user’s /stop wins over a late provider error, whatever the arrival order.

   Python

   from praisonaiagents import RunTerminal, merge_run_terminal, collapse
   
   cancel = RunTerminal("aborted", "external", detail="user /stop")
   late_error = RunTerminal("failed", "provider")
   
   outcome = merge_run_terminal(cancel, late_error)
   print(collapse(outcome))  # 'cancelled' — the user's /stop wins

   TypeScript

   import { RunTerminal, mergeRunTerminal, collapse } from 'praisonai';
   
   const cancel = new RunTerminal({ kind: 'aborted', source: 'external', detail: 'user /stop' });
   const lateError = new RunTerminal({ kind: 'failed', source: 'provider' });
   
   const outcome = mergeRunTerminal(cancel, lateError);
   console.log(collapse(outcome));  // 'cancelled' — the user's /stop wins

3. Round-trip through a durable ledger

   Persist the outcome typed, not as a free string — then rehydrate it.

   Python

   from praisonaiagents import RunTerminal
   
   outcome = RunTerminal("aborted", "external", detail="user /stop")
   
   # Persist to SQLite / JSON / whatever ledger you use
   data = outcome.to_dict()  # {'kind': 'aborted', 'source': 'external', 'detail': 'user /stop'}
   
   # Restart, rehydrate
   restored = RunTerminal.from_dict(data)
   assert restored == outcome  # Python: value equality (frozen dataclass)

   TypeScript

   import { RunTerminal } from 'praisonai';
   
   const outcome = new RunTerminal({ kind: 'aborted', source: 'external', detail: 'user /stop' });
   
   // Persist to SQLite / JSON / whatever ledger you use
   const data = outcome.toDict();
   // { kind: 'aborted', source: 'external', detail: 'user /stop' }
   
   // Restart, rehydrate
   const restored = RunTerminal.fromDict(data);
   // TS instances are not value-equal (restored !== outcome) — compare toDict() output instead.
   console.assert(JSON.stringify(restored.toDict()) === JSON.stringify(outcome.toDict()));

How It Works

Each observer reports a RunTerminal to merge_run_terminal, which keeps refining one authoritative outcome; collapse projects it to a RunStatus for downstream consumers.

Precedence & Stickiness

merge_run_terminal picks a winner by two rules: a stronger kind always beats a weaker one, and among equal kinds a sticky source beats a non-sticky one.

Kind precedence ladder — a later, weaker observation never overwrites a stronger one.

Sticky sources — a deliberate cancel, a hard run-budget timeout, and a supersede are intentional terminals; once recorded, authoritative.

Configuration Options

RunTerminal is a frozen dataclass (Python) / frozen class (TypeScript). Every field:

The source vocabulary and which sources are sticky (identical for both SDKs):

Full API surface lives in the auto-generated SDK reference for praisonaiagents.run_outcome.

Which source to pick

Pick the source that names the observer that ended the run.

Common Patterns

Gateway race — an idle timeout arrives, then the user cancels; the cancel wins:

from praisonaiagents import RunTerminal, merge_run_terminal, collapse

terminal = None
terminal = merge_run_terminal(terminal, RunTerminal("timeout", "idle"))
terminal = merge_run_terminal(terminal, RunTerminal("aborted", "external"))
print(collapse(terminal))  # 'cancelled' — the user's cancel wins over the idle timeout

import { RunTerminal, mergeRunTerminal, collapse } from 'praisonai';

let terminal: RunTerminal | null = null;
terminal = mergeRunTerminal(terminal, new RunTerminal({ kind: 'timeout', source: 'idle' }));
terminal = mergeRunTerminal(terminal, new RunTerminal({ kind: 'aborted', source: 'external' }));
console.log(collapse(terminal));  // 'cancelled' — the user's cancel wins over the idle timeout

Order-independent merge — the same signals yield the same result regardless of arrival order:

from praisonaiagents import RunTerminal, merge_run_terminal

idle       = RunTerminal("timeout", "idle")
run_budget = RunTerminal("timeout", "run_budget")

forward = merge_run_terminal(merge_run_terminal(None, idle),       run_budget)
reverse = merge_run_terminal(merge_run_terminal(None, run_budget), idle)

assert forward == reverse == run_budget  # sticky run_budget wins either way

import { RunTerminal, mergeRunTerminal } from 'praisonai';

const idle      = new RunTerminal({ kind: 'timeout', source: 'idle' });
const runBudget = new RunTerminal({ kind: 'timeout', source: 'run_budget' });

const forward = mergeRunTerminal(mergeRunTerminal(null, idle),      runBudget);
const reverse = mergeRunTerminal(mergeRunTerminal(null, runBudget), idle);

// Sticky run_budget wins either way — compare toDict() (TS instances aren't value-equal).
console.assert(JSON.stringify(forward.toDict()) === JSON.stringify(reverse.toDict()));
console.assert(forward.source === 'run_budget');

Durable ledger persistence — typed, not a free string:

# Before: record.terminal_outcome = str(reason)          # untyped free string
# After:
record.terminal = merge_run_terminal(record.terminal, observed)  # refine-only
record.status   = collapse(record.terminal)                       # RunStatus for downstream

// Before: record.terminalOutcome = String(reason);       // untyped free string
// After:
record.terminal = mergeRunTerminal(record.terminal, observed);  // refine-only
record.status   = collapse(record.terminal);                    // AgentRunStatus for downstream

Best Practices

Related