@struktoai/mirage-core/dist/policy/decisions.d.ts

A Unified Virtual Filesystem For AI Agents

import { type Caller } from '../context/session_context.ts';
import type { Refusal } from '../types.ts';
import { DecisionOwner, Outcome } from './types.ts';
import type { Abandoned, Ask, Claimant, CommandContext, CommandRule, Decision, Deny, ExecuteResultContext, HandOff, NetworkContext, Occurrence, VfsContext, Pending, SessionContext, SessionDecisionsQuery } from './types.ts';
import { Scope } from './types.ts';
import type { RouteContext } from './types.ts';
/**
 * A host that answers an Ask inside the line.
 *
 * `signal` is the run's, so a host that puts a question to a person can
 * take its prompt down when the run it belongs to is killed. Ignoring it
 * is safe: the ledger stops waiting on the handler either way.
 */
export type AskHandler = (record: Decision, signal?: AbortSignal) => Promise<Decision | null>;
/**
 * The id a record is named by: a digest of what was asked, so a retry
 * of the same line quotes the same id and a host answers it once.
 *
 * The id names the record; it does not decide what a retry matches.
 * That comparison is made against the recorded fields themselves
 * (`covers`), so a line the digest cannot tell apart from another still
 * cannot borrow its answer.
 */
export declare function decisionId(sessionId: string, cwd: string, argv: readonly string[]): Promise<string>;
/**
 * The rule an Ask is keyed on: the document's, or for a coded Ask one
 * synthesized over what was asked about (the program, the path, the
 * line, the variable), so a session answer reads "stop asking me about
 * this".
 */
export declare function askRule(ctx: CommandContext | RouteContext | VfsContext | ExecuteResultContext | SessionContext | NetworkContext, ask: Ask): CommandRule;
export declare function sameRule(a: CommandRule, b: CommandRule): boolean;
export declare function covers(record: Decision, rule: CommandRule, argv: readonly string[], cwd: string): boolean;
export declare function lineage(handed: HandOff | null): HandOff[];
export declare function sameOccurrence(a: Occurrence | null, b: Occurrence | null): boolean;
export declare function isPending(refusal: Refusal | null | undefined): boolean;
export declare function opQuestion(ctx: VfsContext | SessionContext | RouteContext | ExecuteResultContext, ask: Ask): [CommandContext, Ask];
export declare function encloses(scope: Occurrence, occurrence: Occurrence): boolean;
export declare class Decisions extends DecisionOwner {
    private readonly sessions;
    private readonly onAsk;
    private readonly memory;
    private readonly live;
    constructor(sessions?: SessionDecisionsQuery | null, onAsk?: AskHandler | null);
    /** Every record, oldest first: questions waiting and questions settled. */
    list(sessionId?: string): Decision[];
    pending(sessionId?: string): Decision[];
    answer(decisionId: string, outcome: Outcome, scope?: Scope, note?: string): Promise<void>;
    private writeAnswer;
    resolve(ctx: CommandContext, ask: Ask, signal?: AbortSignal, claimant?: Claimant | null): Promise<Deny | Pending | Abandoned | null>;
    private claim;
    resolveOp(ctx: VfsContext | SessionContext, ask: Ask, caller?: Caller): Promise<Deny | Pending | null>;
    heldOp(ctx: VfsContext | SessionContext, ask: Ask): Promise<Deny | Pending | null>;
    withinCall<T>(sessionId: string, run: (handed: HandOff) => Promise<T>): Promise<T>;
    revoke(sessionId: string, handed: HandOff): Promise<void>;
    split(sessionId: string, handed: HandOff, scope: Occurrence): HandOff;
    handUp(sessionId: string, handed: HandOff): void;
    release(sessionId: string, handed: HandOff): void;
    held(ctx: CommandContext, ask: Ask, claimant?: Claimant | null): Promise<Deny | Pending | null>;
    private raise;
    private waiting;
    private spend;
    private keys;
    private plan;
    private applyClaim;
    private records;
    private set;
    private add;
    private flush;
}
/**
 * Run one call, the unit an op-level answer covers: a file tool's, or a
 * line's or a job's, whose session writes are its ops. A grant one of its
 * ops is answered by is claimed on `handed` for the call's other ops on
 * that subject. `owner` is the ledger
 * the call runs under, the only one that claims on `handed` and spends
 * it. Mirrors Python's `set_op_call`.
 */
export declare function runWithOpCall<T>(owner: Decisions, handed: HandOff, sessionId: string, fn: () => Promise<T>): Promise<T>;
/**
 * The call running in this context under `owner`'s ledger for
 * `sessionId`, null for a bare op, for a call another ledger
 * runs (a host callback reaching a second workspace mid-call) or for
 * another session's call. Without task isolation every live call is in
 * reach, so the newest of this ledger's and session's is taken.
 */
export declare function getOpCall(owner: Decisions, sessionId: string): HandOff | null;
/**
 * The call `caller` runs in under `owner`'s ledger for `sessionId`, null
 * for a bare op, for a call another ledger runs or for another session's
 * call. Mirrors Python's `call_of`.
 */
export declare function callOf(caller: Caller, owner: Decisions, sessionId: string): HandOff | null;
//# sourceMappingURL=decisions.d.ts.map