@tangle-network/agent-provider-tangle 0.9.0 → 0.11.0

package/dist/tangle-interaction-response.js

@@ -0,0 +1,169 @@
+import { InteractionAcknowledgementSchema, InteractionRequestSchema, InteractionResponseCommandSchema, validateInteractionResponse, } from "@tangle-network/agent-interface";
+import { awaitWithSignal } from "./tangle-contract-safety.js";
+import { assertOptionKeys } from "./tangle-environment-validation.js";
+/**
+ * Build one acknowledgement for a command this adapter refuses on its own.
+ *
+ * The three identity members echo the command, so a caller matches the answer
+ * to the operation it sent. Optional members are written only when a value
+ * exists: the schema demands a message for the two statuses that cannot be
+ * read without one, and an absent `retryable` is a distinct fact from `false`.
+ */
+function acknowledge(command, status, extras = {}) {
+    return InteractionAcknowledgementSchema.parse({
+        operationId: command.operationId,
+        binding: command.binding,
+        commandDigest: command.commandDigest,
+        status,
+        ...(extras.message === undefined ? {} : { message: extras.message }),
+        ...(extras.retryable === undefined ? {} : { retryable: extras.retryable }),
+    });
+}
+/**
+ * The coordinates this environment can answer for. A command naming another
+ * provider, environment, or session is refused here rather than sent, because
+ * the Sandbox SDK rejects such a command by throwing, and a caller holding a
+ * durable operation needs the refusal as an acknowledgement it can record.
+ */
+function foreignBinding(command, options) {
+    const binding = command.binding;
+    if (binding.provider === options.provider &&
+        binding.environmentId === options.environmentId &&
+        binding.sessionId === options.sessionId) {
+        return undefined;
+    }
+    return acknowledge(command, "binding_mismatch", {
+        message: `response command binding names another provider, environment, or session than ${options.provider}/${options.environmentId}/${options.sessionId}`,
+    });
+}
+/**
+ * Refuse an answer the outstanding ask does not accept, naming every field the
+ * spec rejected.
+ *
+ * The deployment validates the same answer and is the authority, so this check
+ * exists for the message: a refusal that names the missing field reaches the
+ * caller instead of a bare rejection. It never invents a value for a field the
+ * caller left out — an incomplete answer is refused whole.
+ *
+ * An ask absent from the outstanding set is not refused here. It is the shape
+ * every already-resolved ask takes, and the deployment's durable record is the
+ * only thing that can tell a replay from an ask that never existed.
+ */
+async function specRefusal(command, options, signal) {
+    if (typeof options.session.interactions !== "function")
+        return undefined;
+    let outstanding;
+    try {
+        outstanding = await awaitWithSignal(options.session.interactions(signal ? { signal } : undefined), signal);
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        // The outstanding set is unreadable, so the spec cannot be checked here.
+        // The command still carries only what the caller supplied, and the
+        // deployment validates it against the same spec before any delivery.
+        console.warn(`Tangle interaction spec read failed for session ${options.sessionId}: the answer reaches the deployment unchecked`, error);
+        return undefined;
+    }
+    signal?.throwIfAborted();
+    if (!Array.isArray(outstanding))
+        return undefined;
+    const interactionId = command.binding.interactionId;
+    for (const entry of outstanding) {
+        const parsed = InteractionRequestSchema.safeParse(entry);
+        if (!parsed.success || parsed.data.id !== interactionId)
+            continue;
+        const validation = validateInteractionResponse(parsed.data, command.response);
+        if (validation.ok)
+            return undefined;
+        return acknowledge(command, "invalid_response", {
+            message: `interaction ${interactionId} rejected this answer: ${validation.errors.join("; ")}`,
+        });
+    }
+    return undefined;
+}
+/** Read the digest a conflicting resolution already holds, when it carries one. */
+function existingResponseDigest(result) {
+    const digest = result.serverResult?.existingResponseDigest;
+    return typeof digest === "string" && digest.length > 0 ? digest : undefined;
+}
+/**
+ * Whether the deployment recorded the response without confirming it reached
+ * the waiting agent. A recorded-but-undelivered resolution is not an accepted
+ * one, and reporting it as accepted would tell a caller an agent was released
+ * that is still blocked.
+ */
+function unconfirmedDelivery(result) {
+    return result.serverResult?.delivered === false;
+}
+/**
+ * Answer one exact interaction through the Sandbox interaction command route.
+ *
+ * The route carries the canonical command whole and returns the deployment's
+ * own durable record, so this adapter keeps no resolution record of its own:
+ * the deployment decides `accepted`, `already_resolved_same`, and
+ * `already_resolved_different`, and its answer survives a restart of this
+ * process and a rebuilt environment object. The capability this responder is
+ * gated on is exactly that durable record.
+ *
+ * Two verdicts stay here, because the route cannot produce them as an
+ * acknowledgement: a command bound to another environment or session, and an
+ * answer the outstanding ask's spec rejects.
+ */
+export function tangleInteractionResponder(options) {
+    return async (command, operation) => {
+        assertOptionKeys(operation, ["signal"], "Tangle interaction response");
+        // A command whose digest does not cover its own content is malformed, not
+        // refused: no acknowledgement can bind to a digest that names nothing.
+        const exactCommand = InteractionResponseCommandSchema.parse(command);
+        operation?.signal?.throwIfAborted();
+        const foreign = foreignBinding(exactCommand, options);
+        if (foreign)
+            return foreign;
+        const respond = options.session.respondToInteraction;
+        if (typeof respond !== "function") {
+            throw new Error("Tangle sandbox session cannot deliver an interaction response command");
+        }
+        const refusal = await specRefusal(exactCommand, options, operation?.signal);
+        if (refusal)
+            return refusal;
+        const result = await awaitWithSignal(respond.call(options.session, exactCommand, operation?.signal ? { signal: operation.signal } : undefined), operation?.signal);
+        operation?.signal?.throwIfAborted();
+        const acknowledgement = InteractionAcknowledgementSchema.parse(result?.acknowledgement);
+        if (acknowledgement.operationId !== exactCommand.operationId ||
+            acknowledgement.commandDigest !== exactCommand.commandDigest ||
+            acknowledgement.binding.interactionId !==
+                exactCommand.binding.interactionId ||
+            acknowledgement.binding.requestDigest !==
+                exactCommand.binding.requestDigest ||
+            acknowledgement.binding.sessionId !== exactCommand.binding.sessionId ||
+            acknowledgement.binding.environmentId !==
+                exactCommand.binding.environmentId ||
+            acknowledgement.binding.runId !== exactCommand.binding.runId ||
+            acknowledgement.binding.executionId !== exactCommand.binding.executionId ||
+            acknowledgement.binding.provider !== exactCommand.binding.provider) {
+            throw new Error("Tangle interaction response returned an acknowledgement for another operation");
+        }
+        if (acknowledgement.status === "accepted" && unconfirmedDelivery(result)) {
+            // The deployment recorded the resolution and did not confirm it reached
+            // the ask. The record makes a retry safe, and the caller must not read
+            // this as an answered ask.
+            return acknowledge(exactCommand, "transport_failure", {
+                message: `interaction ${exactCommand.binding.interactionId} is recorded but delivery is not confirmed`,
+                retryable: true,
+            });
+        }
+        if (acknowledgement.status === "already_resolved_different") {
+            const digest = existingResponseDigest(result);
+            if (digest !== undefined && !(acknowledgement.message ?? "").includes(digest)) {
+                return acknowledge(exactCommand, "already_resolved_different", {
+                    message: `${acknowledgement.message ??
+                        `interaction ${exactCommand.binding.interactionId} already holds another response`} (existing response digest ${digest})`,
+                    ...(acknowledgement.retryable === undefined
+                        ? {}
+                        : { retryable: acknowledgement.retryable }),
+                });
+            }
+        }
+        return acknowledgement;
+    };
+}

package/dist/tangle-observation.d.ts

@@ -0,0 +1,57 @@
+import type { AgentEnvironmentObservation, ResourceProfile, SafeEndpoint } from "@tangle-network/agent-interface";
+import type { SandboxClientLike, SandboxConnectionLike, SandboxInstanceLike } from "./tangle-types.js";
+import type { ExecutionUsageLog } from "./tangle-usage-log.js";
+/** Everything one observation reads, resolved when the environment is composed. */
+export interface TangleObservationSources {
+    box: SandboxInstanceLike;
+    client: SandboxClientLike;
+    provider: string;
+    environmentId: string;
+    /** Compute shape the caller asked for. Absent on an environment rebuilt by id. */
+    requestedResources?: ResourceProfile;
+    usageLog: ExecutionUsageLog;
+}
+/**
+ * Which observation surfaces this environment can put a value on.
+ *
+ * A flag is true only when a concrete source backs the surface for THIS
+ * sandbox. `identity` and `lifecycle` are unconditional because the sandbox id
+ * and status are always readable. `modelUsage` is unconditional for a
+ * different reason: the adapter measures the usage of every execution that
+ * runs through the handle, and reports the surface as unavailable until one
+ * completes. Every other flag rests on a source that can be absent.
+ */
+export interface ObservationSurfaceSupport {
+    identity: boolean;
+    lifecycle: boolean;
+    endpoint: boolean;
+    placement: boolean;
+    resources: boolean;
+    resourceUse: boolean;
+    modelUsage: boolean;
+    computeBilling: boolean;
+    accountUsage: boolean;
+}
+export declare function observationSurfaceSupport(box: SandboxInstanceLike, client: SandboxClientLike, requestedResources: ResourceProfile | undefined): ObservationSurfaceSupport;
+/**
+ * Account usage and the client-side placement surface are the only observation
+ * facts a client can establish before a sandbox exists. The rest rest on one
+ * environment's data, so a provider-stage document keeps them at the declared
+ * ceiling and each concrete sandbox measures them.
+ */
+export declare function clientObservationSurfaceSupport(client: SandboxClientLike): ObservationSurfaceSupport;
+/**
+ * Read the credential-free network location of the sandbox runtime.
+ *
+ * Only the scheme, host, and explicit port of the runtime URL are carried.
+ * Userinfo, path, and query are dropped, and the bearer beside the URL is
+ * never read, so an endpoint payload cannot transport a credential. A port the
+ * URL leaves to its scheme default is omitted rather than inferred. The result
+ * is held to the contract's own endpoint schema, so a runtime URL the contract
+ * refuses reads as no endpoint instead of failing the whole observation.
+ */
+export declare function safeEndpointFromConnection(connection: SandboxConnectionLike | undefined): SafeEndpoint | undefined;
+/** Build the normalized, freshness-tagged observation of one environment. */
+export declare function observeTangleEnvironment(sources: TangleObservationSources, options?: {
+    signal?: AbortSignal;
+}): Promise<AgentEnvironmentObservation>;