@sema-agent/client-core 0.101.0 → 0.102.0

package/dist/sessionBackground.d.ts

@@ -0,0 +1,165 @@
+import type { AgentClient, AgentEvent, TaskRequest } from '@sema-agent/sdk';
+import { type EnvLike } from './hostEnv.js';
+import type { UiLanguage } from './env/uiLanguage.js';
+export type SessionBackgroundableReading = {
+    readonly kind: 'advertised';
+} | {
+    readonly kind: 'declined';
+} | {
+    readonly kind: 'not_reported';
+} | {
+    readonly kind: 'unreadable';
+} | {
+    readonly kind: 'unobserved';
+};
+export declare function projectSessionBackgroundable(caps: {} | null | undefined): SessionBackgroundableReading | undefined;
+export declare function readSessionBackgroundable(baseUrl?: string | undefined): SessionBackgroundableReading;
+export type InteractiveEngineLane = 'self-spawned' | 'external';
+export interface InteractiveEngineWireInit {
+    readonly baseUrl: string;
+    readonly lane: InteractiveEngineLane;
+    readonly tasks: Pick<AgentClient['tasks'], 'stream'>;
+    readonly runs: Pick<AgentClient['runs'], 'events' | 'get'>;
+}
+export interface InteractiveEngineWire {
+    readonly baseUrl: string;
+    readonly lane: InteractiveEngineLane;
+}
+type SdkStreamOptions = Parameters<AgentClient['tasks']['stream']>[1];
+type SdkEventsOptions = NonNullable<Parameters<AgentClient['runs']['events']>[1]>;
+type SdkGetOptions = NonNullable<Parameters<AgentClient['runs']['get']>[1]>;
+type SdkRunRecord = Awaited<ReturnType<AgentClient['runs']['get']>>;
+export type OpeningPhase = 'opening' | 'bound' | 'running' | 'ended-unstarted' | 'finished' | 'stream-ended' | 'handing-off' | 'handed-off' | 'engine-ended';
+export interface OpeningRecordView {
+    readonly phase: OpeningPhase;
+    readonly inconsistent: boolean;
+    readonly capsGenAtBind: number | undefined;
+    readonly stopRequested: boolean;
+    readonly stamped: boolean;
+    readonly postureReason: InteractiveDetachPostureReason;
+    readonly proof: 'loopback-self-spawned' | 'none';
+    readonly taskId: string | undefined;
+    readonly sessionId: string | undefined;
+    readonly openAsks: ReadonlyMap<string, number | undefined>;
+    readonly askUnacked: boolean;
+}
+export interface OpeningRecord extends OpeningRecordView {
+    readonly openingId: number;
+    readonly sessionKey: string | undefined;
+    phase: OpeningPhase;
+    inconsistent: boolean;
+    capsGenAtBind: number | undefined;
+    stopRequested: boolean;
+    stamped: boolean;
+    postureReason: InteractiveDetachPostureReason;
+    proof: 'loopback-self-spawned' | 'none';
+    taskId: string | undefined;
+    sessionId: string | undefined;
+    readonly openAsks: Map<string, number | undefined>;
+    askUnacked: boolean;
+    replay: boolean;
+    readonly tear: (reason: string) => void;
+}
+export interface HandedOffEntry {
+    readonly taskId: string;
+    readonly sessionKey: string;
+    state: 'running' | 'ended' | 'unconfirmed';
+    readonly stop: (cause: 'disposed' | 'engine-ended') => void;
+    readonly reconcile: () => void;
+}
+export interface WireState {
+    retired: boolean;
+    readonly baseUrl: string;
+    readonly lane: InteractiveEngineLane;
+    readonly stream: (req: TaskRequest, opts: SdkStreamOptions) => AsyncGenerator<AgentEvent>;
+    readonly events: (taskId: string, opts: SdkEventsOptions) => AsyncGenerator<AgentEvent>;
+    readonly get: (taskId: string, opts: SdkGetOptions) => Promise<SdkRunRecord>;
+    readonly bySession: Map<string, OpeningRecord>;
+    readonly byTask: Map<string, OpeningRecord>;
+    readonly order: OpeningRecord[];
+    readonly handedOff: Map<string, HandedOffEntry>;
+    nextOpeningId: number;
+}
+export declare const OPENING_RECORD_CAP = 256;
+export type OwnSlot = {
+    readonly state: 'absent';
+} | {
+    readonly state: 'unreadable';
+} | {
+    readonly state: 'data';
+    readonly value: {} | null;
+};
+export declare function ownSlotOf(o: object, key: string): OwnSlot;
+export declare function wireStateOf(wire: InteractiveEngineWire | null | undefined): WireState | undefined;
+export declare function interactiveEngineWire(init: InteractiveEngineWireInit): InteractiveEngineWire | undefined;
+export declare function retireInteractiveEngineWire(wire: InteractiveEngineWire): void;
+export interface InteractiveOpeningInput {
+    readonly sessionKey: string;
+    readonly reattachable: boolean;
+    readonly env?: EnvLike;
+}
+export type InteractiveDetachPostureReason = 'self-spawned' | 'unreadable-input' | 'retired-wire' | 'env-off' | 'not-reattachable' | 'declined' | 'unacknowledged' | 'not_reported' | 'unobserved' | 'unreadable' | 'durable-off-400';
+export interface InteractiveDetachPosture {
+    readonly stamp: boolean;
+    readonly reason: InteractiveDetachPostureReason;
+}
+export declare function interactiveDetachPosture(wire: InteractiveEngineWire, input: InteractiveOpeningInput): InteractiveDetachPosture;
+export type InteractiveStreamOptions = {
+    transientOk: true;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    onResponse?: (res: Response) => void;
+    idempotencyKey?: string | null;
+    heartbeatGraceMs?: number;
+};
+export declare function streamInteractiveRun(wire: InteractiveEngineWire, req: TaskRequest, opts: InteractiveStreamOptions, input: InteractiveOpeningInput): AsyncGenerator<AgentEvent>;
+export type BackgroundHandoffVerdict = {
+    readonly verdict: 'eligible';
+    readonly taskId: string;
+} | {
+    readonly verdict: 'ineligible';
+    readonly reason: BackgroundHandoffRefusal;
+    readonly cause?: InteractiveDetachPostureReason;
+} | {
+    readonly verdict: 'unknown';
+    readonly reason: BackgroundHandoffUnknown;
+};
+export type BackgroundHandoffRefusal = 'no-run' | 'stream-ended' | 'already-handed-off' | 'finished' | 'engine-replaced' | 'stopping' | 'not-stamped' | 'declined' | 'not-started' | 'awaiting-user';
+export type BackgroundHandoffUnknown = 'unreadable-input' | 'capability-unconfirmed' | 'detach-unconfirmed' | 'awaiting-user-unattributable';
+export interface HoldOwnerView {
+    readonly taskId: string | undefined;
+    readonly sessionId: string | undefined;
+}
+export interface HandoffJudgeFacts {
+    readonly inputReadable: boolean;
+    readonly wirePresent: boolean;
+    readonly wireRecognized: boolean;
+    readonly rec: OpeningRecordView | undefined;
+    readonly capability: SessionBackgroundableReading['kind'];
+    readonly capsGenerationNow: number | undefined;
+    readonly holds: readonly HoldOwnerView[];
+    readonly nowMs: number;
+}
+export declare function handoffVerdictOf(f: HandoffJudgeFacts): BackgroundHandoffVerdict;
+export interface HandoffJudgeInput {
+    readonly wire: InteractiveEngineWire | undefined;
+    readonly sessionKey: string;
+}
+export interface JudgedHandoff {
+    readonly verdict: BackgroundHandoffVerdict;
+    readonly rec: OpeningRecord | undefined;
+    readonly state: WireState | undefined;
+}
+export declare function judgeHandoff(input: HandoffJudgeInput | null | undefined): JudgedHandoff;
+export declare function backgroundHandoffEligibility(input: {
+    readonly wire: InteractiveEngineWire | undefined;
+    readonly sessionKey: string;
+}): BackgroundHandoffVerdict;
+export declare function backgroundHandoffSentence(v: BackgroundHandoffVerdict, lang?: UiLanguage): string | undefined;
+export interface InteractiveStopFacts {
+    readonly detachArmed: boolean;
+    readonly handedOff: boolean;
+}
+export declare function interactiveStopFacts(wire: InteractiveEngineWire | undefined, taskId: string): InteractiveStopFacts;
+export declare function noteInteractiveStopRequested(wire: InteractiveEngineWire, taskId: string): 'withheld' | 'proceed';
+export {};