@laserdata/laser-sdk 0.0.1-rc.2 → 0.0.1-rc.22

package/dist/client/laser.js

@@ -0,0 +1,831 @@
+import { ApacheIggyTransport } from "../iggy/apache-iggy.js";
+import { createAgdx } from "../agent/agdx.js";
+import { decodeAgentMessage } from "../agent/reliable-consumer.js";
+import { ReplyHub } from "../agent/replies.js";
+import { ContractBuilder, scatter, scatterReport } from "../agent/contract.js";
+import { Workflow } from "../agent/workflow.js";
+import { aguiEvents, publishStateDelta, publishStateSnapshot, reconstructState } from "../bridges/agui.js";
+import { AgentScope } from "../agent/scope.js";
+import { ChunkAssembler } from "../agent/assembler.js";
+import { AgentRegistry, ClientMetadataRequest, encodePresenceInput, newRegistryCache } from "../agent/registry.js";
+import { AsyncOnce } from "../runtime/async-once.js";
+import { Stream } from "../stream/stream.js";
+import { ContextScope } from "../context-scope.js";
+import { ActionKind, GovernorState, encodePolicyEvidence, decodePolicyEvidence, POLICY_DECISION_OPERATION } from "../govern.js";
+import { MemoryBackend, MemoryHandle } from "../memory/handle.js";
+import { MemoryTopicBuilder } from "../memory/topic.js";
+import { NOOP_OBSERVER } from "../observe.js";
+import { executeBatch } from "../managed/batch.js";
+import { Fork } from "../managed/forks.js";
+import { Kv } from "../managed/kv.js";
+import { Bindings, Projections, Schemas } from "../managed/projections.js";
+import { QueryRequest } from "../managed/query.js";
+import { authzHistory, bindRoles, defineRole, deleteRole, getBindings, getRole, listRoles, whoami } from "../managed/rbac.js";
+import { GraphHandle } from "../managed/graph.js";
+import { Runs } from "../managed/runs.js";
+import { Watch } from "../managed/watch.js";
+import { AGDX_HELLO_CODE, AGDX_SET_CLIENT_METADATA_CODE, CONTROL_OP_VERSION } from "../wire/codes.js";
+import { QueryCommand } from "../wire/commands.js";
+import { encodeControlEnvelope } from "../wire/control.js";
+import { decodeBackendAnnounce } from "../wire/hello.js";
+import { AgentId, ConversationId } from "../types/ids.js";
+import { ownedBytes } from "./bytes.js";
+import { OPERATION_CARD, OPERATION_QUARANTINE, OPERATION_UNQUARANTINE, METADATA_DATA_CLASSIFICATION, METADATA_DELEGATED_BY, METADATA_PURPOSE, encodeAgentCard, validateAgentCard, AgentKind } from "../wire/agent.js";
+import { ContentType, contentTypeCode } from "../wire/content.js";
+import { CONTENT_TYPE } from "../wire/headers.js";
+import { IDEMPOTENCY_KEY } from "../wire/headers.js";
+import { AgentTopic } from "../provenance/agent-topic.js";
+import { encodeProvenanceHeaders, provenancePartitionKey } from "../provenance/provenance.js";
+import { CHANGES_TOPIC, CONTROL_TOPIC, DLQ_TOPIC, OPS_STREAM } from "../wire/topics.js";
+import { encodeNamed } from "../wire/cbor.js";
+import { ConfigError, NoStreamError, PresenceConflictError, ProtocolError, QueryExecutionError, InvalidError, UnsupportedError } from "./errors.js";
+import { executeManaged } from "./managed.js";
+import { INTERNAL_GOVERN, INTERNAL_REPLY_HUB, INTERNAL_TRANSPORT, INTERNAL_VERIFIER } from "./internals.js";
+import { OPEN_CAPABILITIES, managedCapabilitiesFrom, managedCapabilitiesWithUnknownVersions, servesConsistency } from "./capabilities.js";
+const LOCAL_CONNECTION_STRING = "iggy:iggy@127.0.0.1:8090";
+const DEFAULT_TOPOLOGY = {
+    opsStream: OPS_STREAM,
+    controlTopic: CONTROL_TOPIC,
+    deadLetterTopic: DLQ_TOPIC,
+    changesTopic: CHANGES_TOPIC
+};
+export class LaserBuilder {
+    create;
+    connectionStringValue;
+    addressValue;
+    credentialsValue;
+    clientValue;
+    ownershipValue = "borrowed";
+    defaultStreamValue;
+    capabilitiesValue;
+    governorValue;
+    observerValue = NOOP_OBSERVER;
+    verifierValue;
+    topologyValue = DEFAULT_TOPOLOGY;
+    constructor(create) {
+        this.create = create;
+    }
+    connectionString(value) {
+        this.connectionStringValue = value;
+        return this;
+    }
+    address(host, port = 8090) {
+        this.addressValue = { host, port };
+        return this;
+    }
+    credentials(username, password) {
+        this.credentialsValue = { kind: "usernamePassword", username, password };
+        return this;
+    }
+    token(value) {
+        this.credentialsValue = { kind: "token", token: value };
+        return this;
+    }
+    iggyClient(client, options = {}) {
+        this.clientValue = client;
+        this.ownershipValue = options.ownership ?? "borrowed";
+        return this;
+    }
+    defaultStream(value) {
+        this.defaultStreamValue = value;
+        return this;
+    }
+    capabilities(value) {
+        this.capabilitiesValue = value;
+        return this;
+    }
+    governor(policy, mode) {
+        this.governorValue = { policy, mode };
+        return this;
+    }
+    observer(value) {
+        this.observerValue = value;
+        return this;
+    }
+    verifier(value) {
+        this.verifierValue = value;
+        return this;
+    }
+    opsStream(value) {
+        this.topologyValue = { ...this.topologyValue, opsStream: value };
+        return this;
+    }
+    controlTopic(value) {
+        this.topologyValue = { ...this.topologyValue, controlTopic: value };
+        return this;
+    }
+    deadLetterTopic(value) {
+        this.topologyValue = { ...this.topologyValue, deadLetterTopic: value };
+        return this;
+    }
+    changesTopic(value) {
+        this.topologyValue = { ...this.topologyValue, changesTopic: value };
+        return this;
+    }
+    connect() {
+        const modes = Number(this.connectionStringValue !== undefined) +
+            Number(this.addressValue !== undefined) +
+            Number(this.clientValue !== undefined);
+        if (modes > 1) {
+            throw new ConfigError("connectionString(), address(), and iggyClient() are mutually exclusive");
+        }
+        if (this.credentialsValue !== undefined && this.addressValue === undefined) {
+            throw new ConfigError("credentials() and token() require address()");
+        }
+        if (this.addressValue !== undefined) {
+            const { host, port } = this.addressValue;
+            if (host.length === 0 || !Number.isInteger(port) || port <= 0 || port > 65_535) {
+                throw new ConfigError("address() requires a non-empty host and a valid TCP port");
+            }
+        }
+        const topologyEntries = [
+            ["opsStream", this.topologyValue.opsStream],
+            ["controlTopic", this.topologyValue.controlTopic],
+            ["deadLetterTopic", this.topologyValue.deadLetterTopic],
+            ["changesTopic", this.topologyValue.changesTopic]
+        ];
+        for (const [name, value] of topologyEntries) {
+            if (value.length === 0)
+                throw new ConfigError(`${name} must not be empty`);
+        }
+        return this.create({
+            ...(this.connectionStringValue !== undefined
+                ? { connectionString: this.connectionStringValue }
+                : {}),
+            ...(this.addressValue !== undefined ? { address: this.addressValue } : {}),
+            ...(this.credentialsValue !== undefined ? { credentials: this.credentialsValue } : {}),
+            ...(this.clientValue !== undefined ? { client: this.clientValue } : {}),
+            ownership: this.ownershipValue,
+            ...(this.defaultStreamValue !== undefined ? { defaultStream: this.defaultStreamValue } : {}),
+            ...(this.capabilitiesValue !== undefined ? { capabilities: this.capabilitiesValue } : {}),
+            ...(this.governorValue !== undefined ? { governor: this.governorValue } : {}),
+            observer: this.observerValue,
+            ...(this.verifierValue !== undefined ? { verifier: this.verifierValue } : {}),
+            topology: this.topologyValue
+        });
+    }
+}
+export { INTERNAL_GOVERN, INTERNAL_REPLY_HUB, INTERNAL_TRANSPORT, INTERNAL_VERIFIER } from "./internals.js";
+function newSharedState() {
+    return { registryCaches: new Map(), replyHubs: new Map() };
+}
+const WELL_KNOWN_AGENT_TOPICS = [
+    AgentTopic.Commands,
+    AgentTopic.Responses,
+    AgentTopic.ToolCalls,
+    AgentTopic.ToolResults,
+    AgentTopic.LlmIo,
+    AgentTopic.HumanInput,
+    AgentTopic.Audit,
+    AgentTopic.WorkflowJournal,
+    AgentTopic.Dlq,
+    AgentTopic.Registry
+];
+function actionKind(kind) {
+    switch (kind) {
+        case AgentKind.Command:
+            return ActionKind.Command;
+        case AgentKind.Response:
+            return ActionKind.Response;
+        case AgentKind.Event:
+            return ActionKind.Event;
+        case AgentKind.Status:
+            return ActionKind.Status;
+        case AgentKind.Error:
+            return ActionKind.Error;
+        case AgentKind.Chunk:
+            return ActionKind.Send;
+    }
+}
+function metadataString(envelope, key) {
+    const value = envelope.metadata?.get(key);
+    return value?.kind === "string" ? value.value : undefined;
+}
+function metadataActionFields(envelope) {
+    const onBehalfOf = metadataString(envelope, METADATA_DELEGATED_BY);
+    const purpose = metadataString(envelope, METADATA_PURPOSE);
+    const dataClassification = metadataString(envelope, METADATA_DATA_CLASSIFICATION);
+    return {
+        ...(onBehalfOf !== undefined ? { onBehalfOf } : {}),
+        ...(purpose !== undefined ? { purpose } : {}),
+        ...(dataClassification !== undefined ? { dataClassification } : {})
+    };
+}
+async function probeCapabilities(transport) {
+    let reply;
+    try {
+        reply = await transport.sendManaged(AGDX_HELLO_CODE, new Uint8Array());
+    }
+    catch {
+        return OPEN_CAPABILITIES;
+    }
+    if (reply.byteLength === 0) {
+        return managedCapabilitiesWithUnknownVersions();
+    }
+    try {
+        return managedCapabilitiesFrom(decodeBackendAnnounce(reply));
+    }
+    catch {
+        return managedCapabilitiesWithUnknownVersions();
+    }
+}
+/** Owns one Apache Iggy connection and addresses every stream available through it. */
+export class Laser {
+    transport;
+    defaultStream;
+    capabilitiesOnce;
+    shared;
+    observer;
+    governor;
+    verifier;
+    ownsClosure;
+    closed = false;
+    opsStream;
+    controlTopic;
+    deadLetterTopic;
+    changesTopic;
+    constructor(transport, defaultStream, capabilitiesOnce, shared, observer = NOOP_OBSERVER, governor, verifier, topology = DEFAULT_TOPOLOGY, ownsClosure = true) {
+        this.transport = transport;
+        this.defaultStream = defaultStream;
+        this.capabilitiesOnce = capabilitiesOnce;
+        this.shared = shared;
+        this.observer = observer;
+        this.governor = governor;
+        this.verifier = verifier;
+        this.ownsClosure = ownsClosure;
+        this.opsStream = topology.opsStream;
+        this.controlTopic = topology.controlTopic;
+        this.deadLetterTopic = topology.deadLetterTopic;
+        this.changesTopic = topology.changesTopic;
+    }
+    static builder() {
+        return new LaserBuilder(async (options) => {
+            let transport;
+            if (options.client !== undefined) {
+                transport = await ApacheIggyTransport.fromClient(options.client, options.ownership);
+            }
+            else if (options.address !== undefined) {
+                const credentials = options.credentials ?? {
+                    kind: "usernamePassword",
+                    username: "iggy",
+                    password: "iggy"
+                };
+                const userInfo = credentials.kind === "token"
+                    ? encodeURIComponent(credentials.token)
+                    : `${encodeURIComponent(credentials.username)}:${encodeURIComponent(credentials.password)}`;
+                const authorityHost = options.address.host.includes(":")
+                    ? `[${options.address.host.replace(/^\[|\]$/g, "")}]`
+                    : options.address.host;
+                transport = await ApacheIggyTransport.connect(`iggy://${userInfo}@${authorityHost}:${String(options.address.port)}`);
+            }
+            else {
+                transport = await ApacheIggyTransport.connect(options.connectionString ?? LOCAL_CONNECTION_STRING);
+            }
+            return new Laser(transport, options.defaultStream, options.capabilities === undefined
+                ? new AsyncOnce()
+                : AsyncOnce.resolved(options.capabilities), newSharedState(), options.observer, options.governor === undefined
+                ? undefined
+                : new GovernorState(options.governor.policy, options.governor.mode), options.verifier, options.topology);
+        });
+    }
+    static fromIggyClient(client, options = {}) {
+        const builder = Laser.builder()
+            .iggyClient(client, options.ownership === undefined ? {} : { ownership: options.ownership })
+            .capabilities(options.capabilities ?? OPEN_CAPABILITIES);
+        if (options.defaultStream !== undefined)
+            builder.defaultStream(options.defaultStream);
+        if (options.observer !== undefined)
+            builder.observer(options.observer);
+        return builder.connect();
+    }
+    static async connect(connectionString) {
+        const transport = await ApacheIggyTransport.connect(connectionString);
+        return new Laser(transport, undefined, new AsyncOnce(), newSharedState());
+    }
+    static async connectWithStream(connectionString, stream) {
+        const transport = await ApacheIggyTransport.connect(connectionString);
+        return new Laser(transport, stream, new AsyncOnce(), newSharedState());
+    }
+    static async connectEnv(env = process.env) {
+        const connectionString = env["LASER_CONNECTION_STRING"];
+        if (connectionString === undefined || connectionString.length === 0) {
+            throw new ConfigError("LASER_CONNECTION_STRING is not set");
+        }
+        const stream = env["LASER_STREAM"];
+        return stream === undefined || stream.length === 0
+            ? Laser.connect(connectionString)
+            : Laser.connectWithStream(connectionString, stream);
+    }
+    static async local() {
+        return Laser.connect(LOCAL_CONNECTION_STRING);
+    }
+    withDefaultStream(stream) {
+        return new Laser(this.transport, stream, this.capabilitiesOnce, this.shared, this.observer, this.governor, this.verifier, this.topology(), false);
+    }
+    withCapabilities(capabilities) {
+        return new Laser(this.transport, this.defaultStream, AsyncOnce.resolved(capabilities), this.shared, this.observer, this.governor, this.verifier, this.topology(), false);
+    }
+    withGovernor(governor, mode) {
+        return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, this.observer, new GovernorState(governor, mode), this.verifier, this.topology(), false);
+    }
+    withVerifier(verifier) {
+        return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, this.observer, this.governor, verifier, this.topology(), false);
+    }
+    withObserver(observer) {
+        return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, observer, this.governor, this.verifier, this.topology(), false);
+    }
+    topology() {
+        return {
+            opsStream: this.opsStream,
+            controlTopic: this.controlTopic,
+            deadLetterTopic: this.deadLetterTopic,
+            changesTopic: this.changesTopic
+        };
+    }
+    async observe(operation, attributes, effect) {
+        const span = this.observer.start(operation, attributes);
+        try {
+            const value = await effect();
+            span.end();
+            return value;
+        }
+        catch (error) {
+            span.end(error);
+            throw error;
+        }
+    }
+    managedTransport() {
+        return {
+            sendManaged: (commandCode, payload) => this.observe("laser.managed", { operation: "managed", commandCode }, () => this.transport.sendManaged(commandCode, payload))
+        };
+    }
+    async capabilities() {
+        return this.capabilitiesOnce.get(() => probeCapabilities(this.managedTransport()));
+    }
+    [INTERNAL_TRANSPORT]() {
+        return this.transport;
+    }
+    [INTERNAL_VERIFIER]() {
+        return this.verifier;
+    }
+    [INTERNAL_REPLY_HUB](topic) {
+        return this.replyHub(topic);
+    }
+    [INTERNAL_GOVERN](action) {
+        if (this.governor === undefined)
+            return Promise.resolve(action.payload.slice());
+        return this.governor.govern(action, (evidence) => this.emitPolicyEvidence(action.stream, evidence));
+    }
+    get iggyClient() {
+        return this.transport.iggyClient;
+    }
+    stream(name) {
+        return new Stream(this.transport, name, (stream, topic, payload, provenance) => this[INTERNAL_GOVERN]({
+            kind: ActionKind.Publish,
+            stream,
+            topic,
+            ...(provenance?.agent !== undefined ? { source: provenance.agent.asString() } : {}),
+            ...(provenance?.targetAgentId !== undefined
+                ? { target: provenance.targetAgentId.asString() }
+                : {}),
+            ...(provenance !== undefined ? { conversation: provenance.conversationId } : {}),
+            ...(provenance?.correlationId !== undefined
+                ? { correlation: provenance.correlationId }
+                : {}),
+            payload,
+            signed: false
+        }), async (schemaId) => (await this.schemas().get(schemaId))?.schema, (operation, attributes, effect) => this.observe(operation, attributes, effect));
+    }
+    topic(name) {
+        if (this.defaultStream === undefined) {
+            throw new NoStreamError("topic() requires a default stream, use stream(name).topic(name) or withDefaultStream(name)");
+        }
+        return this.stream(this.defaultStream).topic(name);
+    }
+    agdx(topic, source, conversation) {
+        if (this.defaultStream === undefined) {
+            throw new NoStreamError("agdx() requires a default stream, use connectWithStream() or withDefaultStream()");
+        }
+        const stream = this.defaultStream;
+        return createAgdx(this.transport, stream, topic, source, conversation, undefined, (envelope, willSign) => this[INTERNAL_GOVERN]({
+            kind: actionKind(envelope.kind),
+            stream,
+            topic,
+            source: envelope.source,
+            ...(envelope.target !== undefined ? { target: envelope.target } : {}),
+            conversation,
+            ...(envelope.correlation !== undefined
+                ? { correlation: envelope.correlation.toString() }
+                : {}),
+            ...(envelope.operation !== undefined ? { operation: envelope.operation } : {}),
+            ...(envelope.tool !== undefined ? { tool: envelope.tool } : {}),
+            ...metadataActionFields(envelope),
+            payload: envelope.body,
+            signed: willSign
+        }));
+    }
+    agent(id) {
+        return new AgentScope(this, id);
+    }
+    contract(router) {
+        return new ContractBuilder(this, router);
+    }
+    workflow(name) {
+        return new Workflow(this, name);
+    }
+    publishStateSnapshot(topic, source, conversation, state) {
+        return publishStateSnapshot(this, topic, source, conversation, state);
+    }
+    publishStateDelta(topic, source, conversation, patch) {
+        return publishStateDelta(this, topic, source, conversation, patch);
+    }
+    reconstructState(conversation, topic) {
+        return reconstructState(this, conversation, topic);
+    }
+    aguiEvents(conversation, topic) {
+        return aguiEvents(this, conversation, topic);
+    }
+    scatter(source, selector, payload, inboxRoute, deadlineMs) {
+        return scatter(this, source, selector, payload, inboxRoute, deadlineMs);
+    }
+    scatterReport(source, selector, payload, inboxRoute, deadlineMs) {
+        return scatterReport(this, source, selector, payload, inboxRoute, deadlineMs);
+    }
+    context(conversation) {
+        return new ContextScope(this, conversation);
+    }
+    memory(namespace) {
+        return this.memoryWith(namespace, MemoryBackend.Auto);
+    }
+    /** Opens durable memory on an existing caller-named topic. */
+    memoryOnTopic(topic, stream) {
+        return MemoryHandle.logTopic(this, topic, stream);
+    }
+    /** Configures a durable memory topic before opening it. */
+    memoryTopic(topic) {
+        return new MemoryTopicBuilder(this, topic);
+    }
+    memoryWith(namespace, backend, embedder) {
+        return backend === MemoryBackend.Vector
+            ? MemoryHandle.governedVector(this, embedder)
+            : MemoryHandle.log(this, namespace);
+    }
+    memoryCustom(memory) {
+        return MemoryHandle.custom(memory);
+    }
+    async bootstrap(partitions) {
+        const stream = this.requireDefaultStream("bootstrap()");
+        await this.observe("laser.bootstrap", { operation: "bootstrap", stream, partitions }, async () => {
+            await this.transport.ensureStream(stream);
+            await Promise.all(WELL_KNOWN_AGENT_TOPICS.map((topic) => this.transport.ensureTopic(stream, topic, partitions)));
+        });
+    }
+    async sendAgent(topic, payload, provenance, options = {}) {
+        const stream = this.requireDefaultStream("sendAgent()");
+        await this.observe("laser.agent.send", {
+            operation: "send",
+            stream,
+            topic,
+            conversation: provenance.conversationId.toString(),
+            ...(provenance.correlationId !== undefined
+                ? { correlation: provenance.correlationId }
+                : {}),
+            ...(provenance.agent !== undefined ? { agent: provenance.agent.asString() } : {})
+        }, async () => {
+            const governedPayload = await this[INTERNAL_GOVERN]({
+                kind: ActionKind.Send,
+                stream,
+                topic,
+                ...(provenance.agent !== undefined ? { source: provenance.agent.asString() } : {}),
+                ...(provenance.targetAgentId !== undefined
+                    ? { target: provenance.targetAgentId.asString() }
+                    : {}),
+                conversation: provenance.conversationId,
+                ...(provenance.correlationId !== undefined
+                    ? { correlation: provenance.correlationId }
+                    : {}),
+                payload: ownedBytes(payload),
+                signed: false
+            });
+            const headers = new Map(encodeProvenanceHeaders(provenance));
+            if (options.contentType !== undefined) {
+                headers.set(CONTENT_TYPE, {
+                    kind: "uint8",
+                    value: contentTypeCode(options.contentType)
+                });
+            }
+            await this.transport.sendMessageWithHeaders(stream, topic, governedPayload, headers, provenancePartitionKey(provenance));
+        });
+    }
+    async policyEvidence(conversation) {
+        const messages = await this.context(conversation).fetch([AgentTopic.Audit], Number.MAX_SAFE_INTEGER);
+        return messages.flatMap((message) => {
+            if (message.envelope?.operation !== POLICY_DECISION_OPERATION)
+                return [];
+            try {
+                return [decodePolicyEvidence(message.envelope.body)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    async emitPolicyEvidence(stream, evidence) {
+        const conversation = evidence.conversation === undefined
+            ? ConversationId.parse("00000000000000000000000000")
+            : ConversationId.parse(evidence.conversation);
+        const source = AgentId.new(evidence.source ?? "governor");
+        await createAgdx(this.transport, stream, AgentTopic.Audit, source, conversation)
+            .emit(encodePolicyEvidence(evidence))
+            .withOperation(POLICY_DECISION_OPERATION)
+            .contentType(ContentType.Cbor)
+            .send();
+    }
+    spawnSubconversation(parent) {
+        return {
+            conversationId: ConversationId.new(),
+            parentConversationId: parent.conversationId,
+            rootConversationId: parent.rootConversationId ?? parent.conversationId,
+            ...(parent.agent !== undefined ? { agent: parent.agent } : {})
+        };
+    }
+    async reassembleChannel(conversation, topic, channel) {
+        const cursor = await this.topic(topic).replay({ batchSize: 1_000 });
+        const envelopes = [];
+        for (;;) {
+            const records = await cursor.poll();
+            if (records.length === 0)
+                break;
+            for (const record of records) {
+                const decoded = decodeAgentMessage(record);
+                if (decoded.kind !== "message")
+                    continue;
+                const envelope = decoded.message.envelope;
+                if (envelope?.kind === AgentKind.Chunk &&
+                    envelope.conversation.toString() === conversation.toString() &&
+                    envelope.channel?.equals(channel) === true) {
+                    envelopes.push(envelope);
+                }
+            }
+        }
+        envelopes.sort((left, right) => {
+            const a = left.sequence ?? 0n;
+            const b = right.sequence ?? 0n;
+            return a < b ? -1 : a > b ? 1 : 0;
+        });
+        const assembler = new ChunkAssembler();
+        return envelopes.flatMap((envelope) => assembler.feed(envelope));
+    }
+    async consumed(target, at) {
+        if (this.transport.resolveStreamTopicNames === undefined ||
+            this.transport.getConsumerOffset === undefined) {
+            throw new UnsupportedError("the active Iggy transport cannot resolve consumer offsets");
+        }
+        const names = await this.transport.resolveStreamTopicNames(at.streamId, at.topicId);
+        if (names === undefined) {
+            return { kind: "notYetConsumed", behindBy: at.offset + 1n };
+        }
+        const consumer = target.kind === "group"
+            ? {
+                kind: "group",
+                name: typeof target.name === "string" ? target.name : target.name.asString()
+            }
+            : { kind: "consumer", name: target.name };
+        const offset = await this.transport.getConsumerOffset(names.stream, names.topic, consumer, at.partitionId);
+        if (offset === undefined)
+            return { kind: "notYetConsumed", behindBy: at.offset + 1n };
+        return offset.storedOffset >= at.offset
+            ? { kind: "consumed", committed: offset.storedOffset, head: offset.currentOffset }
+            : { kind: "notYetConsumed", behindBy: at.offset - offset.storedOffset };
+    }
+    async redriveDeadLetter(capsule) {
+        if (this.transport.resolveStreamTopicNames === undefined) {
+            throw new UnsupportedError("the active Iggy transport cannot resolve dead-letter sources");
+        }
+        const source = capsule.source;
+        const names = await this.transport.resolveStreamTopicNames(source.streamId, source.topicId);
+        if (names === undefined) {
+            throw new InvalidError("dead-letter source stream or topic no longer exists");
+        }
+        const records = await this.transport.pollMessages(names.stream, names.topic, { kind: "single", partitionId: source.partitionId }, { kind: "offset", value: source.offset }, 1, false);
+        const original = records.find((record) => record.offset === source.offset);
+        if (original === undefined) {
+            throw new InvalidError(`dead-letter source record at offset ${source.offset.toString()} is no longer on the log`);
+        }
+        const headers = new Map(original.headers);
+        const idempotency = headers.get(IDEMPOTENCY_KEY);
+        if (idempotency?.kind === "string") {
+            headers.set(IDEMPOTENCY_KEY, {
+                kind: "string",
+                value: `${idempotency.value}/redrive/${String(source.partitionId)}-${source.offset.toString()}`
+            });
+        }
+        const decoded = decodeAgentMessage(original);
+        const partitionKey = decoded.kind === "message" ? provenancePartitionKey(decoded.message.provenance) : undefined;
+        await this.transport.sendMessageWithHeaders(names.stream, names.topic, original.payload, headers, partitionKey);
+    }
+    async request(requestTopic, replyTopic, payload, provenance, timeoutMs, signal) {
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new InvalidError("request() timeout must be a non-negative finite number");
+        }
+        const correlationId = provenance.correlationId ?? ConversationId.new().toString();
+        const correlated = { ...provenance, correlationId };
+        const hub = await this.replyHub(replyTopic);
+        const ticket = hub.subscribe(correlationId);
+        try {
+            await this.sendAgent(requestTopic, payload, correlated);
+        }
+        catch (error) {
+            ticket.cancel();
+            throw error;
+        }
+        return ticket.wait(timeoutMs, signal);
+    }
+    clientMetadata() {
+        return new ClientMetadataRequest(this.transport);
+    }
+    async advertisePresence(presence) {
+        const requested = presence.agent.asString();
+        const advertised = this.shared.advertisedAgent;
+        if (advertised !== undefined && advertised !== requested) {
+            throw new PresenceConflictError(advertised, requested);
+        }
+        this.shared.advertisedAgent = requested;
+        await this.managedTransport().sendManaged(AGDX_SET_CLIENT_METADATA_CODE, encodePresenceInput(presence));
+    }
+    async clearPresence() {
+        await this.managedTransport().sendManaged(AGDX_SET_CLIENT_METADATA_CODE, new Uint8Array());
+        delete this.shared.advertisedAgent;
+    }
+    async agentRegistry() {
+        const stream = this.requireDefaultStream("agentRegistry()");
+        let cache = this.shared.registryCaches.get(stream);
+        if (cache === undefined) {
+            cache = newRegistryCache();
+            this.shared.registryCaches.set(stream, cache);
+        }
+        const cursor = await this.topic(AgentTopic.Registry).replay();
+        return new AgentRegistry(cursor, cache, () => this.clientMetadata(), undefined, this.verifier);
+    }
+    async publishCard(source, card) {
+        validateAgentCard(card);
+        const body = encodeNamed(encodeAgentCard(card));
+        await this.agdx(AgentTopic.Registry, source, ConversationId.new())
+            .status(OPERATION_CARD)
+            .body(body)
+            .contentType(ContentType.Cbor)
+            .send();
+    }
+    async quarantine(operator, agent) {
+        await this.publishRegistryFact(OPERATION_QUARANTINE, operator, agent);
+    }
+    async unquarantine(operator, agent) {
+        await this.publishRegistryFact(OPERATION_UNQUARANTINE, operator, agent);
+    }
+    async quarantineSigned(operator, agent, key) {
+        await this.publishRegistryFact(OPERATION_QUARANTINE, operator, agent, key);
+    }
+    async unquarantineSigned(operator, agent, key) {
+        await this.publishRegistryFact(OPERATION_UNQUARANTINE, operator, agent, key);
+    }
+    async publishRegistryFact(operation, operator, agent, key) {
+        let fact = this.agdx(AgentTopic.Registry, operator, ConversationId.new())
+            .status(operation)
+            .body(new TextEncoder().encode(agent.asString()));
+        if (key !== undefined)
+            fact = fact.signedBy(key);
+        await fact.send();
+    }
+    requireDefaultStream(operation) {
+        if (this.defaultStream === undefined) {
+            throw new NoStreamError(`${operation} requires a default stream, use connectWithStream() or withDefaultStream()`);
+        }
+        return this.defaultStream;
+    }
+    async replyHub(topic) {
+        const stream = this.requireDefaultStream("request()");
+        const key = `${stream}\u001f${topic}`;
+        let hub = this.shared.replyHubs.get(key);
+        if (hub === undefined) {
+            hub = ReplyHub.create(this.transport, stream, topic);
+            this.shared.replyHubs.set(key, hub);
+            void hub.catch(() => this.shared.replyHubs.delete(key));
+        }
+        return hub;
+    }
+    query(index) {
+        return new QueryRequest(index, (query) => this.executeQuery(query));
+    }
+    kv(namespace) {
+        return new Kv(this.managedTransport(), () => this.capabilities(), namespace);
+    }
+    async kvNamespaces() {
+        return Kv.namespaces(this.managedTransport(), () => this.capabilities());
+    }
+    async executeBatch(ops) {
+        const capabilities = await this.capabilities();
+        return executeBatch(this.managedTransport(), capabilities, ops);
+    }
+    fork(forkId) {
+        return new Fork(this.managedTransport(), () => this.capabilities(), forkId);
+    }
+    async forks() {
+        return Fork.forks(this.managedTransport(), () => this.capabilities());
+    }
+    projections() {
+        return new Projections(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
+    }
+    bindings() {
+        return new Bindings((command) => this.publishControl(command));
+    }
+    schemas() {
+        return new Schemas(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
+    }
+    runs() {
+        return new Runs(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
+    }
+    watch() {
+        return new Watch(() => this.capabilities(), (options) => this.stream(this.opsStream).topic(this.changesTopic).replay(options));
+    }
+    graph(name) {
+        return new GraphHandle(this.managedTransport(), () => this.capabilities(), name);
+    }
+    async whoami() {
+        return whoami(this.managedTransport(), await this.capabilities());
+    }
+    async listRoles(options) {
+        return listRoles(this.managedTransport(), await this.capabilities(), options);
+    }
+    async getRole(name) {
+        return getRole(this.managedTransport(), await this.capabilities(), name);
+    }
+    async getBindings(userId) {
+        return getBindings(this.managedTransport(), await this.capabilities(), userId);
+    }
+    async defineRole(role) {
+        return defineRole(this.managedTransport(), await this.capabilities(), role);
+    }
+    async deleteRole(name) {
+        return deleteRole(this.managedTransport(), await this.capabilities(), name);
+    }
+    async bindRoles(userId, roles, expectRevision) {
+        return bindRoles(this.managedTransport(), await this.capabilities(), userId, roles, expectRevision);
+    }
+    async authzHistory(subject, limit, afterRevision) {
+        return authzHistory(this.managedTransport(), await this.capabilities(), subject, limit, afterRevision);
+    }
+    async publishControl(command) {
+        const envelope = {
+            v: CONTROL_OP_VERSION,
+            timestampMicros: BigInt(Date.now()) * 1000n,
+            command
+        };
+        const payload = encodeNamed(encodeControlEnvelope(envelope));
+        await this.stream(this.opsStream)
+            .topic(this.controlTopic)
+            .send(payload, { key: new TextEncoder().encode("control") });
+    }
+    async executeQuery(query) {
+        const capabilities = await this.capabilities();
+        if (query.text !== undefined && !capabilities.query.keyword) {
+            throw new UnsupportedError("keyword query is not served by this deployment");
+        }
+        if (!servesConsistency(capabilities, query.consistency)) {
+            throw new UnsupportedError(`${query.consistency} query consistency is not served by this deployment`);
+        }
+        const reply = await executeManaged(this.managedTransport(), capabilities, QueryCommand, {
+            query
+        });
+        if (reply.kind === "ok")
+            return reply.result;
+        if (reply.kind === "unrecognized") {
+            throw new ProtocolError(`query returned unknown reply variant \`${reply.tag}\``, {
+                commandCode: QueryCommand.code
+            });
+        }
+        if (reply.error.kind === "unsupported") {
+            throw new UnsupportedError(reply.error.message);
+        }
+        throw new QueryExecutionError(`query failed: ${reply.error.kind}`, reply.error);
+    }
+    /** Closes owned transport resources. Safe to call more than once. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (!this.ownsClosure)
+            return;
+        const hubs = await Promise.allSettled(this.shared.replyHubs.values());
+        for (const hub of hubs) {
+            if (hub.status === "fulfilled")
+                hub.value.stop();
+        }
+        this.shared.replyHubs.clear();
+        await this.observe("laser.close", { operation: "close" }, () => this.transport.close());
+    }
+    /** Delegates async disposal to `close()`. */
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+}
+//# sourceMappingURL=laser.js.map