@jini-ai/daemon 0.3.8 → 0.5.0

package/dist/run-credentials.d.ts

@@ -0,0 +1,138 @@
+export interface RunScopedCaller {
+    readonly runId: string;
+    readonly principalId: string;
+}
+export interface CredentialCryptoPort {
+    mintToken(args: Record<string, never>): string;
+    digest(args: {
+        token: string;
+    }): string;
+    tokensMatch(args: {
+        presented: string;
+        expected: string;
+    }): boolean;
+}
+/** Explicit Node adapter; consumers can inject an alternate crypto implementation. */
+export declare function createNodeCredentialCrypto(_args: Record<string, never>): CredentialCryptoPort;
+export interface RunScopedCallerResolver {
+    resolveCaller(args: {
+        token: string;
+    }): RunScopedCaller | undefined;
+}
+export interface RunScopedCredentials extends RunScopedCallerResolver {
+    mint(args: {
+        runId: string;
+    }): string;
+    resolvePrincipal(args: {
+        token: string;
+    }): string | undefined;
+    revoke(args: {
+        runId: string;
+    }): void;
+}
+export declare function createRunScopedCredentials(deps: {
+    principalOfLiveRun(args: {
+        runId: string;
+    }): string | undefined;
+    crypto: Pick<CredentialCryptoPort, 'mintToken' | 'digest'>;
+}): RunScopedCredentials;
+export declare function ensureAgentDaemonToken({ env, envVarName, crypto }: {
+    env: Record<string, string | undefined>;
+    envVarName: string;
+    crypto: Pick<CredentialCryptoPort, 'mintToken'>;
+}): string;
+export interface RouteAccessPolicy {
+    /** Return a URL-decoded run ID; malformed encoding must throw URIError. */
+    targetRun(args: {
+        path: string;
+    }): string | undefined;
+    allowsRunScoped(args: {
+        method: string;
+        path: string;
+    }): boolean;
+    isDelegatedCall(args: {
+        method: string;
+        path: string;
+    }): boolean;
+    isEventStream(args: {
+        path: string;
+    }): boolean;
+}
+/** Host supplies route names; this module owns matching and run isolation. */
+export declare function createRouteAccessPolicy({ runPathPrefix, delegatedToolCallsPath, eventStreamSuffix, allowedRoutes }: {
+    runPathPrefix: string;
+    delegatedToolCallsPath: string;
+    eventStreamSuffix: string;
+    allowedRoutes: readonly {
+        method: string;
+        path: RegExp;
+    }[];
+}): RouteAccessPolicy;
+export type AccessDecision = {
+    allowed: true;
+    principalHeader?: {
+        name: string;
+        value: string;
+    };
+} | {
+    allowed: false;
+    status: 400 | 401 | 403 | 404 | 503;
+    body: unknown;
+};
+/** Transport-independent bearer gate. Apply principalHeader only after an allowed decision. */
+export declare function authorizeDaemonRequest({ request, env, envVarName, principalHeaderName, authorizationHeaderName, crypto, routes }: {
+    request: {
+        method: string;
+        path: string;
+        headers: Readonly<Record<string, string | undefined>>;
+        body?: unknown;
+    };
+    env: Readonly<Record<string, string | undefined>>;
+    envVarName: string;
+    principalHeaderName: string;
+    authorizationHeaderName: string;
+    crypto: Pick<CredentialCryptoPort, 'tokensMatch'>;
+    routes: RouteAccessPolicy;
+}, { exemptPaths, runScopedCallers, validateDelegatedRunId }?: {
+    exemptPaths?: readonly string[];
+    runScopedCallers?: RunScopedCallerResolver;
+    validateDelegatedRunId?: boolean;
+}): AccessDecision;
+export interface RunOwnerRegistry {
+    record(args: {
+        runId: string;
+        principalId: string;
+    }): void;
+    ownerOf(args: {
+        runId: string;
+    }): string | undefined;
+    forget(args: {
+        runId: string;
+    }): void;
+}
+export declare function createRunOwnerRegistry(_args: Record<string, never>): RunOwnerRegistry;
+/** Mount after the bearer gate; principalId must be server verified. */
+export declare function authorizeRunOwnership({ runId, principalId, principalHeaderName, registry, runExists, eventStream }: {
+    runId: string | undefined;
+    principalId: string | undefined;
+    principalHeaderName: string;
+    registry: RunOwnerRegistry;
+    runExists: (args: {
+        runId: string;
+    }) => Promise<boolean>;
+    eventStream: boolean;
+}): Promise<AccessDecision>;
+export declare function listOwnedRuns<Run extends {
+    id: string;
+}>({ runs, registry, principalId, principalHeaderName }: {
+    runs: readonly Run[];
+    registry: RunOwnerRegistry;
+    principalId: string | undefined;
+    principalHeaderName: string;
+}): {
+    allowed: true;
+    runs: Run[];
+} | Exclude<AccessDecision, {
+    allowed: true;
+}>;
+//# sourceMappingURL=run-credentials.d.ts.map

package/dist/run-credentials.js

@@ -0,0 +1,152 @@
+import { timingSafeTokenMatch } from '@jini-ai/core';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+/** Explicit Node adapter; consumers can inject an alternate crypto implementation. */
+export function createNodeCredentialCrypto(_args) {
+    return {
+        mintToken: () => randomBytes(32).toString('hex'),
+        digest: ({ token }) => createHash('sha256').update(token, 'utf8').digest('hex'),
+        tokensMatch({ presented, expected }) {
+            return timingSafeTokenMatch({ presented, expected, timingSafeEqual: ({ left, right }) => timingSafeEqual(left, right) });
+        },
+    };
+}
+export function createRunScopedCredentials(deps) {
+    const runByDigest = new Map();
+    const tokens = new Map();
+    const resolveCaller = ({ token }) => {
+        const runId = runByDigest.get(deps.crypto.digest({ token }));
+        if (runId === undefined)
+            return undefined;
+        const principalId = deps.principalOfLiveRun({ runId });
+        return principalId === undefined ? undefined : { runId, principalId };
+    };
+    return {
+        mint({ runId }) {
+            if (deps.principalOfLiveRun({ runId }) === undefined)
+                throw new Error(`cannot mint a credential for run "${runId}": it is not live`);
+            const existing = tokens.get(runId);
+            if (existing !== undefined)
+                return existing;
+            const token = deps.crypto.mintToken({});
+            const digest = deps.crypto.digest({ token });
+            if (!token || runByDigest.has(digest))
+                throw new Error('run credential must be nonempty and unique');
+            tokens.set(runId, token);
+            runByDigest.set(digest, runId);
+            return token;
+        },
+        resolveCaller,
+        resolvePrincipal: args => resolveCaller(args)?.principalId,
+        revoke({ runId }) {
+            const token = tokens.get(runId);
+            if (token === undefined)
+                return;
+            tokens.delete(runId);
+            runByDigest.delete(deps.crypto.digest({ token }));
+        },
+    };
+}
+export function ensureAgentDaemonToken({ env, envVarName, crypto }) {
+    const existing = env[envVarName];
+    if (typeof existing === 'string' && existing.length > 0)
+        return existing;
+    const token = crypto.mintToken({});
+    if (!token)
+        throw new Error('daemon credential must be nonempty');
+    env[envVarName] = token;
+    return token;
+}
+/** Host supplies route names; this module owns matching and run isolation. */
+export function createRouteAccessPolicy({ runPathPrefix, delegatedToolCallsPath, eventStreamSuffix, allowedRoutes }) {
+    return {
+        targetRun({ path }) {
+            // Binding is case insensitive as in the original gate, while the allowlist remains exact.
+            const prefix = runPathPrefix.endsWith('/') ? runPathPrefix : `${runPathPrefix}/`;
+            if (!path.toLowerCase().startsWith(prefix.toLowerCase()))
+                return undefined;
+            const segment = path.slice(prefix.length).split('/')[0];
+            return segment ? decodeURIComponent(segment) : undefined;
+        },
+        allowsRunScoped({ method, path }) {
+            // Strip stateful flags so repeated calls cannot alternate permission decisions.
+            return allowedRoutes.some(route => route.method === method && new RegExp(route.path.source, route.path.flags.replace(/[gy]/g, '')).test(path));
+        },
+        isDelegatedCall: ({ method, path }) => method === 'POST' && path === delegatedToolCallsPath,
+        isEventStream: ({ path }) => path.toLowerCase().replace(/\/$/, '').endsWith(eventStreamSuffix.toLowerCase()),
+    };
+}
+const bearerPattern = /^Bearer[ \t]+(\S+)[ \t]*$/i;
+function notFound(runId, stream) {
+    return { allowed: false, status: 404, body: { error: { code: 'NOT_FOUND', message: stream ? 'run was not found' : `run "${runId}" was not found` } } };
+}
+/** Transport-independent bearer gate. Apply principalHeader only after an allowed decision. */
+export function authorizeDaemonRequest({ request, env, envVarName, principalHeaderName, authorizationHeaderName, crypto, routes }, { exemptPaths = [], runScopedCallers, validateDelegatedRunId = false } = {}) {
+    const authorization = request.headers[authorizationHeaderName];
+    if (exemptPaths.includes(request.path) && authorization === undefined)
+        return { allowed: true };
+    const expected = env[envVarName];
+    if (typeof expected !== 'string' || expected.length === 0)
+        return {
+            allowed: false, status: 503, body: { error: `the agent daemon is not configured: ${envVarName} is unset`, code: 'AGENT_DAEMON_UNCONFIGURED' },
+        };
+    const token = bearerPattern.exec(authorization ?? '')?.[1];
+    if (token !== undefined && crypto.tokensMatch({ presented: token, expected }))
+        return { allowed: true };
+    const caller = token === undefined ? undefined : runScopedCallers?.resolveCaller({ token });
+    if (caller === undefined)
+        return { allowed: false, status: 401, body: { error: `Authorization: Bearer <${envVarName}> is required`, code: 'UNAUTHENTICATED' } };
+    let target;
+    try {
+        target = routes.targetRun({ path: request.path });
+    }
+    catch (error) {
+        if (!(error instanceof URIError))
+            throw error;
+        return { allowed: false, status: 400, body: { error: { code: 'BAD_REQUEST', message: 'runId is not valid URL encoding' } } };
+    }
+    if (target !== undefined && target !== caller.runId)
+        return notFound(target, routes.isEventStream({ path: request.path }));
+    if (!routes.allowsRunScoped(request))
+        return { allowed: false, status: 403, body: { error: `a run-scoped credential cannot call ${request.method} ${request.path}`, code: 'FORBIDDEN' } };
+    if (validateDelegatedRunId && routes.isDelegatedCall(request)) {
+        const bodyRunId = request.body !== null && typeof request.body === 'object' ? request.body['runId'] : undefined;
+        if (bodyRunId !== caller.runId)
+            return { allowed: false, status: 403, body: { error: 'a run-scoped credential requires body.runId to match its own run', code: 'FORBIDDEN' } };
+    }
+    return { allowed: true, principalHeader: { name: principalHeaderName, value: caller.principalId } };
+}
+export function createRunOwnerRegistry(_args) {
+    const owners = new Map();
+    return {
+        record: ({ runId, principalId }) => { owners.set(runId, principalId); },
+        ownerOf: ({ runId }) => owners.get(runId),
+        forget: ({ runId }) => { owners.delete(runId); },
+    };
+}
+function principalRequired(principalHeaderName) {
+    return { allowed: false, status: 401, body: { error: { code: 'UNAUTHENTICATED', message: `${principalHeaderName} is required on run-scoped requests` } } };
+}
+/** Mount after the bearer gate; principalId must be server verified. */
+export async function authorizeRunOwnership({ runId, principalId, principalHeaderName, registry, runExists, eventStream }) {
+    if (!principalId)
+        return principalRequired(principalHeaderName);
+    if (!runId)
+        return { allowed: true };
+    const owner = registry.ownerOf({ runId });
+    if (owner === principalId)
+        return { allowed: true };
+    if (owner !== undefined)
+        return notFound(runId, eventStream);
+    let exists = true;
+    try {
+        exists = await runExists({ runId });
+    }
+    catch { /* Unknown ownership fails closed on lookup failure. */ }
+    return exists ? notFound(runId, eventStream) : { allowed: true };
+}
+export function listOwnedRuns({ runs, registry, principalId, principalHeaderName }) {
+    if (!principalId)
+        return principalRequired(principalHeaderName);
+    return { allowed: true, runs: runs.filter(run => registry.ownerOf({ runId: run.id }) === principalId) };
+}
+//# sourceMappingURL=run-credentials.js.map

package/dist/run-lifecycle.d.ts

@@ -10,7 +10,7 @@ export interface StartRunInput {
      * returns the original run (`started: false`) instead of creating a
      * second one — new behavior this port builds fresh, since OD's own
      * `clientRequestId` is threaded through but never actually deduplicated
-     * against (confirmed absent upstream; see `source-map.md`).
+     * against (confirmed absent upstream; see `archived provenance ledger`).
      */
     readonly idempotencyKey?: string;
     /** Override the generated run id — test/fixture hook only. */
@@ -70,23 +70,35 @@ export type StreamSubscribeResult = {
 }>;
 export interface RunLifecycle {
     /** Rebuilds the in-memory run index from durable EventLog records. Hosts must await this once during boot before accepting run requests. */
-    rehydrate(): Promise<void>;
-    start(input: StartRunInput): Promise<StartRunResult>;
-    get(runId: string): Promise<RunStatus | undefined>;
-    list(contextRef?: string): Promise<readonly RunStatus[]>;
+    rehydrate(_args: Record<string, never>): Promise<void>;
+    start(requiredArgs: Pick<StartRunInput, "contextRef">, optionalArgs?: Pick<StartRunInput, "agentId" | "idempotencyKey" | "runId" | "inactivityTimeoutMs">): Promise<StartRunResult>;
+    get(args: {
+        readonly runId: string;
+    }): Promise<RunStatus | undefined>;
+    list(args: Record<string, never>, optionalArgs?: {
+        readonly contextRef?: string;
+    }): Promise<readonly RunStatus[]>;
     /** Records cancellation intent. Idempotent — cancelling an already-terminal run is a no-op, not an error. */
     cancel(request: RunCancelRequest): Promise<RunStatus>;
     /** Registers a listener fired synchronously when `cancel()` is called for `runId`. Returns an unsubscribe function. */
-    onCancelRequested(runId: string, listener: (request: RunCancelRequest) => void): Unsubscribe;
+    onCancelRequested(args: {
+        readonly runId: string;
+        readonly listener: (request: RunCancelRequest) => void;
+    }): Unsubscribe;
     /** Appends a driver-observed event and fans it out to live subscribers. Throws if `runId` is unknown or already terminal. */
-    emit(runId: string, input: DriverEmittableInput): Promise<RunProtocolEvent>;
+    emit(args: {
+        readonly runId: string;
+        readonly input: DriverEmittableInput;
+    }): Promise<RunProtocolEvent>;
     /** Idempotent terminal transition; a second call while already terminal is a no-op that returns the existing status unchanged. */
-    finish(input: FinishRunInput): Promise<RunStatus>;
-    resume(runId: string): Promise<ResumeRunResult>;
+    finish(requiredArgs: Pick<FinishRunInput, "runId" | "status" | "code" | "signal" | "resumable">, optionalArgs?: Pick<FinishRunInput, "sessionRef">): Promise<RunStatus>;
+    resume(args: {
+        readonly runId: string;
+    }): Promise<ResumeRunResult>;
     /**
      * Suspends the slow-run watchdog for `runId` while a daemon-managed operation of legitimately
      * unbounded duration is in flight (e.g. an auto-resolved tool call the daemon itself awaits) — pair
-     * with {@link RunLifecycle.resumeSlowRunNotice} once that operation concludes. `emit()` is the
+     * with {@link RunLifecycle.resumeSlowRunNotice} once that operation concludes. `emit()` of an agent event (excluding the notice itself) is the
      * *only* other reset signal the watchdog has, and it fires nothing while such an operation is
      * running (there is no output to stream), so without this call a tool that legitimately runs past
      * the threshold (an install, a build, a repo-wide scan) is indistinguishable from the exact
@@ -95,16 +107,22 @@ export interface RunLifecycle {
      * rather than leaving the watchdog to guess from silence alone. No-op if `runId` is unknown,
      * already terminal, or the slow-run notice is disabled kernel-wide (`slowRunThresholdMs: null`).
      */
-    suspendSlowRunNotice(runId: string): void;
+    suspendSlowRunNotice(args: {
+        readonly runId: string;
+    }): void;
     /**
      * Re-arms the slow-run watchdog for `runId` with a fresh timeout window, undoing
      * {@link RunLifecycle.suspendSlowRunNotice} once the known operation concludes — so a genuinely
      * stalled stretch starting *after* that point is still caught. No-op under the same conditions as
      * `suspendSlowRunNotice`.
      */
-    resumeSlowRunNotice(runId: string): void;
+    resumeSlowRunNotice(args: {
+        readonly runId: string;
+    }): void;
     /** Resolves once `runId` reaches a terminal state; resolves immediately if it already has. */
-    waitForTerminal(runId: string): Promise<RunStatus>;
+    waitForTerminal(args: {
+        readonly runId: string;
+    }): Promise<RunStatus>;
     /**
      * Replays buffered history after `options.afterCursor` (or from the
      * beginning if omitted/null) and then subscribes `onEvent` for live
@@ -114,23 +132,37 @@ export interface RunLifecycle {
      * of the final `'end'` event, so a client can never silently miss the
      * terminal signal (`runs.ts` `stream()`, researched source).
      */
-    stream(runId: string, onEvent: (event: RunProtocolEvent) => void, options?: StreamOptions): Promise<StreamSubscribeResult>;
+    stream(args: {
+        readonly runId: string;
+        readonly onEvent: (event: RunProtocolEvent) => void;
+    }, optionalArgs?: StreamOptions): Promise<StreamSubscribeResult>;
 }
 /**
  * `start()`'s idempotency-replay lookup: the run id an existing `idempotencyKey` already maps to,
  * or `undefined` when there is no key or no existing mapping (a fresh start proceeds normally).
  * Pure.
  */
-export declare function resolveIdempotentReplayRunId(idempotencyIndex: ReadonlyMap<string, string>, idempotencyKey: string | undefined): string | undefined;
+export declare function resolveIdempotentReplayRunId({ idempotencyIndex, idempotencyKey }: {
+    readonly idempotencyIndex: ReadonlyMap<string, string>;
+    readonly idempotencyKey: string | undefined;
+}): string | undefined;
 /** Registers `runId` under `idempotencyKey` in `idempotencyIndex` — a no-op when no key was supplied. */
-export declare function registerIdempotencyKeyIfPresent(idempotencyIndex: Map<string, string>, idempotencyKey: string | undefined, runId: string): void;
+export declare function registerIdempotencyKeyIfPresent({ idempotencyIndex, idempotencyKey, runId }: {
+    readonly idempotencyIndex: Map<string, string>;
+    readonly idempotencyKey: string | undefined;
+    readonly runId: string;
+}): void;
 /**
  * Removes `idempotencyKey`'s mapping from `idempotencyIndex`, but only when it still points at
  * `runId` — used to roll back a failed durable `'start'` append without clobbering a different
  * run that may have since claimed the same key (defensive; `start()`'s own locking makes that
  * race unreachable today, but the check costs nothing and documents the invariant).
  */
-export declare function clearIdempotencyIndexEntryIfMatching(idempotencyIndex: Map<string, string>, idempotencyKey: string | undefined, runId: string): void;
+export declare function clearIdempotencyIndexEntryIfMatching({ idempotencyIndex, idempotencyKey, runId }: {
+    readonly idempotencyIndex: Map<string, string>;
+    readonly idempotencyKey: string | undefined;
+    readonly runId: string;
+}): void;
 /**
  * Default terminal-run retention window: how long a completed/failed/cancelled run's in-memory
  * record stays readable via `get`/`list`/`stream`/`resume` before eviction. `runs.set()` never had
@@ -152,7 +184,7 @@ export declare const DEFAULT_TERMINAL_RETENTION_MS: number;
 export declare const DEFAULT_MAX_TERMINAL_RUNS = 1000;
 /**
  * Default wall-clock threshold for the slow-run notice (distinct from the crash/inactivity watchdog
- * above): how long a run may go with no `emit()` before a `'slow_running'` agent event tells the UI
+ * above): how long a run may go with no agent-event `emit()` (excluding the notice itself) before a `'slow_running'` agent event tells the UI
  * "this is taking longer than usual," without ever finishing the run. See {@link armSlowRunWatchdogIfConfigured}'s
  * doc for the full "why a second, non-terminating watchdog" rationale. 45s was picked as long enough
  * that an ordinary quiet stretch (the agent thinking between tool calls, a slow but healthy model
@@ -169,17 +201,28 @@ export declare const DEFAULT_SLOW_RUN_THRESHOLD_MS = 45000;
  * where a run may have gone terminal long before this process started) schedules an immediate
  * eviction rather than a negative-delay timer. Pure.
  */
-export declare function computeRetentionDelayMs(terminalAt: number, retentionMs: number, now: number): number;
+export declare function computeRetentionDelayMs({ terminalAt, retentionMs, now }: {
+    readonly terminalAt: number;
+    readonly retentionMs: number;
+    readonly now: number;
+}): number;
 /** The durable `'start'` entry's payload — pure field mapping, split out of `start()` so its two optional-field spreads don't count toward that method's own complexity. */
-export declare function buildStartPayload(runId: string, startInput: Pick<StartRunInput, 'contextRef' | 'agentId' | 'idempotencyKey'>): RunStartPayload;
+export declare function buildStartPayload({ runId, startInput }: {
+    readonly runId: string;
+    readonly startInput: Pick<StartRunInput, 'contextRef' | 'agentId' | 'idempotencyKey'>;
+}): RunStartPayload;
 /**
  * Arms `record.watchdog` when `timeoutMs` is configured — a no-op otherwise. `record` is typed as a
  * plain `{watchdog}` shape (not `Pick<RunRecord, 'watchdog'>`) purely so this function can be
  * exported without naming the private `RunRecord` type in a public signature.
  */
-export declare function armWatchdogIfConfigured(record: {
-    watchdog: InactivityWatchdog | undefined;
-}, timeoutMs: number | undefined, onTimeout: () => void): void;
+export declare function armWatchdogIfConfigured({ record, timeoutMs, onTimeout }: {
+    readonly record: {
+        watchdog: InactivityWatchdog | undefined;
+    };
+    readonly timeoutMs: number | undefined;
+    readonly onTimeout: () => void;
+}): void;
 /**
  * Arms `record.slowRunWatchdog` when `timeoutMs` is configured — a no-op otherwise (the kernel-wide
  * opt-out: `CreateRunLifecycleInput.slowRunThresholdMs: null`). Deliberately a sibling of
@@ -190,31 +233,47 @@ export declare function armWatchdogIfConfigured(record: {
  * three-line dedup. `record` is typed as a plain `{slowRunWatchdog}` shape for the same exportability
  * reason {@link armWatchdogIfConfigured} already documents.
  */
-export declare function armSlowRunWatchdogIfConfigured(record: {
-    slowRunWatchdog: InactivityWatchdog | undefined;
-}, timeoutMs: number | undefined, onTimeout: () => void): void;
+export declare function armSlowRunWatchdogIfConfigured({ record, timeoutMs, onTimeout }: {
+    readonly record: {
+        slowRunWatchdog: InactivityWatchdog | undefined;
+    };
+    readonly timeoutMs: number | undefined;
+    readonly onTimeout: () => void;
+}): void;
 /**
  * `stream()`'s replay-delivery step: sends every already-durable entry to `onEvent`, returning the
  * delivered eventIds so a caller can avoid re-delivering the same event from a different source
  * (buffered live events observed during the replay, a terminal catch-up event). Pure aside from
  * calling the injected `onEvent`.
  */
-export declare function deliverReplayedEvents(runId: string, entries: readonly EventLogEntry[], onEvent: (event: RunProtocolEvent) => void): Set<string>;
+export declare function deliverReplayedEvents({ runId, entries, onEvent }: {
+    readonly runId: string;
+    readonly entries: readonly EventLogEntry[];
+    readonly onEvent: (event: RunProtocolEvent) => void;
+}): Set<string>;
 /**
  * Delivers every event in `events` not already present in `deliveredEventIds`, marking each as
  * delivered as it goes. Reused in `stream()` for both the buffered-live-event catch-up and the
  * single terminal-event catch-up, so the "don't double-deliver" bookkeeping lives in one place.
  */
-export declare function deliverUndeliveredEvents(events: readonly RunProtocolEvent[], deliveredEventIds: Set<string>, onEvent: (event: RunProtocolEvent) => void): void;
+export declare function deliverUndeliveredEvents({ events, deliveredEventIds, onEvent }: {
+    readonly events: readonly RunProtocolEvent[];
+    readonly deliveredEventIds: Set<string>;
+    readonly onEvent: (event: RunProtocolEvent) => void;
+}): void;
 /**
  * Closes out a `stream()` subscription once replay and catch-up delivery are done: a terminal run's
  * subscriber is removed immediately (no further event will ever come), a still-live run's stays
  * registered behind the returned `unsubscribe`. `record` is typed as a plain `{subscribers}` shape
  * for the same exportability reason as {@link armWatchdogIfConfigured}.
  */
-export declare function finishStreamSubscription(record: {
-    subscribers: Set<(event: RunProtocolEvent) => void>;
-}, subscriber: (event: RunProtocolEvent) => void, terminal: boolean): StreamSubscribeResult;
+export declare function finishStreamSubscription({ record, subscriber, terminal }: {
+    readonly record: {
+        subscribers: Set<(event: RunProtocolEvent) => void>;
+    };
+    readonly subscriber: (event: RunProtocolEvent) => void;
+    readonly terminal: boolean;
+}): StreamSubscribeResult;
 export interface CreateRunLifecycleInput {
     readonly eventLog: EventLog;
     /** Host-owned sink for asynchronous lifecycle failures that cannot be returned to a caller. Defaults to `console.error`. */
@@ -224,7 +283,7 @@ export interface CreateRunLifecycleInput {
     /** Hard cap on concurrently-retained terminal run records. See {@link DEFAULT_MAX_TERMINAL_RUNS}. Defaults to that constant. */
     readonly maxTerminalRuns?: number;
     /**
-     * How long a run may go with no `emit()` before a `'slow_running'` agent event tells the UI the
+     * How long a run may go with no agent-event `emit()` (excluding the notice itself) before a `'slow_running'` agent event tells the UI the
      * turn is taking longer than usual — never a terminating action; see
      * {@link armSlowRunWatchdogIfConfigured}'s doc. Applies kernel-wide to every `start()`ed run, unlike
      * `StartRunInput.inactivityTimeoutMs` (which requires a per-call opt-in and none of this codebase's
@@ -249,5 +308,5 @@ export interface RunLifecycleInternalErrorContext {
  * @complexity Per-call complexities documented on each method; the registry itself is a `Map` keyed by `runId` (O(1) lookup). Memory is bounded: non-terminal runs are O(n) in concurrently-live runs, and terminal runs are capped at `maxTerminalRuns` (each additionally bounded in retention time by `terminalRetentionMs`) rather than growing for the life of the process.
  * @overallScore 100/100
  */
-export declare function createRunLifecycle(input: CreateRunLifecycleInput): RunLifecycle;
+export declare function createRunLifecycle(requiredArgs: Pick<CreateRunLifecycleInput, "eventLog">, optionalArgs?: Pick<CreateRunLifecycleInput, "onInternalError" | "terminalRetentionMs" | "maxTerminalRuns" | "slowRunThresholdMs">): RunLifecycle;
 //# sourceMappingURL=run-lifecycle.d.ts.map