@kruntime/komputer 0.1.0

package/dist/agent-session.d.ts

@@ -0,0 +1,303 @@
+import { normalizeInput } from './content.js';
+import { EventLog } from './events.js';
+import { KFileSystem } from './vfs.js';
+import { VProcessTable } from './vprocess.js';
+import { ShellExpander } from './shell/expansion.js';
+import type { Komputer } from './komputer.js';
+import type { ModeInput } from './authority.js';
+import type { AccessScope, EventEnvelope, HookContext, HookDecision, KMessage, ModeName, ModeState, ModelResult, ModelEvent, RuntimeEvent, RuntimeComputerFace, SessionRecord, TraceRecord, Json } from './types.js';
+import type { KStateLease } from './state-backend.js';
+import type { VJobRecord, VProcessRecord } from './vprocess.js';
+import type { ShellExecutionLimits } from './remote.js';
+import type { ApprovalRecord } from './agent/approvals.js';
+import type { ShellOptions } from './shell/runtime.js';
+export { isFinalTurnEvent } from './agent/session-utils.js';
+type EventHandler = (event: RuntimeEvent, envelope: EventEnvelope) => Promise<void> | void;
+type HookHandler = (ctx: HookContext<Record<string, unknown>>) => Promise<HookDecision | void> | HookDecision | void;
+interface AgentSessionInit {
+    computer: Komputer;
+    agentName: string;
+    sessionId: string;
+    mode?: ModeInput;
+    disk?: string;
+}
+export interface SendOptions {
+    by?: string;
+    model?: string;
+    [key: string]: unknown;
+}
+export interface ExecOptions {
+    by?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    foreground?: boolean;
+    remote?: string;
+    limits?: ShellExecutionLimits;
+    signal?: AbortSignal;
+}
+type ExecShellOptions = ExecOptions & {
+    forceRemote?: boolean;
+};
+interface TurnEndPayload {
+    turnId: string;
+    inputId?: string;
+    status: string;
+    text?: string;
+    reason?: string;
+    provider?: Record<string, unknown>;
+}
+export interface ForkOptions {
+    from?: string | Record<string, unknown>;
+    mode?: ModeInput;
+    scope?: AccessScope;
+    disk?: string;
+    hooks?: boolean;
+}
+interface HookRunResult {
+    rejected: boolean;
+    current: Record<string, unknown>;
+    reason?: string;
+    waitingApproval?: boolean;
+    approval?: Record<string, unknown>;
+}
+export interface UploadOptions {
+    by?: string;
+    announce?: boolean;
+}
+export interface DownloadOptions {
+    encoding?: 'utf8';
+}
+export interface AgentSessionStats {
+    sessionId: string;
+    agent: string;
+    mode: ModeName;
+    disk: string;
+    cwd: string;
+    closed: boolean;
+    localEventHandlers: number;
+    localHooks: number;
+    localActiveProcesses: number;
+    shellFunctions: number;
+}
+export interface AgentSessionInitResult {
+    firstLogin: boolean;
+    recovered: boolean;
+}
+export declare class AgentSession {
+    private readonly runtime;
+    computer: RuntimeComputerFace;
+    kstate: Komputer['kstate'];
+    agentName: string;
+    sessionId: string;
+    modeState: ModeState;
+    mode: ModeName;
+    disk: string;
+    definition: {
+        home?: string;
+        model?: string;
+    };
+    home: string;
+    modelAlias: string;
+    system: string;
+    eventLog: EventLog;
+    handlers: Map<string, EventHandler[]>;
+    hooks: Map<string, HookHandler[]>;
+    shellEnv: Record<string, string>;
+    private shellEnvBase?;
+    shellFunctions: Record<string, string>;
+    shellOptions: ShellOptions;
+    private readonly messageLog;
+    private readonly approvalLog;
+    cwd: string;
+    fs: KFileSystem;
+    localComputer: RuntimeComputerFace;
+    vprocess: VProcessTable;
+    shellExpander: ShellExpander;
+    turnStopDepth: number;
+    maxTurnStopContinuations: number;
+    private functionDepth;
+    private sourceDepth;
+    private fsActorStack;
+    lastExitCode: number;
+    closed: boolean;
+    initResult?: AgentSessionInitResult;
+    lease?: KStateLease;
+    leaseHeartbeat?: ReturnType<typeof setInterval>;
+    constructor({ computer, agentName, sessionId, mode, disk }: AgentSessionInit);
+    init(): Promise<this>;
+    private reconcileRecoveredProcessReceipts;
+    private finalizeProcessReceiptFromWait;
+    saveSession(patch: Partial<SessionRecord>): Promise<void>;
+    private saveSessionUnchecked;
+    startLeaseHeartbeat(): void;
+    renewLease(): Promise<void>;
+    private assertWritableSession;
+    private assertActiveLease;
+    private canWriteWithCurrentLease;
+    private normalizeModeForAgent;
+    ready(): Promise<void>;
+    authorizeFs(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    trace(type: string, data?: Record<string, unknown>): Promise<TraceRecord>;
+    private traceFs;
+    private currentFsActor;
+    private withFsActor;
+    emit(event: RuntimeEvent): Promise<EventEnvelope>;
+    events(options?: {
+        since?: number;
+        types?: RuntimeEvent['type'][];
+        signal?: AbortSignal;
+    }): AsyncIterable<EventEnvelope>;
+    on(type: string, handler: EventHandler): () => void;
+    hook(type: string, handler: HookHandler): () => void;
+    hasHooks(type: string): boolean;
+    runHook(type: string, current: Record<string, unknown>): Promise<HookRunResult>;
+    hookContext(type: string, current: Record<string, unknown>): HookContext<Record<string, unknown>>;
+    signal(name: string, data?: unknown, options?: {
+        level?: string;
+    }): Promise<EventEnvelope>;
+    emitApprovalRequest(approval: ApprovalRecord): Promise<void>;
+    decide(approvalId: string, decision: unknown, options?: {
+        by?: string;
+    }): Promise<Record<string, unknown>>;
+    consumeApproval(approval: ApprovalRecord): Promise<void>;
+    resumeApproval(approval: ApprovalRecord): Promise<unknown>;
+    resumeFsApproval(current: Record<string, unknown>): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+    detach(): Promise<void>;
+    /** @internal */
+    abandonStartup(): Promise<void>;
+    private clearRuntimeHandles;
+    private releaseLease;
+    send(input: Parameters<typeof normalizeInput>[0], options?: SendOptions): Promise<Record<string, unknown>>;
+    run(input: Parameters<typeof normalizeInput>[0], options?: SendOptions): Promise<Record<string, unknown>>;
+    queue(inputs: Parameters<typeof normalizeInput>[0][], options?: SendOptions): Promise<Record<string, unknown>[]>;
+    upload(path: string, data: string | Uint8Array | Json, options?: UploadOptions): Promise<Record<string, unknown>>;
+    download(path: string, _options?: DownloadOptions): Promise<{
+        path: string;
+        text: string;
+        bytes: number;
+    }>;
+    nextTurn({ inputId, model }?: {
+        inputId?: string;
+        model?: string;
+    }): Promise<Record<string, unknown>>;
+    consumeModelStream(stream: AsyncIterable<ModelEvent>, { turnId, inputId, emit, }: {
+        turnId: string;
+        inputId?: string;
+        emit: boolean;
+    }): Promise<{
+        result: ModelResult;
+        emitted: boolean;
+    }>;
+    publishModelResult({ turnId, inputId, model, modelTraceSeq, result, emitContent, }: {
+        turnId: string;
+        inputId?: string;
+        model?: string;
+        modelTraceSeq?: number;
+        result: ModelResult;
+        emitContent?: boolean;
+    }): Promise<Record<string, unknown>>;
+    endTurn({ turnId, inputId, status, text, reason, provider }: TurnEndPayload): Promise<Record<string, unknown>>;
+    recordInput(record: Record<string, unknown>): Promise<void>;
+    private nextQueuedInputId;
+    stats(): AgentSessionStats;
+    exec(command: string, options?: ExecOptions): Promise<Record<string, unknown>>;
+    execInternal(command: string, options?: ExecShellOptions): Promise<Record<string, unknown>>;
+    execCommand(command: string | {
+        command: string;
+        argv?: string[];
+        stdin?: string;
+        remote?: string;
+        limits?: ShellExecutionLimits;
+    }, options?: ExecOptions): Promise<Record<string, unknown>>;
+    private appendExecToolExchange;
+    private execShell;
+    private remoteShellSandbox;
+    private hardenReadonlyMountsForRemoteShell;
+    private remoteRealPathsForScope;
+    private remoteDenyWritePaths;
+    private remoteSandboxPath;
+    private requireRealKPath;
+    private isKCommandInvocation;
+    private isKBuiltinInvocation;
+    private isKShellFunctionInvocation;
+    private isKLocalSequence;
+    private resolveKExecutable;
+    private execKLocalSequence;
+    private execBackgroundKLocalSequence;
+    private execKLocalSegment;
+    private execKSubshellFromShell;
+    private execKLocalFunctionProgram;
+    private execShellReturn;
+    private execKLocalControlProgram;
+    private execKLocalControl;
+    private execKCommandFromShell;
+    private execKBuiltinFromShell;
+    private execKShellFunctionFromShell;
+    private execKExecutableFromShell;
+    private failShellCommandBeforeRun;
+    private finalizeBackgroundReceipt;
+    private trackBackgroundReceipt;
+    private runBuiltin;
+    private fetchNetwork;
+    private applyRedirectedStreams;
+    private prepareRedirect;
+    private expandRedirectPath;
+    private assertRedirectTargetWritable;
+    private expandShellArgs;
+    private expandCaseToken;
+    private expandShellEnv;
+    private expandGlobArg;
+    private defaultShellEnv;
+    private effectiveShellEnv;
+    private setShellEnv;
+    private unsetShellEnv;
+    private setShellOptions;
+    private withTemporaryShellState;
+    private shellSessionRecord;
+    private withTemporaryShellEnvKeys;
+    private rememberExit;
+    private normalizeShellSegment;
+    private withTemporaryMode;
+    private emitShellOutput;
+    private boundRuntimeEvent;
+    private boundShellResult;
+    private boundShellReceiptOutput;
+    private applyRedirect;
+    command(name: string, input?: Record<string, unknown>, options?: SendOptions): Promise<unknown>;
+    processes(): Promise<VProcessRecord[]>;
+    jobs(): Promise<VJobRecord[]>;
+    remoteCwd(): string | undefined;
+    hookCwd(): string;
+    shellPath(path: string): string;
+    appendMessage(message: Omit<KMessage, 'seq' | 'at'>): Promise<KMessage>;
+    messagesForModel(): Promise<KMessage[]>;
+    get messages(): {
+        get: (options?: {}) => Promise<{
+            messages: KMessage[];
+            cursor: number;
+            hasMore: boolean;
+        }>;
+        current: (options?: {}) => Promise<{
+            messages: KMessage[];
+            cursor: number;
+            hasMore: boolean;
+        }>;
+        full: (options?: {}) => Promise<{
+            messages: KMessage[];
+            cursor: number;
+            hasMore: boolean;
+        }>;
+        tail: (options?: {}) => AsyncIterable<{
+            cursor: number;
+            message: KMessage;
+        }>;
+    };
+    checkpoint({ label }?: {
+        label?: string;
+    }): Promise<Record<string, unknown>>;
+    fork({ from, mode, scope, disk, hooks }?: ForkOptions): Promise<AgentSession>;
+    sealUnfinishedTools(): Promise<number>;
+    sealUnfinishedToolEvents(): Promise<number>;
+    sealInterruptedTurns(): Promise<number>;
+}