@hunterzhu/pulse-runtime 0.1.0

package/dist/core/types.d.ts

@@ -0,0 +1,615 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type LaneId = string;
+export type AgentId = string;
+export type EffectId = string;
+export type WaitId = string;
+export type ResultRef = string;
+export type ArtifactRef = string;
+export type FindingRef = ResultRef;
+export type DataRef = {
+    kind: 'result';
+    ref: ResultRef;
+} | {
+    kind: 'artifact';
+    ref: ArtifactRef;
+};
+export type ProvenanceRef = string | DataRef;
+export declare function provenanceRefId(ref: ProvenanceRef): string;
+export declare function provenanceRefKind(ref: ProvenanceRef): 'legacy' | DataRef['kind'];
+export type ContextVersion = number;
+export type PrivacyLabel = 'public' | 'cloud_allowed' | 'local_only';
+export type SideEffectPolicy = 'none' | 'read' | 'write' | 'external';
+export type ForkAffinityMode = 'off' | 'advise' | 'coalesce';
+export type LaneStatus = 'ready' | 'running' | 'waiting' | 'closing' | 'cancelling' | 'succeeded' | 'failed' | 'cancelled';
+export type EffectState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'retry_wait' | 'reconcile_required';
+export type ConcurrencyClass = 'llm' | 'tool' | 'agent' | 'none';
+export type OutcomeStatus = 'succeeded' | 'failed' | 'cancelled';
+export interface ResourceLockSpec {
+    resource: string;
+    mode: 'shared' | 'exclusive';
+}
+export interface PrivacyTaint {
+    path: string[];
+    privacy: PrivacyLabel;
+}
+export interface PrivacyMetadata {
+    privacy: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+}
+export interface RuntimeError {
+    code: string;
+    message: string;
+    /** Explicitly prevents or permits automatic retry when the failure is settled by an Effect host. */
+    retryable?: boolean;
+    details?: JsonValue;
+}
+export interface Outcome {
+    status: OutcomeStatus;
+    resultRef?: ResultRef;
+    result?: JsonValue;
+    rejectedOutputRefs?: ResultRef[];
+    error?: RuntimeError;
+    reason?: string;
+    unresolvedEffectIds?: EffectId[];
+}
+export interface ResumePoint {
+    programId: string;
+    programVersion: string;
+    step: string;
+    locals: JsonValue;
+}
+export interface HistoryRecord {
+    seq: number;
+    effectId?: EffectId;
+    instruction: string;
+    resultRefs: ResultRef[];
+    resultSelection?: Array<{
+        ref: ResultRef;
+        rule: string;
+        hash: string;
+    }>;
+    result?: ResultRef;
+    findings?: FindingRef[];
+    output: JsonValue;
+    privacy: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+}
+export interface LaneContext {
+    version: ContextVersion;
+    history: HistoryRecord[];
+    state: JsonValue;
+    privacy?: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+}
+export interface ProgressWatchdogState {
+    window: string[];
+    actionSignatures?: string[];
+    progressKeys?: string[];
+    noProgressCount: number;
+    interventionLevel: 0 | 1 | 2 | 3;
+    lastFingerprint?: string;
+    lastReason?: string;
+}
+export interface HistoryPressure {
+    historyTokens: number;
+    softTokens: number;
+    hardTokens: number;
+}
+export interface AgentRecord {
+    id: AgentId;
+    rootLaneId: LaneId;
+    goal?: string;
+    state?: 'created' | 'running' | 'cancelling' | 'succeeded' | 'failed' | 'cancelled';
+    policyId?: string;
+    limitsId?: string;
+    deadlineAt?: number;
+    globalVersions: Map<ContextVersion, JsonValue>;
+    globalPrivacy?: Map<ContextVersion, PrivacyMetadata>;
+    latestGlobalVersion: ContextVersion;
+    maxActiveLanes: number;
+    parentAgentId?: AgentId;
+    depth?: number;
+    detached?: boolean;
+}
+export interface LaneRecord {
+    id: LaneId;
+    agentId: AgentId;
+    ownerLaneId?: LaneId;
+    status: LaneStatus;
+    version: number;
+    goal: string;
+    resume: ResumePoint;
+    series?: SeriesLaneSpec;
+    pendingResumeInput?: ResumeInput;
+    /** Control proposals that arrived while another ResumeInput occupied the slot. */
+    pendingControlProposals?: ControlProposal[];
+    contextSnapshotVersion: ContextVersion;
+    context: LaneContext;
+    visibleResultRefs?: Set<ResultRef>;
+    activeWaitId?: WaitId;
+    children: Set<LaneId>;
+    priority: number;
+    inheritedFloor?: number;
+    enqueueSeq: number;
+    readySince: number;
+    ownedEffectIds: Set<EffectId>;
+    closingResult?: {
+        value: JsonValue;
+        privacy: PrivacyLabel;
+        privacyTaints?: PrivacyTaint[];
+        derivedFrom?: ProvenanceRef[];
+    };
+    failure?: {
+        error: RuntimeError;
+        privacy: PrivacyLabel;
+        derivedFrom?: ProvenanceRef[];
+    };
+    cancelReason?: string;
+    resultRef?: ResultRef;
+    consecutiveControlErrors?: number;
+    pendingOutcome?: Outcome;
+    unresolvedEffectIds?: EffectId[];
+    progressWatchdog?: ProgressWatchdogState;
+    historyPressure?: HistoryPressure;
+}
+export interface EffectRecord {
+    id: EffectId;
+    agentId: AgentId;
+    ownerLaneId: LaneId;
+    key: string;
+    kind: 'llm' | 'tool' | 'human' | 'agent' | 'timer';
+    concurrencyClass: ConcurrencyClass;
+    input: JsonValue;
+    derivedFrom?: ProvenanceRef[];
+    state: EffectState;
+    attemptId: string;
+    attemptNo: number;
+    executionState: 'local' | 'running' | 'succeeded' | 'failed' | 'remote_unknown' | 'local_closed' | 'settled';
+    sideEffectState: 'none' | 'applied' | 'known' | 'unknown';
+    executionRef?: JsonValue;
+    attempts?: AttemptRecord[];
+    cancelRequested?: {
+        reason: string;
+        at: number;
+    };
+    schedulePriority?: number;
+    inheritedFloor?: number;
+    deadlineAt?: number;
+    cancelGraceMs?: number;
+    attemptTimeoutMs?: number;
+    idempotencyKey?: string;
+    sideEffectPolicy?: SideEffectPolicy;
+    toolVersion?: string;
+    retryPolicy?: {
+        maxAttempts: number;
+        initialBackoffMs: number;
+        maxBackoffMs: number;
+        jitter: boolean;
+    };
+    duplicateExecutionPolicy?: 'allow' | 'forbid';
+    maxUnknownAttempts?: number;
+    retryAt?: number;
+    preparation?: {
+        state: 'idle' | 'preparing' | 'prepared' | 'stale';
+        generation: number;
+        projectionRef?: string;
+    };
+    outcome?: Outcome;
+    toolCallId?: string;
+    llmEffectId?: EffectId;
+    childAgentId?: AgentId;
+    locks?: ResourceLockSpec[];
+}
+export interface AttemptRecord {
+    id: string;
+    effectId: EffectId;
+    modelId?: string;
+    providerId?: string;
+    executionState: EffectRecord['executionState'];
+    sideEffectState: EffectRecord['sideEffectState'];
+    startedAt?: number;
+    settledAt?: number;
+    error?: RuntimeError;
+    remoteStatusRef?: JsonValue;
+    sideEffectRef?: JsonValue;
+}
+export interface ResultRecord {
+    id: ResultRef;
+    effectId?: EffectId;
+    /** Stable producer identity used by DSL metadata and audit tooling. */
+    producer?: TargetRef;
+    kind?: 'result' | 'finding' | 'rejected_output';
+    statement?: string;
+    evidenceRefs?: DataRef[];
+    value?: JsonValue;
+    storageState?: 'memory' | 'persisted';
+    pinCount?: number;
+    privacy: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+    derivedFrom: ProvenanceRef[];
+    summary?: JsonValue;
+    sizeBytes?: number;
+    contentHash?: string;
+    normalized?: JsonValue;
+    downgrade?: {
+        sourceRefs: ProvenanceRef[];
+        targetPrivacy: 'cloud_allowed';
+        method: 'human_approval' | 'sanitizer';
+        approvalRef?: string;
+        sanitizerId?: string;
+    };
+}
+export interface FindingRecord extends ResultRecord {
+    kind: 'finding';
+    statement: string;
+    evidenceRefs: DataRef[];
+    agentId: AgentId;
+    laneId: LaneId;
+}
+export interface ArtifactRecord {
+    ref: ArtifactRef;
+    agentId?: AgentId;
+    mediaType: string;
+    sizeBytes: number;
+    contentHash: string;
+    contentBase64: string;
+    privacy: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+    derivedFrom?: ProvenanceRef[];
+    storageState: 'memory' | 'persisted';
+    pinCount: number;
+}
+export interface DependencySpec {
+    key: string;
+    target: TargetRef | LocalRef;
+    condition: 'success' | 'settled';
+}
+export interface WaitSpec {
+    dependencies: DependencySpec[];
+    mode: 'all' | 'any' | 'quorum';
+    quorum?: number;
+    onUnsatisfied: 'fail_lane' | 'resume_with_error';
+    onCancelled?: 'unsatisfied' | 'ignore';
+    reason: 'startup' | 'effect' | 'dependency' | 'join' | 'timer';
+    deadlineAt?: number;
+}
+export interface WaitRecord {
+    id: WaitId;
+    laneId: LaneId;
+    spec: WaitSpec;
+    state: 'pending' | 'satisfied' | 'unsatisfied';
+    resolution?: WaitResolution;
+}
+export type TargetRef = {
+    kind: 'lane' | 'effect';
+    id: string;
+};
+export type LocalRef = {
+    local: string;
+};
+export type DependencyObservation = {
+    state: 'pending';
+    target: TargetRef;
+} | {
+    state: 'settled';
+    target: TargetRef;
+    outcome: Outcome;
+} | {
+    state: 'ignored';
+    target: TargetRef;
+    outcome: Outcome;
+};
+export interface WaitResolution {
+    waitId: WaitId;
+    status: 'satisfied' | 'unsatisfied';
+    dependencies: Record<string, DependencyObservation>;
+    error?: RuntimeError;
+}
+export type ControlProposal = {
+    type: 'cancel_lane';
+    laneId: LaneId;
+    reason: string;
+    fromLaneId: LaneId;
+};
+export type ResumeInput = {
+    type: 'wait';
+    resolution: WaitResolution;
+} | {
+    type: 'submitted';
+    targets: Record<string, TargetRef>;
+} | {
+    type: 'control_error';
+    error: RuntimeError;
+    original?: ResumeInput;
+} | {
+    type: 'control_proposal';
+    proposals: ControlProposal[];
+};
+export declare function enqueueControlProposal(lane: LaneRecord, proposal: ControlProposal): void;
+/** Replace the resume slot. Existing control_proposal inputs are parked, then promoted if the slot ends up empty. */
+export declare function replaceResumeInput(lane: LaneRecord, input: ResumeInput | undefined): void;
+export interface EffectSubmission {
+    key: string;
+    kind: EffectRecord['kind'];
+    concurrencyClass: ConcurrencyClass;
+    input: JsonValue;
+    derivedFrom?: ProvenanceRef[];
+    wait?: boolean;
+    privacy?: PrivacyLabel;
+    priority?: number;
+    deadlineAt?: number;
+    cancelGraceMs?: number;
+    attemptTimeoutMs?: number;
+    idempotencyKey?: string;
+    sideEffectPolicy?: SideEffectPolicy;
+    toolVersion?: string;
+    retryPolicy?: {
+        maxAttempts: number;
+        initialBackoffMs: number;
+        maxBackoffMs: number;
+        jitter: boolean;
+    };
+    duplicateExecutionPolicy?: 'allow' | 'forbid';
+    maxUnknownAttempts?: number;
+    toolCallId?: string;
+    llmEffectId?: EffectId;
+    locks?: ResourceLockSpec[];
+}
+export interface ForkLaneSpec {
+    key: string;
+    goal: string;
+    program: ResumePoint;
+    priority?: number;
+    contextVersion?: 'parent' | 'latest' | ContextVersion;
+    affinityKey?: string;
+    resources?: ResourceLockSpec[];
+    inputResultRefs?: ResultRef[];
+    toolSetId?: string;
+    workspacePath?: string;
+    dependsOn?: Array<{
+        key: string;
+        target: TargetRef | LocalRef;
+        condition: 'success' | 'settled';
+    }>;
+    series?: SeriesLaneSpec;
+}
+export interface SeriesLaneSpec {
+    member: ResumePoint;
+    keys: string[];
+    goals?: Record<string, string>;
+    members?: Record<string, {
+        dependsOn: Array<{
+            key: string;
+            condition: 'success' | 'settled';
+        }>;
+    }>;
+    onMemberFailure?: 'continue' | 'abort';
+}
+export interface RuntimeActionBase {
+    type: string;
+}
+export interface SubmitEffectsAction extends RuntimeActionBase {
+    type: 'submit_effects';
+    effects: EffectSubmission[];
+    wait?: {
+        onUnsatisfied: 'fail_lane' | 'resume_with_error';
+        onCancelled?: 'unsatisfied' | 'ignore';
+        reason?: WaitSpec['reason'];
+        deadlineAt?: number;
+    };
+}
+export interface WaitAction extends RuntimeActionBase {
+    type: 'wait';
+    spec: WaitSpec;
+}
+export interface ForkAction extends RuntimeActionBase {
+    type: 'fork';
+    lanes: ForkLaneSpec[];
+    affinityAck?: boolean;
+    joinAliases?: Record<string, string>;
+    join?: {
+        condition: 'success' | 'settled';
+        mode?: WaitSpec['mode'];
+        quorum?: number;
+        deadlineAt?: number;
+        onUnsatisfied: 'fail_lane' | 'resume_with_error';
+        onCancelled?: 'unsatisfied' | 'ignore';
+    };
+}
+export interface CancelLaneAction extends RuntimeActionBase {
+    type: 'cancel_lane';
+    laneId: LaneId;
+    reason: 'SUPERSEDED' | 'USER_REQUESTED' | 'POLICY';
+}
+export interface ProposeCancelAction extends RuntimeActionBase {
+    type: 'propose_cancel';
+    laneId: LaneId;
+    reason: 'SUPERSEDED' | 'POLICY';
+}
+export interface CompleteAction extends RuntimeActionBase {
+    type: 'complete';
+    result: JsonValue;
+    privacy?: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+    derivedFrom?: ProvenanceRef[];
+    children?: 'reject_if_active' | 'cancel' | 'await';
+}
+export interface FailAction extends RuntimeActionBase {
+    type: 'fail';
+    error: RuntimeError;
+    privacy?: PrivacyLabel;
+    derivedFrom?: ProvenanceRef[];
+}
+export interface AdoptContextAction extends RuntimeActionBase {
+    type: 'adopt_context';
+    version: ContextVersion | 'latest';
+}
+export interface DowngradePrivacyAction extends RuntimeActionBase {
+    type: 'downgrade_privacy';
+    sourceRefs: ProvenanceRef[];
+    outputRef: ResultRef;
+    value: JsonValue;
+    targetPrivacy: 'cloud_allowed';
+    method: 'human_approval' | 'sanitizer';
+    approvalRef?: string;
+    sanitizerId?: string;
+    summary?: JsonValue;
+}
+export type RuntimeAction = SubmitEffectsAction | WaitAction | ForkAction | CancelLaneAction | ProposeCancelAction | CompleteAction | FailAction | AdoptContextAction | DowngradePrivacyAction;
+export interface ContextOp {
+    op: 'set' | 'append' | 'remove' | 'compact_history';
+    path?: string[];
+    value?: JsonValue;
+    upToSeq?: number;
+    summary?: JsonValue;
+    summaryRef?: ResultRef;
+}
+export interface ContextDelta {
+    target: 'global' | 'lane';
+    baseVersion: ContextVersion;
+    sourceLaneId?: LaneId;
+    ops: ContextOp[];
+    privacy?: PrivacyLabel;
+    privacyTaints?: PrivacyTaint[];
+    derivedFrom?: ProvenanceRef[];
+    proposal?: boolean;
+}
+export interface MergeProposal {
+    id: string;
+    agentId: AgentId;
+    sourceLaneId: LaneId;
+    baseGlobalVersion: ContextVersion;
+    delta: ContextDelta;
+    createdAt: number;
+}
+export interface LaneStepOutput {
+    contextDelta?: ContextDelta;
+    adoptCommittedContext?: boolean;
+    actions: RuntimeAction[];
+    next: ResumePoint;
+    locals?: JsonValue;
+}
+export interface LLMContextSpec {
+    globalSnapshotVersion: ContextVersion;
+    laneSnapshotVersion: ContextVersion;
+    resultRefs: ResultRef[];
+    artifactRefs?: ArtifactRef[];
+    eventIds: string[];
+    toolSetId: string;
+    instruction: string;
+    privacy: PrivacyLabel;
+    privacyRefs: ProvenanceRef[];
+    privacyTaints?: PrivacyTaint[];
+}
+export interface LLMRequestProjection {
+    contextSpec: LLMContextSpec;
+    blocks: Array<{
+        kind: 'system' | 'policy' | 'tools' | 'global' | 'history' | 'lane' | 'events' | 'results' | 'artifacts' | 'instruction';
+        content: JsonValue;
+    }>;
+    prefixHash: string;
+    projectionHash: string;
+    builderVersion: string;
+    policyVersion: string;
+    toolSetVersion: string;
+    privacy: PrivacyLabel;
+    privacyRefs: ProvenanceRef[];
+    privacyTaints?: PrivacyTaint[];
+}
+export interface RuntimeEvent {
+    id: string;
+    schemaVersion: number;
+    sessionId: string;
+    seq: number;
+    timestamp: number;
+    type: string;
+    txId?: string;
+    agentId?: AgentId;
+    laneId?: LaneId;
+    effectId?: EffectId;
+    attemptId?: string;
+    causationId?: string;
+    payload: JsonValue;
+    data?: JsonValue;
+}
+export interface RuntimeEventInput {
+    id?: string;
+    schemaVersion?: number;
+    sessionId?: string;
+    type: string;
+    timestamp?: number;
+    txId?: string;
+    agentId?: AgentId;
+    laneId?: LaneId;
+    effectId?: EffectId;
+    attemptId?: string;
+    causationId?: string;
+    payload?: JsonValue;
+    data?: JsonValue;
+}
+export interface RuntimeState {
+    now: number;
+    agents: Map<AgentId, AgentRecord>;
+    lanes: Map<LaneId, LaneRecord>;
+    effects: Map<EffectId, EffectRecord>;
+    waits: Map<WaitId, WaitRecord>;
+    results: Map<ResultRef, ResultRecord>;
+    artifacts: Map<ArtifactRef, ArtifactRecord>;
+    toolCallCorrelations: Map<string, ToolCallCorrelation>;
+    mergeProposals: Map<string, MergeProposal>;
+    events: RuntimeEvent[];
+    eventsCompactedThrough?: number;
+    nextIds: {
+        agent: number;
+        lane: number;
+        effect: number;
+        wait: number;
+        result: number;
+        artifact: number;
+        proposal: number;
+        event: number;
+    };
+    maxTotalLanes: number;
+    maxQueuedEffects: number;
+    maxRunning: Record<ConcurrencyClass, number>;
+    forkAffinity: ForkAffinityMode;
+    historySoftTokens: number;
+    historyHardTokens: number;
+    maxResultSummaryBytes: number;
+    trustedSanitizerIds: Set<string>;
+}
+export interface ContextSnapshotRef {
+    kind: 'global' | 'lane';
+    agentId?: AgentId;
+    laneId?: LaneId;
+    version: ContextVersion;
+}
+export declare function globalContextRef(agentId: AgentId, version: ContextVersion): string;
+export declare function laneContextRef(laneId: LaneId, version: ContextVersion): string;
+export declare function parseContextSnapshotRef(ref: string): ContextSnapshotRef | undefined;
+export declare function privacyForContextSnapshot(state: RuntimeState, lane: LaneRecord, ref: string): PrivacyMetadata | undefined;
+export declare function privacyMetadataForDerivedRef(state: RuntimeState, lane: LaneRecord, ref: ProvenanceRef): PrivacyMetadata | undefined;
+export declare function privacyTaintsForDerivedRefs(state: RuntimeState, lane: LaneRecord, refs: readonly ProvenanceRef[]): PrivacyTaint[];
+export interface ToolCallCorrelation {
+    toolCallId: string;
+    llmEffectId: EffectId;
+    toolEffectId: EffectId;
+    resultRef?: ResultRef;
+}
+export declare function createRuntimeState(maxTotalLanes?: number, options?: {
+    maxQueuedEffects?: number;
+    maxRunning?: Partial<Record<ConcurrencyClass, number>>;
+    forkAffinity?: ForkAffinityMode;
+    historySoftTokens?: number;
+    historyHardTokens?: number;
+    maxResultSummaryBytes?: number;
+    trustedSanitizerIds?: Iterable<string>;
+}): RuntimeState;
+export declare function privacyRank(label: PrivacyLabel): number;
+export declare function strictestPrivacy(labels: PrivacyLabel[]): PrivacyLabel;
+export declare function isSideEffectful(policy: SideEffectPolicy | undefined): boolean;
+export declare function privacyTaintPrivacy(taints: readonly PrivacyTaint[] | undefined): PrivacyLabel;
+export declare function effectivePrivacy(base: PrivacyLabel, taints: readonly PrivacyTaint[] | undefined): PrivacyLabel;
+export declare function validatePrivacyTaints(value: readonly PrivacyTaint[] | undefined): string | undefined;