import { AgentDeclaredArtifactAudit } from "std/agent/required_artifacts"
/** Producer-owned classification of an agent-loop terminal. */
pub type AgentTerminalKind = "natural" \
| "user_cancelled" \
| "policy_budget" \
| "completion_unverified" \
| "policy_no_progress" \
| "policy_thrash" \
| "policy_guardrail" \
| "policy_stop" \
| "provider_error" \
| "runtime_error" \
| "suspended" \
| "unknown"
pub type AgentTerminalOwner = "agent" | "user" | "policy" | "provider" | "harness" | "unknown"
pub type AgentTerminalLifecycleState = "completed" \
| "failed" \
| "stopped" \
| "cancelled" \
| "suspended"
pub type AgentTerminalOutcome = {
kind: AgentTerminalKind,
reason: string,
owner: AgentTerminalOwner,
lifecycle_state: AgentTerminalLifecycleState,
run_record_status: AgentTerminalLifecycleState,
}
pub type AgentLlmSummary = {
token_scope: string,
iterations: int,
duration_ms: int,
input_tokens: int,
output_tokens: int,
cache_read_tokens: int,
cache_write_tokens: int,
accounting_status: "reported" | "partial" | "unknown",
known_cost_usd: float,
projected_cost_usd?: float,
unpriced_calls: int,
usage_unknown_calls: int,
...rest,
}
/* Worst case for the run; nil when some call has no bound at all. */
pub type AgentToolSummary = {
calls: list,
successful: list<string>,
rejected: list<string>,
mode: string,
...rest,
}
/** Deterministic recap lifecycle state derived from durable session facts. */
pub type AgentRecapCompletionState = "open" | "complete" | "incomplete" | "unassigned"
pub type AgentRecapToolState = "open" | "completed" | "failed" | "incomplete"
pub type AgentRecapTextFact = {text: string, sourceEventId: int}
pub type AgentRecapVerificationFact = {
schema: string,
status: "passed",
verifiedPaths: list<string>,
sourceEventId: int,
}
pub type AgentRecapToolExchange = {
toolCallId: string,
toolName: string?,
state: AgentRecapToolState,
callObserved: bool,
resultObserved: bool,
input: any,
output: any,
verification: AgentRecapVerificationFact?,
sourceEventIds: list<int>,
}
pub type AgentRecapPlanStepStatus = "pending" \
| "in_progress" \
| "completed" \
| "blocked" \
| "cancelled"
pub type AgentRecapPlanStep = {id: string, content: string, status: AgentRecapPlanStepStatus}
pub type AgentRecapPlanEventKind = "created" | "updated"
pub type AgentRecapPlanEventFact = {
kind: AgentRecapPlanEventKind,
eventId: string,
inputRevisionId: string?,
}
pub type AgentRecapPlanFact = {
documentId: string,
revisionId: string,
title: string,
summary: string,
steps: list<AgentRecapPlanStep>,
event: AgentRecapPlanEventFact?,
sourceEventId: int,
}
pub type AgentRecapProgressStatus = "pending" | "in_progress" | "completed"
pub type AgentRecapProgressPriority = "high" | "medium" | "low"
pub type AgentRecapProgressEntry = {
content: string,
status: AgentRecapProgressStatus,
priority: AgentRecapProgressPriority?,
}
pub type AgentRecapProgressFact = {
message: string?,
entries: list<AgentRecapProgressEntry>,
replace: bool,
sourceEventId: int,
}
pub type AgentRecapTerminalFact = {
state: AgentRecapCompletionState,
finalStatus: string?,
stopReason: string?,
kind: string?,
owner: string?,
reason: string?,
sourceEventId: int,
}
pub type AgentIterationRecap = {
iteration: int?,
state: AgentRecapCompletionState,
assistantText: list<AgentRecapTextFact>,
tools: list<AgentRecapToolExchange>,
plans: list<AgentRecapPlanFact>,
progress: list<AgentRecapProgressFact>,
sourceEventIds: list<int>,
}
pub type AgentPromptTurnRecap = {
turnId: string,
runId: string,
state: AgentRecapCompletionState,
prompts: list<AgentRecapTextFact>,
iterations: list<AgentIterationRecap>,
terminal: AgentRecapTerminalFact?,
sourceEventIds: list<int>,
}
pub type AgentRecapQuery = {
sessionId: string,
runId: string?,
turnId: string?,
fromEventId: int?,
limit: int?,
}
pub type AgentRecapCursor = {lastEventId: int?, nextEventId: int?}
pub type AgentRecapCoverage = {
scanned: int,
matched: int,
pending: int,
unassigned: int,
truncated: bool,
}
pub type AgentRecapSourceEvent = {eventId: int, recordHash: string}
pub type AgentRecapSource = {
firstEventId: int?,
lastEventId: int?,
events: list<AgentRecapSourceEvent>,
}
pub type AgentRecapSnapshot = {
schemaVersion: int,
sessionId: string,
query: AgentRecapQuery,
cursor: AgentRecapCursor,
coverage: AgentRecapCoverage,
source: AgentRecapSource,
contentHash: string,
projectionHash: string,
turns: list<AgentPromptTurnRecap>,
extensions: dict,
}
pub type AgentRecapUnavailableReason = "journal_unavailable" \
| "session_missing" \
| "projection_failed" \
| "admission_terminal"
pub type AgentRecapAvailability = {state: "available", snapshot: AgentRecapSnapshot} \
| {state: "unavailable", reason: AgentRecapUnavailableReason}
/**
* Why the loop judged that a run which reached its own end did not do the work
* (harn#7915).
*
* Present ONLY on a convicted run, so its absence is not a verdict of success;
* it means the rule did not fire. It rides beside `terminal` rather than inside
* it: `terminal.kind` is `completion_unverified` on a convicted run and stays
* the field a host branches on, while `stop_reason` keeps whatever the run
* itself said, verbatim.
*
* `attempted_tool_calls` and `succeeded_tool_calls` are CALL counts. They are
* deliberately not the lengths of `tools.successful` / `tools.rejected`, which
* deduplicate by tool name and answer a different question.
*
* The decision belongs to the agent loop's terminal region, which is the only
* place that holds the evidence. A result obtained from
* `HarnessAgent.session_finalize` directly therefore never carries this field,
* because no loop ran to decide it — not because the run was judged complete.
*
* `AgentResult.declared_artifacts` is the sibling field and is NOT a verdict:
* the declared-artifact audit is published on satisfied runs too, so a caller
* can tell a contract that passed from one that was never checked.
*/
pub type AgentAbandonment = {
cause: "no_tool_call_succeeded" | "required_tool_missing" | "declared_artifact_missing",
natural_stop_reason: string,
attempted_tool_calls: int,
succeeded_tool_calls: int,
last_rejection_category: string?,
}
/**
* Canonical result returned by `agent_loop` and `HarnessAgent.session_finalize`.
*
* `terminal` is the stable decision surface. `final_status`, `stop_reason`,
* and the open raw payloads remain lossless compatibility data for transcripts
* and diagnostics; consumers do not reclassify them. `cost_usd` is exact and
* nil if any call is unpriced; `known_cost_usd` is the priced-call lower bound.
*/
pub type AgentResult = {
status: string,
final_status: string,
stop_reason: string,
acp_stop_reason: string,
terminal_class: string?,
terminal: AgentTerminalOutcome,
abandonment?: AgentAbandonment,
declared_artifacts?: AgentDeclaredArtifactAudit,
error: any,
text: string,
visible_text: string,
private_reasoning: any,
thinking_summary: any,
llm: AgentLlmSummary,
tools: AgentToolSummary,
transcript: any,
recap: AgentRecapAvailability,
trace: any,
tokens_used: int,
cost_usd: float?,
known_cost_usd: float,
unpriced_calls: int,
usage_unknown_calls: int,
provider_call_count: int,
session_id: string,
run_id: string,
started_at: string,
task: string,
daemon_state: any,
daemon_snapshot_path: any,
...rest,
}
/** Exact retained-run receipt for retrying a failed terminal persistence write. */
pub type AgentFinalizationRetry = {
kind: "agent_session_finalize",
session_id: string,
run_id: string,
}
/** Additive error envelope for an agent loop that aborts by throwing. */
pub type AgentLoopTerminalError = {
kind: string,
category: string,
reason: string,
message: string,
cause: unknown,
provider_call_count: int?,
retry: AgentFinalizationRetry?,
...rest,
}
// Nil means the session ledger itself was unavailable. A measured zero is
// always the integer 0, so consumers cannot confuse missing measurement
// with a request that was refused before dispatch.