praxis-agent 0.34.0 → 0.36.0

package/dist/core/agent-orchestration.js

@@ -0,0 +1,235 @@
+/** Provider- and persistence-independent lifecycle contract for one Agent. */
+export const TERMINAL_LIFECYCLE_STATES = [
+    'completed',
+    'failed',
+    'cancelled',
+    'orphaned',
+];
+const transitions = {
+    queued: ['running', 'cancelling', 'failed'],
+    running: ['waiting', 'completed', 'failed', 'cancelling'],
+    waiting: ['running', 'completed', 'failed', 'cancelling'],
+    cancelling: ['cancelled'],
+    completed: [],
+    failed: [],
+    cancelled: [],
+    orphaned: [],
+};
+export function isTerminalLifecycleState(state) {
+    return TERMINAL_LIFECYCLE_STATES.includes(state);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseOwner(value) {
+    if (!isRecord(value))
+        throw new Error('Invalid lifecycle owner');
+    const owner = value;
+    const token = owner.token;
+    const pid = owner.pid;
+    const acquiredAt = owner.acquiredAt;
+    if (typeof token !== 'string' ||
+        token.trim().length === 0 ||
+        !Number.isSafeInteger(pid) ||
+        Number(pid) <= 0 ||
+        typeof acquiredAt !== 'string' ||
+        Number.isNaN(Date.parse(acquiredAt))) {
+        throw new Error('Invalid lifecycle owner');
+    }
+    return Object.freeze({
+        token: token,
+        pid: pid,
+        acquiredAt: acquiredAt,
+    });
+}
+/** The single invariant parser used by every lifecycle mutation and store. */
+export function parseAgentLifecycleSnapshot(value) {
+    if (!isRecord(value))
+        throw new Error('Invalid lifecycle snapshot');
+    const generation = value.generation;
+    const revision = value.revision;
+    const state = value.state;
+    const previousOwnerToken = value.previousOwnerToken;
+    const acceptance = value.acceptance;
+    const terminalAt = value.terminalAt;
+    if (!Number.isSafeInteger(generation) || Number(generation) <= 0) {
+        throw new Error('Lifecycle generation must be a positive integer');
+    }
+    if (!Number.isSafeInteger(revision) || Number(revision) < 0) {
+        throw new Error('Lifecycle revision must be a nonnegative integer');
+    }
+    if (![
+        'queued',
+        'running',
+        'waiting',
+        'completed',
+        'failed',
+        'cancelling',
+        'cancelled',
+        'orphaned',
+    ].includes(String(state))) {
+        throw new Error(`Invalid lifecycle state: ${String(value.state)}`);
+    }
+    if (previousOwnerToken !== null &&
+        (typeof previousOwnerToken !== 'string' ||
+            previousOwnerToken.trim().length === 0)) {
+        throw new Error('Invalid previous lifecycle owner token');
+    }
+    if (!['pending', 'accepted', 'rejected'].includes(String(acceptance))) {
+        throw new Error('Invalid lifecycle acceptance');
+    }
+    if (isTerminalLifecycleState(state)) {
+        if (value.owner !== null || terminalAt === null) {
+            throw new Error('Terminal lifecycle must be ownerless and timestamped');
+        }
+        if (typeof terminalAt !== 'string' ||
+            Number.isNaN(Date.parse(terminalAt))) {
+            throw new Error('Invalid lifecycle terminal timestamp');
+        }
+        if (acceptance !== 'pending' && state !== 'completed') {
+            throw new Error('Only completed lifecycle may be accepted or rejected');
+        }
+    }
+    else if (value.owner === null ||
+        terminalAt !== null ||
+        acceptance !== 'pending') {
+        throw new Error('Nonterminal lifecycle must be owned, pending, and untimestamped');
+    }
+    const owner = value.owner === null ? null : parseOwner(value.owner);
+    return Object.freeze({
+        generation: generation,
+        revision: revision,
+        state: state,
+        owner,
+        previousOwnerToken: previousOwnerToken,
+        terminalAt: terminalAt,
+        acceptance: acceptance,
+    });
+}
+export function createAgentLifecycle(owner, generation = 1) {
+    parseOwner(owner);
+    return parseAgentLifecycleSnapshot({
+        generation,
+        revision: 0,
+        state: 'queued',
+        owner,
+        previousOwnerToken: null,
+        terminalAt: null,
+        acceptance: 'pending',
+    });
+}
+function requireCurrentOwner(current, token) {
+    if (current.owner === null || current.owner.token !== token) {
+        throw new Error('Lifecycle execution owner token is stale or missing');
+    }
+}
+export function transitionLifecycle(current, nextState, ownerToken, terminalAt = new Date().toISOString()) {
+    parseAgentLifecycleSnapshot(current);
+    requireCurrentOwner(current, ownerToken);
+    if (!transitions[current.state].includes(nextState)) {
+        throw new Error(`Illegal lifecycle transition: ${current.state} -> ${nextState}`);
+    }
+    const terminal = isTerminalLifecycleState(nextState);
+    if (terminal && Number.isNaN(Date.parse(terminalAt))) {
+        throw new Error('Invalid lifecycle terminal timestamp');
+    }
+    return parseAgentLifecycleSnapshot({
+        generation: current.generation,
+        revision: current.revision + 1,
+        state: nextState,
+        owner: terminal ? null : current.owner,
+        previousOwnerToken: terminal
+            ? (current.owner?.token ?? null)
+            : current.previousOwnerToken,
+        terminalAt: terminal ? terminalAt : null,
+        acceptance: 'pending',
+    });
+}
+function requireFreshOwner(current, owner) {
+    parseOwner(owner);
+    if (owner.token === current.previousOwnerToken) {
+        throw new Error('Lifecycle generation requires a fresh owner token');
+    }
+}
+/** Rotate a queued execution owner during a planned parent-to-worker handoff. */
+export function transferLifecycleOwner(current, currentOwnerToken, nextOwner) {
+    parseAgentLifecycleSnapshot(current);
+    requireCurrentOwner(current, currentOwnerToken);
+    if (current.state !== 'queued') {
+        throw new Error(`Cannot transfer lifecycle owner from ${current.state}`);
+    }
+    parseOwner(nextOwner);
+    if (nextOwner.token === currentOwnerToken) {
+        throw new Error('Lifecycle handoff requires a different owner token');
+    }
+    requireFreshOwner(current, nextOwner);
+    return parseAgentLifecycleSnapshot({
+        ...current,
+        revision: current.revision + 1,
+        owner: nextOwner,
+        previousOwnerToken: currentOwnerToken,
+    });
+}
+export function continueLifecycle(current, owner) {
+    parseAgentLifecycleSnapshot(current);
+    if (!['completed', 'failed', 'cancelled'].includes(current.state)) {
+        throw new Error(`Cannot continue lifecycle from ${current.state}`);
+    }
+    requireFreshOwner(current, owner);
+    return parseAgentLifecycleSnapshot({
+        generation: current.generation + 1,
+        revision: current.revision + 1,
+        state: 'queued',
+        owner,
+        previousOwnerToken: current.previousOwnerToken,
+        terminalAt: null,
+        acceptance: 'pending',
+    });
+}
+export function recoverLifecycle(current, owner) {
+    parseAgentLifecycleSnapshot(current);
+    if (current.state !== 'orphaned') {
+        throw new Error(`Cannot recover lifecycle from ${current.state}`);
+    }
+    requireFreshOwner(current, owner);
+    return parseAgentLifecycleSnapshot({
+        generation: current.generation + 1,
+        revision: current.revision + 1,
+        state: 'queued',
+        owner,
+        previousOwnerToken: current.previousOwnerToken,
+        terminalAt: null,
+        acceptance: 'pending',
+    });
+}
+/** Adapter-proven owner loss is intentionally separate from ordinary transitions. */
+export function markLifecycleOrphaned(current, ownerToken, terminalAt = new Date().toISOString()) {
+    parseAgentLifecycleSnapshot(current);
+    requireCurrentOwner(current, ownerToken);
+    if (!['queued', 'running', 'waiting', 'cancelling'].includes(current.state)) {
+        throw new Error(`Cannot orphan lifecycle from ${current.state}`);
+    }
+    if (Number.isNaN(Date.parse(terminalAt)))
+        throw new Error('Invalid lifecycle terminal timestamp');
+    return parseAgentLifecycleSnapshot({
+        generation: current.generation,
+        revision: current.revision + 1,
+        state: 'orphaned',
+        owner: null,
+        previousOwnerToken: ownerToken,
+        terminalAt,
+        acceptance: 'pending',
+    });
+}
+export function acceptLifecycle(current, generation = current.generation, acceptance = 'accepted') {
+    parseAgentLifecycleSnapshot(current);
+    if (current.state !== 'completed' || generation !== current.generation) {
+        throw new Error('Only the completed current generation may be accepted');
+    }
+    return parseAgentLifecycleSnapshot({
+        ...current,
+        revision: current.revision + 1,
+        acceptance,
+    });
+}
+//# sourceMappingURL=agent-orchestration.js.map

package/dist/core/context.d.ts

@@ -1,20 +1,36 @@
 import type { ModelMessage } from './runtime.js';
-import type { PromptCompositionMode, PromptSection } from './prompt-composer.js';
 export type SystemContextMessage = Extract<ModelMessage, {
     role: 'system';
 }>;
-export interface AssembledContext {
+export type ContextSectionStability = 'static' | 'session' | 'volatile';
+export type ContextSectionPlacement = 'system' | 'first-user';
+export type ContextCompositionMode = 'default' | 'custom' | 'bare' | 'agent' | 'subagent';
+export interface ContextSection {
+    id: string;
+    content: string;
+    placement: ContextSectionPlacement;
+    stability: ContextSectionStability;
+}
+export interface ContextSnapshot {
+    sections: readonly ContextSection[];
+}
+export interface ContextProjection {
     systemMessages: readonly SystemContextMessage[];
     firstUserMessageContext?: string;
-    promptSections?: readonly PromptSection[];
-    stableSystemSectionCount?: number;
+    stableSystemSectionCount: number;
+}
+export interface TurnContextInputs {
+    planMode?: string;
+    sessionMemory?: string;
+    briefOutput?: boolean;
+    structuredOutput?: boolean;
 }
 export interface ContextAssemblyOptions {
     cwd?: string;
     lifecycleId?: string;
-    mode?: PromptCompositionMode;
+    mode?: ContextCompositionMode;
     baseSystemPrompt?: string;
-    additionalSections?: readonly PromptSection[];
+    turn?: TurnContextInputs;
 }
 export type ContextInvalidationReason = 'clear' | 'compact' | 'fork' | 'resource-reload' | 'restore' | 'tool-pool' | 'cwd' | 'worktree';
 export interface ContextInvalidationOptions {
@@ -22,8 +38,10 @@ export interface ContextInvalidationOptions {
     reason: ContextInvalidationReason;
 }
 export interface ContextAssembler {
-    assemble(options?: ContextAssemblyOptions): Promise<AssembledContext>;
+    assemble(options?: ContextAssemblyOptions): Promise<ContextSnapshot>;
     invalidate?(options: ContextInvalidationOptions): void;
 }
+export declare function createContextSnapshot(sections: readonly ContextSection[]): ContextSnapshot;
+export declare function projectContextSnapshot(snapshot: ContextSnapshot): ContextProjection;
 export declare function injectFirstUserMessageContext(messages: readonly ModelMessage[], context: string | undefined): ModelMessage[];
 //# sourceMappingURL=context.d.ts.map

package/dist/core/context.js

@@ -1,3 +1,49 @@
+function validateContextSections(sections) {
+    const identities = new Set();
+    let volatileSystemSeen = false;
+    for (const section of sections) {
+        if (!section.id.trim())
+            throw new Error('Context section id is required');
+        if (!section.content.trim()) {
+            throw new Error(`Context section ${section.id} content is required`);
+        }
+        if (identities.has(section.id)) {
+            throw new Error(`Duplicate context section ${section.id}`);
+        }
+        identities.add(section.id);
+        if (section.placement === 'system') {
+            if (section.stability === 'volatile')
+                volatileSystemSeen = true;
+            else if (volatileSystemSeen) {
+                throw new Error('Non-volatile system sections cannot follow volatile sections');
+            }
+        }
+    }
+}
+export function createContextSnapshot(sections) {
+    validateContextSections(sections);
+    return { sections: sections.map((section) => ({ ...section })) };
+}
+export function projectContextSnapshot(snapshot) {
+    const sections = snapshot.sections;
+    validateContextSections(sections);
+    const systemSections = sections.filter((section) => section.placement === 'system');
+    const firstVolatileSystemIndex = systemSections.findIndex((section) => section.stability === 'volatile');
+    const firstUserMessageContext = sections
+        .filter((section) => section.placement === 'first-user')
+        .map((section) => section.content)
+        .join('\n\n');
+    return {
+        systemMessages: systemSections.map((section) => ({
+            role: 'system',
+            content: section.content,
+        })),
+        stableSystemSectionCount: firstVolatileSystemIndex < 0
+            ? systemSections.length
+            : firstVolatileSystemIndex,
+        ...(firstUserMessageContext ? { firstUserMessageContext } : {}),
+    };
+}
 export function injectFirstUserMessageContext(messages, context) {
     if (context === undefined)
         return [...messages];

package/dist/core/prompt-composer.d.ts

@@ -1,27 +1,19 @@
-import type { SystemContextMessage } from './context.js';
-export type PromptSectionStability = 'static' | 'session' | 'volatile';
-export type PromptSectionPlacement = 'system' | 'first-user';
-export type PromptCompositionMode = 'default' | 'custom' | 'bare' | 'agent' | 'subagent';
-export interface PromptSection {
-    id: string;
-    content: string;
-    stability: PromptSectionStability;
-    placement: PromptSectionPlacement;
-}
-export interface PromptComposition {
-    sections: readonly PromptSection[];
-    systemMessages: readonly SystemContextMessage[];
-    firstUserMessageContext?: string;
-    stableSystemSectionCount: number;
-}
+import { type ContextAssembler, type ContextAssemblyOptions, type ContextCompositionMode, type ContextSection, type ContextSnapshot, type TurnContextInputs } from './context.js';
+export type PromptSectionStability = ContextSection['stability'];
+export type PromptSectionPlacement = ContextSection['placement'];
+export type PromptCompositionMode = ContextCompositionMode;
+export type PromptSection = ContextSection;
+export type PromptComposition = ContextSnapshot;
 export interface PromptCompositionOptions {
     mode: PromptCompositionMode;
     baseSystemPrompt?: string;
     appendSystemPrompt?: string;
     sessionSections?: readonly PromptSection[];
     tailSections?: readonly PromptSection[];
+    turn?: TurnContextInputs;
 }
 export declare class PromptComposer {
     compose(options: PromptCompositionOptions): PromptComposition;
 }
+export declare function assembleContextSnapshot(assembler: ContextAssembler | undefined, options?: ContextAssemblyOptions): Promise<ContextSnapshot>;
 //# sourceMappingURL=prompt-composer.d.ts.map

package/dist/core/prompt-composer.js

@@ -1,3 +1,4 @@
+import { createContextSnapshot, } from './context.js';
 const PRODUCT_POLICY = `# Praxis
 
 You are Praxis, a local CLI coding agent. Work until the user's request is genuinely handled or a concrete blocker requires their input.
@@ -9,6 +10,8 @@ You are Praxis, a local CLI coding agent. Work until the user's request is genui
 - Summarize or clear bulky intermediate results once their useful facts have been retained.
 - Treat the context window as bounded: preserve decisions and evidence before reducing detail.
 - Keep responses concise and use the user's language unless they request otherwise.`;
+const BRIEF_OUTPUT_POLICY = 'When brief mode is enabled, SendUserMessage is the primary user-visible reply channel. Use it for the answer, progress checkpoints, and blockers. Set status to normal for a direct reply and proactive for an unsolicited update.';
+const STRUCTURED_OUTPUT_POLICY = 'You MUST call StructuredOutput exactly once at the end with a value matching the requested JSON Schema.';
 function baseSection(mode, content) {
     if (mode === 'bare')
         return undefined;
@@ -51,6 +54,52 @@ function normalizedSections(sections, group) {
         return { ...section };
     });
 }
+function turnSections(turn) {
+    if (!turn)
+        return [];
+    return [
+        ...(turn.planMode?.trim()
+            ? [
+                {
+                    id: 'plan-mode',
+                    content: turn.planMode,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+        ...(turn.sessionMemory?.trim()
+            ? [
+                {
+                    id: 'session-memory',
+                    content: turn.sessionMemory,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+        ...(turn.briefOutput
+            ? [
+                {
+                    id: 'brief-output',
+                    content: BRIEF_OUTPUT_POLICY,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+        ...(turn.structuredOutput
+            ? [
+                {
+                    id: 'structured-output',
+                    content: STRUCTURED_OUTPUT_POLICY,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+    ];
+}
 export class PromptComposer {
     compose(options) {
         const base = baseSection(options.mode, options.baseSystemPrompt);
@@ -63,37 +112,28 @@ export class PromptComposer {
                 stability: 'session',
             }
             : undefined;
-        const tailSections = normalizedSections(options.tailSections ?? [], 'tailSections');
+        const tailSections = normalizedSections([...(options.tailSections ?? []), ...turnSections(options.turn)], 'tailSections');
         const sections = [
             ...(base ? [base] : []),
             ...sessionSections,
             ...(append ? [append] : []),
             ...tailSections,
         ];
-        const identities = new Set();
-        for (const section of sections) {
-            if (identities.has(section.id)) {
-                throw new Error(`Duplicate prompt section ${section.id}`);
-            }
-            identities.add(section.id);
-        }
-        const systemSections = sections.filter((section) => section.placement === 'system');
-        const firstVolatileSystemIndex = systemSections.findIndex((section) => section.stability === 'volatile');
-        const firstUserMessageContext = sections
-            .filter((section) => section.placement === 'first-user')
-            .map((section) => section.content)
-            .join('\n\n');
-        return {
-            sections,
-            systemMessages: systemSections.map((section) => ({
-                role: 'system',
-                content: section.content,
-            })),
-            stableSystemSectionCount: firstVolatileSystemIndex < 0
-                ? systemSections.length
-                : firstVolatileSystemIndex,
-            ...(firstUserMessageContext ? { firstUserMessageContext } : {}),
-        };
+        return createContextSnapshot(sections);
     }
 }
+const defaultContextAssembler = {
+    async assemble(options = {}) {
+        return new PromptComposer().compose({
+            mode: options.mode ?? 'bare',
+            ...(options.baseSystemPrompt === undefined
+                ? {}
+                : { baseSystemPrompt: options.baseSystemPrompt }),
+            ...(options.turn === undefined ? {} : { turn: options.turn }),
+        });
+    },
+};
+export async function assembleContextSnapshot(assembler, options = {}) {
+    return (assembler ?? defaultContextAssembler).assemble(options);
+}
 //# sourceMappingURL=prompt-composer.js.map

package/dist/core/resources.d.ts

@@ -0,0 +1,39 @@
+export type ResourceScope = 'local' | 'project' | 'user';
+export interface TextResource {
+    path: string;
+    scope: ResourceScope;
+    content: string;
+    importedFrom?: string;
+    importRoot?: string;
+}
+export interface JsonResource {
+    path: string;
+    scope: ResourceScope;
+    value: unknown;
+    plugin?: true;
+    pluginName?: string;
+    pluginSource?: string;
+    environment?: Readonly<Record<string, string>>;
+    sensitiveValues?: readonly string[];
+}
+export interface ContextResources {
+    instructions: TextResource[];
+    conditionalRules: ConditionalRule[];
+    memoryIndex: TextResource | null;
+}
+export interface ConditionalRule extends TextResource {
+    baseDirectory: string;
+    content: string;
+    globs: string[];
+    rawContent: string;
+}
+export interface SharedResources {
+    instructions: TextResource[];
+    memory: TextResource[];
+    skills: TextResource[];
+    commands: TextResource[];
+    agents: TextResource[];
+    settings: JsonResource[];
+    mcp: JsonResource[];
+}
+//# sourceMappingURL=resources.d.ts.map

package/dist/core/resources.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resources.js.map

package/dist/core/runtime.d.ts

@@ -151,7 +151,7 @@ export interface ModelProvider {
 }
 export type RuntimeEvent = {
     type: 'state';
-    state: Exclude<RuntimeState, 'idle' | 'failed'>;
+    state: Exclude<RuntimeState, 'idle'>;
 } | {
     type: 'text-delta';
     delta: string;
@@ -419,6 +419,11 @@ export declare function permissionDecisionSource(decision: PermissionDecision):
 export declare function annotateAutoModePermissionOutcome<T extends PermissionDecision>(decision: T, outcome: AutoModePermissionOutcome): T;
 export declare function autoModePermissionOutcome(decision: PermissionDecision): AutoModePermissionOutcome | undefined;
 export interface AgentRunObserver {
+    modelRequestCompleted?(input: {
+        usage: ModelUsage;
+        messages: readonly ModelMessage[];
+        tools: readonly ModelToolDefinition[];
+    }): Promise<void>;
     assistantCompleted(message: {
         content: string;
         thinkingBlocks?: readonly ModelThinkingBlock[];

package/dist/core/runtime.js

@@ -368,6 +368,7 @@ export class AgentRuntime {
                 let textBytes = 0;
                 const thinkingBlocks = [];
                 let turnUsage = emptyUsage();
+                let turnUsageSeen = false;
                 let streaming = false;
                 const toolCalls = [];
                 let terminalReason;
@@ -477,9 +478,10 @@ export class AgentRuntime {
                             terminalReason = event.reason;
                             this.emit(event);
                         }
-                        else {
+                        else if (event.type === 'usage') {
                             activeAttemptHasPresentation = true;
                             turnUsage = event.usage;
+                            turnUsageSeen = true;
                             this.emit(event);
                         }
                     }
@@ -528,6 +530,18 @@ export class AgentRuntime {
                     toolCalls.length > 0) {
                     return failScheduledTurn(new ModelProviderError(`Provider reported ${terminalReason} with completed tool calls`, { retryable: false }));
                 }
+                if (turnUsageSeen) {
+                    try {
+                        await request.observer?.modelRequestCompleted?.({
+                            usage: turnUsage,
+                            messages: providerRequest.messages,
+                            tools: definitions,
+                        });
+                    }
+                    catch (error) {
+                        return failScheduledTurn(error);
+                    }
+                }
                 if (request.collectMetrics) {
                     const turnApiDurationWithoutRetriesMsResolved = turnApiDurationWithoutRetriesMs ?? turnApiDurationMs;
                     durationApiWithoutRetriesMs = addApiDurationMetric(turnApiDurationWithoutRetriesMsResolved, durationApiWithoutRetriesMs, 'durationApiWithoutRetriesMs');

package/dist/core/session.d.ts

@@ -0,0 +1,2 @@
+export declare function isSessionId(value: string): boolean;
+//# sourceMappingURL=session.d.ts.map

package/dist/core/session.js

@@ -0,0 +1,5 @@
+const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isSessionId(value) {
+    return SESSION_ID_PATTERN.test(value);
+}
+//# sourceMappingURL=session.js.map

package/dist/core/transcript-codec.d.ts

@@ -0,0 +1,70 @@
+import type { TranscriptEvent } from './transcript-event.js';
+export type TranscriptCodecDiagnostic = {
+    kind: 'unsupported-version';
+    lineNumber: number | null;
+    byteOffset: number;
+    message: string;
+    schemaVersion: string | number;
+} | {
+    kind: 'corrupt-line';
+    lineNumber: number | null;
+    byteOffset: number;
+    message: string;
+    schemaVersion?: string | number;
+} | {
+    kind: 'unsupported-event';
+    lineNumber: number | null;
+    byteOffset: number;
+    message: string;
+    eventKind?: string;
+};
+export interface OpaquePreservationToken {
+    readonly __opaqueToken: unique symbol;
+}
+type TokenPayload = {
+    owner: symbol;
+    raw: string;
+    eventFingerprint: string;
+};
+export type PreservationTokenSource = {
+    owner: symbol;
+    raw: string;
+    event: TranscriptEvent;
+};
+export declare function createPreservationToken(owner: symbol, source: PreservationTokenSource): OpaquePreservationToken;
+export declare function readPreservationToken(token: OpaquePreservationToken, owner: symbol): TokenPayload | null;
+export interface DecodedTranscriptRecord {
+    readonly event: TranscriptEvent;
+    readonly preservation?: OpaquePreservationToken;
+}
+export type TranscriptLineResult = {
+    ok: true;
+    record: DecodedTranscriptRecord;
+} | {
+    ok: false;
+    issue: TranscriptCodecDiagnostic;
+};
+export type TranscriptEncodeResult = {
+    ok: true;
+    line: string;
+} | {
+    ok: false;
+    issue: TranscriptCodecDiagnostic;
+};
+export interface TranscriptDocumentResult {
+    readonly records: readonly DecodedTranscriptRecord[];
+    readonly issue: TranscriptCodecDiagnostic | null;
+    readonly validPrefixByteLength: number;
+}
+export interface TranscriptCodec {
+    readonly id: string;
+    readonly version: string | number;
+    readonly writeMode: 'read-only' | 'read-write';
+    decodeLine(line: string, lineNumber?: number, byteOffset?: number): TranscriptLineResult;
+    encodeLine(event: TranscriptEvent, preservation?: OpaquePreservationToken): TranscriptEncodeResult;
+    decodeDocument(source: string | Uint8Array): TranscriptDocumentResult;
+}
+export declare function diagnostic(kind: TranscriptCodecDiagnostic['kind'], message: string, byteOffset: number, lineNumber: number | null, extra?: Partial<TranscriptCodecDiagnostic>): TranscriptCodecDiagnostic;
+export declare function decodeDocumentWith(codec: TranscriptCodec, source: string | Uint8Array): TranscriptDocumentResult;
+export {};
+//# sourceMappingURL=transcript-codec.d.ts.map