@spine-event-engine/server 2.0.0-snapshot.21 → 2.0.0-snapshot.23

package/dist/agent/agent-read-runtime.js

@@ -0,0 +1,320 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { clone, create, equals } from "@bufbuild/protobuf";
+import { AnySchema } from "@bufbuild/protobuf/wkt";
+import { AnyMessages, TypeUrls } from "@spine-event-engine/core";
+import { QuerySchema } from "@spine-event-engine/proto/client";
+import { AgentExecutionJournalEntrySchema as JournalEntrySchema, AgentExecutionScopeSchema, AgentHistoryReadKind, AgentHistoryReadPageSchema as ReadPageSchema, AgentHistoryReadRequestSchema as ReadRequestSchema, AgentProjectionReadResultSchema as ProjectionResultSchema, AgentReadSnapshotSchema, } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { AgentExecutionSizes, } from "@spine-event-engine/storage/provider";
+import { AgentExecutionFault } from "./agent-execution-fault.js";
+/**
+ * Reuses complete indexed pages under one handler's fenced journal.
+ */
+export class AgentReadRuntime {
+    session;
+    handlerOrdinal;
+    #cursor = 0;
+    #pending = 0;
+    #tail = Promise.resolve();
+    /**
+     * Creates a read sequencer for one handler invocation.
+     *
+     * @param session Fenced execution journal for this invocation.
+     * @param handlerOrdinal Ordinal of the handler within the accepted delivery.
+     */
+    constructor(session, handlerOrdinal) {
+        this.session = session;
+        this.handlerOrdinal = handlerOrdinal;
+    }
+    /**
+     * Returns one saved page or persists a live page before the handler sees it.
+     *
+     * @param scope Accepted Agent instance for this read.
+     * @param view History view selected by the handler.
+     * @param request Requested page and cursor.
+     * @param live Performs the live read when no saved page exists.
+     * @param maxBytes Maximum size of a live history page.
+     * @returns The saved or newly persisted page.
+     */
+    history(scope, view, request, live, maxBytes) {
+        this.#pending++;
+        const read = this.#tail.then(() => this.#history(scope, view, request, live, maxBytes));
+        this.#tail = read.then(() => undefined, () => undefined);
+        return read.finally(() => {
+            this.#pending--;
+        });
+    }
+    /**
+     * Returns saved typed projection states or persists a live query result.
+     *
+     * @typeParam Schema Schema of each returned projection state.
+     * @param schema Projection state schema.
+     * @param query Typed query to replay or execute.
+     * @param live Performs the live query when no saved result exists.
+     * @returns The saved or newly persisted projection states.
+     */
+    query(schema, query, live) {
+        this.#pending++;
+        const read = this.#tail.then(() => this.#query(schema, query, live));
+        this.#tail = read.then(() => undefined, () => undefined);
+        return read.finally(() => {
+            this.#pending--;
+        });
+    }
+    /**
+     * Handles a projection read in the same call-order sequence as history reads.
+     *
+     * @typeParam Schema Schema of the projection states.
+     */
+    async #query(schema, query, live) {
+        if (query.target?.type !== TypeUrls.derive(schema))
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Agent projection query target type changed.");
+        const name = `query:${String(this.#cursor)}`;
+        const prior = this.#savedReads()[this.#cursor];
+        if (prior !== undefined) {
+            const states = this.#replayQuery(prior, name, schema, query);
+            this.#cursor++;
+            return states;
+        }
+        this.#checkBudget(this.session.record());
+        const states = await live();
+        await this.#saveQuery(name, query, schema, states);
+        this.#cursor++;
+        return states;
+    }
+    /**
+     * Reuses typed states after comparing every request field except generated ID.
+     *
+     * @typeParam Schema Schema of the saved projection states.
+     */
+    #replayQuery(prior, name, schema, query) {
+        const scope = this.session.record().accepted?.key?.scope;
+        const saved = prior.request === undefined ? undefined : AnyMessages.unpack(prior.request, QuerySchema);
+        if (saved?.id === undefined ||
+            scope === undefined ||
+            prior.readName !== name ||
+            prior.scope === undefined ||
+            !equals(AgentExecutionScopeSchema, prior.scope, scope))
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Agent projection query request or scope changed on recovery.");
+        const normalized = clone(QuerySchema, query);
+        normalized.id = saved.id;
+        if (!equals(QuerySchema, normalized, saved))
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Agent projection query request changed on recovery.");
+        return this.#savedQueryStates(prior, schema);
+    }
+    /**
+     * Decodes only states matching the requested generated Projection schema.
+     *
+     * @typeParam Schema Generated state schema requested by the handler.
+     * @param prior Saved read entry with its typed result.
+     * @param schema Expected Projection state schema.
+     * @returns Independent retained state messages.
+     */
+    #savedQueryStates(prior, schema) {
+        const result = prior.result === undefined
+            ? undefined
+            : AnyMessages.unpack(prior.result, ProjectionResultSchema);
+        if (result === undefined)
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Saved Agent projection result is absent.");
+        return Object.freeze(result.states.map((packed) => {
+            const state = AnyMessages.unpack(packed, schema);
+            if (state === undefined)
+                throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Saved Agent projection state type changed.");
+            return state;
+        }));
+    }
+    /**
+     * Persists typed projection states before exposing them to a handler.
+     *
+     * @typeParam Schema Schema of the states being saved.
+     */
+    async #saveQuery(name, query, schema, states) {
+        const request = AnyMessages.pack(QuerySchema, query);
+        const result = this.#queryResult(schema, states);
+        await this.session.update((record) => {
+            const scope = record.accepted?.key?.scope;
+            if (scope === undefined)
+                throw new Error("Agent query requires accepted scope.");
+            this.#checkBudget(record);
+            record.journal.push(create(JournalEntrySchema, {
+                ordinal: BigInt(record.journal.length),
+                evidence: {
+                    case: "read",
+                    value: create(AgentReadSnapshotSchema, {
+                        handlerOrdinal: this.handlerOrdinal,
+                        readName: name,
+                        scope,
+                        request,
+                        result,
+                    }),
+                },
+            }));
+            this.#checkCapacity(record);
+            return record;
+        });
+    }
+    /**
+     * Packs the exact typed state array returned by a Projection read.
+     *
+     * @typeParam Schema Schema of the states being saved.
+     * @param schema Generated state descriptor.
+     * @param states Ordered states returned by the live query.
+     * @returns Typed saved query result envelope.
+     */
+    #queryResult(schema, states) {
+        return AnyMessages.pack(ProjectionResultSchema, create(ProjectionResultSchema, {
+            states: states.map((state) => AnyMessages.pack(schema, state)),
+        }));
+    }
+    /**
+     * Processes reads in call order, including concurrent handler requests.
+     */
+    async #history(scope, view, request, live, maxBytes) {
+        this.#checkScope(scope);
+        const named = `history:${String(this.#cursor)}`;
+        const prepared = this.#request(view, request, maxBytes);
+        const prior = this.#savedReads()[this.#cursor];
+        if (prior !== undefined) {
+            const page = this.#replay(prior, named, prepared);
+            this.#cursor++;
+            return page;
+        }
+        this.#checkBudget(this.session.record());
+        const page = await live();
+        await this.#save(named, prepared, page);
+        this.#cursor++;
+        return page;
+    }
+    /**
+     * Rejects omitted saved reads after all handler methods have returned.
+     */
+    finish() {
+        if (this.#pending !== 0)
+            throw new Error("Agent history read is still in progress.");
+        if (this.#cursor !== this.#savedReads().length)
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Agent history read sequence changed on recovery.");
+    }
+    /**
+     * Ensures the read cannot escape its accepted Agent instance.
+     */
+    #checkScope(scope) {
+        const accepted = this.session.record().accepted?.key?.scope;
+        if (accepted?.stateType !== scope.repository || accepted.agentKey !== scope.entity)
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Agent history read scope changed on recovery.");
+    }
+    /**
+     * Encodes the complete public request and effective byte ceiling.
+     */
+    #request(view, request, maxBytes) {
+        if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes <= 0))
+            throw new RangeError("Agent history maxBytes must be a positive safe integer.");
+        const kind = {
+            full: AgentHistoryReadKind.AGENT_HISTORY_READ_FULL,
+            conversation: AgentHistoryReadKind.AGENT_HISTORY_READ_CONVERSATION,
+            system: AgentHistoryReadKind.AGENT_HISTORY_READ_SYSTEM,
+            domain: AgentHistoryReadKind.AGENT_HISTORY_READ_DOMAIN,
+        }[view.kind];
+        return AnyMessages.pack(ReadRequestSchema, create(ReadRequestSchema, {
+            kind,
+            ...(view.kind === "conversation" ? { conversation: view.conversation } : {}),
+            pageSize: BigInt(request.pageSize),
+            ...(request.cursor === undefined ? {} : { cursor: request.cursor }),
+            ...(maxBytes === undefined ? {} : { maxBytes: BigInt(maxBytes) }),
+        }));
+    }
+    /**
+     * Selects this handler's saved reads in original call order.
+     */
+    #savedReads() {
+        return this.session
+            .record()
+            .journal.flatMap((entry) => entry.evidence.case === "read" &&
+            entry.evidence.value.handlerOrdinal === this.handlerOrdinal
+            ? [entry.evidence.value]
+            : []);
+    }
+    /**
+     * Returns exact prior content without consulting current provider state.
+     */
+    #replay(prior, name, request) {
+        const scope = this.session.record().accepted?.key?.scope;
+        if (prior.readName !== name ||
+            scope === undefined ||
+            prior.scope === undefined ||
+            prior.request === undefined ||
+            !equals(AnySchema, prior.request, request) ||
+            !equals(AgentExecutionScopeSchema, prior.scope, scope))
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Agent history read request or scope changed on recovery.");
+        const page = prior.result === undefined ? undefined : AnyMessages.unpack(prior.result, ReadPageSchema);
+        if (page === undefined)
+            throw new AgentExecutionFault("REPLAY_DIVERGENCE", "Saved Agent history page is absent or changed.");
+        return { entries: page.entries, hasMore: page.hasMore };
+    }
+    /**
+     * Saves a complete page under the provider claim before returning it.
+     */
+    async #save(name, request, page) {
+        await this.session.update((record) => {
+            const scope = record.accepted?.key?.scope;
+            if (scope === undefined)
+                throw new Error("Agent history read requires accepted scope.");
+            this.#checkBudget(record);
+            record.journal.push(this.#entry(record.journal.length, scope, name, request, page));
+            this.#checkCapacity(record);
+            return record;
+        });
+    }
+    /**
+     * Counts both history and projection snapshots against one invocation bound.
+     */
+    #checkBudget(record) {
+        const count = record.journal.filter((entry) => entry.evidence.case === "read").length;
+        const limit = record.started?.bounds?.recordedReads;
+        if (limit !== undefined && BigInt(count) >= limit)
+            throw new AgentExecutionFault("READ_BUDGET_EXCEEDED", "Agent recorded read budget is exhausted.");
+    }
+    /**
+     * Constructs the complete recorded read page with its call-order name.
+     */
+    #entry(ordinal, scope, name, request, page) {
+        return create(JournalEntrySchema, {
+            ordinal: BigInt(ordinal),
+            evidence: {
+                case: "read",
+                value: create(AgentReadSnapshotSchema, {
+                    handlerOrdinal: this.handlerOrdinal,
+                    readName: name,
+                    scope,
+                    request,
+                    result: AnyMessages.pack(ReadPageSchema, create(ReadPageSchema, {
+                        entries: [...page.entries],
+                        hasMore: page.hasMore,
+                    })),
+                }),
+            },
+        });
+    }
+    /**
+     * Rejects a page whose full persisted journal exceeds runtime or provider bounds.
+     */
+    #checkCapacity(record) {
+        const size = AgentExecutionSizes.record(record);
+        const providerLimit = this.session.capacity().executionRecordBytes;
+        const configuredLimit = record.started?.bounds?.maxRecoveryBytes;
+        if ((configuredLimit !== undefined && BigInt(size) > configuredLimit) ||
+            (providerLimit !== undefined && size > providerLimit))
+            throw new Error("Agent read snapshot exceeds durable record bytes.");
+    }
+}
+//# sourceMappingURL=agent-read-runtime.js.map

package/dist/agent/agent-read-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-read-runtime.js","sourceRoot":"","sources":["../../src/agent/agent-read-runtime.ts"],"names":[],"mappings":"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"}

package/dist/agent/agent-revisions.d.ts

@@ -0,0 +1,35 @@
+import type { AiRegistry } from "@spine-event-engine/ai";
+import type { DescriptorMessageSchema } from "../entity/entity-metadata.js";
+import type { RegisteredHandlerMetadata } from "../handler/handler-metadata.js";
+import type { RepositoryAiOptions } from "../repository/repository.js";
+/**
+ * Exact generated-schema and effective-policy revisions at Agent admission.
+ */
+export interface AgentAdmissionRevisions {
+    /**
+     * Digest of the selected state, signal, and capability descriptors.
+     */
+    readonly schema: string;
+    /**
+     * Digest of effective registry and repository capability policy.
+     */
+    readonly policy: string;
+}
+interface AgentRevisionsAccess {
+    /**
+     * Calculates admission revisions from generated descriptors and configured policy.
+     *
+     * @param state Generated Agent state descriptor.
+     * @param handlers Selected original handler bindings.
+     * @param ai Effective Bounded Context AI registry.
+     * @param repository Repository capability configuration.
+     * @returns Revisions compared when accepted work resumes.
+     */
+    atAdmission(state: DescriptorMessageSchema, handlers: readonly RegisteredHandlerMetadata[], ai: AiRegistry, repository: RepositoryAiOptions): AgentAdmissionRevisions;
+}
+/**
+ * Derives restart comparison keys without retaining application callbacks.
+ */
+export declare const AgentRevisions: AgentRevisionsAccess;
+export {};
+//# sourceMappingURL=agent-revisions.d.ts.map

package/dist/agent/agent-revisions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-revisions.d.ts","sourceRoot":"","sources":["../../src/agent/agent-revisions.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAOzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,oBAAoB;IAC5B;;;;;;;;OAQG;IACH,WAAW,CACT,KAAK,EAAE,uBAAuB,EAC9B,QAAQ,EAAE,SAAS,yBAAyB,EAAE,EAC9C,EAAE,EAAE,UAAU,EACd,UAAU,EAAE,mBAAmB,GAC9B,uBAAuB,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,oBAoC3B,CAAC"}

package/dist/agent/agent-revisions.js

@@ -0,0 +1,133 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { createHash } from "node:crypto";
+import { toBinary } from "@bufbuild/protobuf";
+import { FileDescriptorProtoSchema } from "@bufbuild/protobuf/wkt";
+import { mcpDefinition, mcpRegistrations, registryOptions, } from "@spine-event-engine/ai/spi/runtime";
+/**
+ * Derives restart comparison keys without retaining application callbacks.
+ */
+export const AgentRevisions = Object.freeze({
+    /**
+     * Computes descriptor and effective-policy digests for accepted work.
+     *
+     * @param state Generated Agent state descriptor.
+     * @param handlers Selected handler bindings in execution order.
+     * @param ai Effective Bounded Context AI registry.
+     * @param repository Repository capability configuration.
+     * @returns Revisions persisted for recovery comparison.
+     */
+    atAdmission(state, handlers, ai, repository) {
+        const schemas = [
+            state,
+            ...handlers.map((entry) => entry.handler.schema),
+            ...repository.models.flatMap((model) => [model.definition.input, model.definition.output]),
+        ];
+        const files = new Map(schemas.map((schema) => [schema.file.proto.name, schema.file.proto]));
+        const schemaHash = createHash("sha256");
+        for (const name of [...files.keys()].sort()) {
+            schemaHash.update(name);
+            const file = files.get(name);
+            if (file === undefined)
+                throw new Error("Agent descriptor disappeared during admission.");
+            schemaHash.update(toBinary(FileDescriptorProtoSchema, file));
+        }
+        return Object.freeze({
+            schema: schemaHash.digest("hex"),
+            policy: createHash("sha256")
+                .update(JSON.stringify(policyShape(ai, repository)))
+                .digest("hex"),
+        });
+    },
+});
+/**
+ * Selects serializable policy fields while callback revisions remain in codeRevision.
+ *
+ * @param ai Effective registry.
+ * @param repository Repository capabilities and narrowing policy.
+ * @returns Ordered policy value for a deterministic digest.
+ */
+function policyShape(ai, repository) {
+    const options = registryOptions(ai);
+    return {
+        defaults: options.defaultModels,
+        limits: options.invocationLimits,
+        hookTimeoutMs: options.hookTimeoutMs,
+        repositoryDefaults: repository.defaultModels,
+        allowedModels: repository.allowedModels,
+        invocationLimits: repository.invocationLimits,
+        mcpServers: mcpPolicies(ai, repository),
+        models: repository.models.map(({ definition }) => ({
+            name: definition.name,
+            version: definition.version,
+            kind: definition.kind,
+            input: definition.input.typeName,
+            output: definition.output.typeName,
+            limits: definition.limits,
+            validationVersion: definition.validation?.version,
+            ...(definition.kind === "generation"
+                ? {
+                    instructions: definition.instructions,
+                    outputMode: definition.outputMode,
+                    tools: definition.tools,
+                }
+                : {
+                    questions: definition.questions,
+                    mappingVersion: definition.mapping.version,
+                    requireProbabilities: definition.requireProbabilities,
+                    requireIndependentQuestions: definition.requireIndependentQuestions,
+                }),
+        })),
+    };
+}
+/**
+ * Hashes only available tools and their server policy without evaluating credential callbacks.
+ *
+ * @param ai Effective AI registry with registered tool servers.
+ * @param repository Model capabilities available to this Agent repository.
+ * @returns Deterministically ordered serializable server policies.
+ */
+function mcpPolicies(ai, repository) {
+    const selected = repository.models.flatMap(({ definition }) => definition.kind === "generation" ? (definition.tools ?? []) : []);
+    return mcpRegistrations(ai)
+        .filter((registration) => selected.some((ref) => ref.server === mcpDefinition(registration).id))
+        .map((registration) => {
+        const server = mcpDefinition(registration);
+        const transport = server.transport.kind === "streamable-http"
+            ? { kind: server.transport.kind, url: server.transport.url }
+            : {
+                kind: server.transport.kind,
+                executable: server.transport.executable,
+                args: server.transport.args,
+                cwd: server.transport.cwd,
+            };
+        return {
+            id: server.id,
+            revision: server.revision,
+            transport,
+            tools: Object.entries(server.tools)
+                .filter(([name]) => selected.some((ref) => ref.server === server.id && ref.tool === name))
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([name, policy]) => ({
+                name,
+                effect: policy.effect,
+                timeoutMs: policy.timeoutMs,
+                maxArgumentBytes: policy.maxArgumentBytes,
+                maxResultBytes: policy.maxResultBytes,
+            })),
+        };
+    })
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+//# sourceMappingURL=agent-revisions.js.map

package/dist/agent/agent-revisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-revisions.js","sourceRoot":"","sources":["../../src/agent/agent-revisions.ts"],"names":[],"mappings":"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"}

package/dist/agent/agent-scheduler.d.ts

@@ -0,0 +1,99 @@
+import { type AgentInvocationKey } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { TenantId } from "@spine-event-engine/proto";
+import type { AgentPendingCursor, AgentPendingPage, TenantCatalogCursor } from "@spine-event-engine/storage/provider";
+import type { TenantIndexPage } from "../context/tenant-index.js";
+import { AgentExecutionCapacity } from "./agent-execution-capacity.js";
+/**
+ * One complete repository and tenant visited by the Agent scheduler.
+ */
+export interface AgentScanScope {
+    /**
+     * Identifies one repository and tenant scan scope.
+     */
+    readonly id: string;
+    /**
+     * Reads a finite page of unresolved Agent invocations.
+     *
+     * @param after Provider continuation from the prior page.
+     * @param count Maximum records requested for this scan.
+     * @returns Pending records and their next continuation.
+     */
+    pending(after: AgentPendingCursor | undefined, count: number): Promise<AgentPendingPage>;
+    /**
+     * Executes one invocation after attempting its provider claim.
+     *
+     * @param key Exact accepted invocation selected by the scan.
+     * @param signal Bounded Context shutdown cancellation signal.
+     * @returns Completion after the claimed work settles.
+     */
+    run(key: AgentInvocationKey, signal: AbortSignal): Promise<void>;
+}
+/**
+ * Produces finite tenant pages and lazily constructs registered scopes.
+ */
+export interface AgentScopeSource {
+    /**
+     * Number of registered Agent repository views per tenant.
+     */
+    readonly repositories: number;
+    /**
+     * Reads one bounded tenant catalog page.
+     *
+     * @param after Opaque provider continuation from the prior page.
+     * @param signal Scheduler shutdown signal.
+     * @returns Complete tenant IDs and a possible continuation.
+     */
+    page(after: TenantCatalogCursor | undefined, signal: AbortSignal): Promise<TenantIndexPage>;
+    /**
+     * Creates one registered repository scope for a selected tenant.
+     *
+     * @param tenant Complete tenant identifier.
+     * @param repository Index in the fixed registered repository list.
+     * @returns A lazily constructed scan scope.
+     */
+    scope(tenant: TenantId, repository: number): AgentScanScope;
+}
+/**
+ * Bounded, round-robin scan of provider-indexed Agent heads.
+ */
+export declare class AgentScheduler {
+    #private;
+    private readonly source;
+    private readonly capacity;
+    private readonly onError;
+    /**
+     * Creates bounded discovery for the Bounded Context's registered Agent scopes.
+     *
+     * @param source Pages tenants and constructs a registered scope on demand.
+     * @param capacity Shared registry execution gate.
+     * @param onError Reports failed discovery or execution turns.
+     */
+    constructor(source: AgentScopeSource, capacity: AgentExecutionCapacity, onError: (error: unknown) => void);
+    /**
+     * Starts periodic discovery, including pending work after process reconstruction.
+     */
+    start(): void;
+    /**
+     * Schedules a prompt bounded turn without resetting the fixed-time sweep.
+     *
+     * @param scope Newly accepted repository and tenant, when available.
+     */
+    wake(scope?: AgentScanScope): void;
+    /**
+     * Reads at most four indexed pages and retains continuation across turns.
+     *
+     * @returns Completion after this bounded scan, or the scan already in progress.
+     */
+    turn(): Promise<void>;
+    /**
+     * Stops discovery and waits for already dispatched bounded work.
+     */
+    stop(): void;
+    /**
+     * Waits for dispatched work after stopping new discovery.
+     *
+     * @returns Completion after active work has settled.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=agent-scheduler.d.ts.map

package/dist/agent/agent-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-scheduler.d.ts","sourceRoot":"","sources":["../../src/agent/agent-scheduler.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,+EAA+E,CAAC;AACvF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEzF;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5F;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC;CAC7D;AAmBD;;GAEG;AACH,qBAAa,cAAc;;IA6CvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B;;;;;;OAMG;gBAEgB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAGpD;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI;IAelC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiR3B;;OAEG;IACH,IAAI,IAAI,IAAI;IAWZ;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}