@hue-run/sdk 0.19.1 → 0.20.1

package/dist/world/readiness.d.ts

@@ -0,0 +1,18 @@
+/** Progress of one requested starting World. */
+export interface WorldPreparationProgress {
+    /** Whether the request is preparing, usable, or waiting for changed evidence or dependencies. */
+    state: "preparing" | "insufficient_evidence" | "processing_limit" | "dependency_unavailable" | "ready";
+    /** Evidence cutoff selected for this request. */
+    selectedEvidenceCutoff: number;
+    /** Latest retained evidence cutoff. */
+    retainedEvidenceCutoff: number;
+    /** Latest indexed evidence cutoff for the current interpretation. */
+    readyEvidenceCutoff: number;
+    /** Whether retained evidence is still waiting for indexing. */
+    pendingEvidence: boolean;
+}
+/** Retained and indexed progress of an entity history. */
+export interface WorldModelProcessing extends Omit<WorldPreparationProgress, "state" | "selectedEvidenceCutoff"> {
+    /** Indexing progress; a requested represented time may still lack required evidence. */
+    state: "indexed" | "preparing" | "insufficient_evidence" | "processing_limit" | "dependency_unavailable";
+}

package/dist/world/readiness.js

@@ -0,0 +1,69 @@
+const diagnosticStates = {
+    world_preparing: "preparing",
+    world_insufficient_evidence: "insufficient_evidence",
+    world_processing_limit: "processing_limit",
+    world_dependency_unavailable: "dependency_unavailable",
+};
+/** @internal Only numeric progress and an allowlisted state cross the error boundary. */
+export async function readWorldPreparation(response, diagnostic) {
+    if (response.status !== 503 || diagnostic === undefined || !(diagnostic in diagnosticStates)) {
+        await response.body?.cancel().catch(() => { });
+        return undefined;
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return undefined;
+    try {
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 16 * 1024)
+                return undefined;
+            chunks.push(value);
+        }
+        const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!body || typeof body !== "object" || !("preparation" in body))
+            return undefined;
+        const value = body.preparation;
+        if (!value || typeof value !== "object")
+            return undefined;
+        const { state, selectedEvidenceCutoff: selected, retainedEvidenceCutoff: retained, readyEvidenceCutoff: ready, pendingEvidence, } = value;
+        const expectedState = diagnosticStates[diagnostic];
+        if (expectedState === undefined ||
+            state !== expectedState ||
+            !Number.isSafeInteger(selected) ||
+            !Number.isSafeInteger(retained) ||
+            !Number.isSafeInteger(ready) ||
+            typeof selected !== "number" ||
+            typeof retained !== "number" ||
+            typeof ready !== "number" ||
+            selected < 0 ||
+            ready < 0 ||
+            selected > retained ||
+            ready > retained ||
+            pendingEvidence !== retained > ready)
+            return undefined;
+        return {
+            state: expectedState,
+            selectedEvidenceCutoff: selected,
+            retainedEvidenceCutoff: retained,
+            readyEvidenceCutoff: ready,
+            pendingEvidence,
+        };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
+/** @internal These failures require changed evidence or processing, not another identical call. */
+export const TERMINAL_WORLD_DIAGNOSTICS = new Set([
+    "world_insufficient_evidence",
+    "world_processing_limit",
+]);

package/dist/world/tools.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from "@opentelemetry/api";
+import type { HueClient } from "../client.js";
+import type { EnvironmentClient } from "./client.js";
+import type { ActionSchema, EnvironmentRun, JsonValue, Observation } from "./types.js";
+/** Framework-neutral callable generated from one environment action. */
+export interface EnvironmentTool {
+    /** Tool name. */
+    name: string;
+    /** Agent-visible description. */
+    description?: string;
+    /** JSON Schema input contract. */
+    inputSchema: ActionSchema;
+    /** Executes the action and resolves with the world's observation. */
+    execute(args?: Record<string, JsonValue>): Promise<Observation>;
+}
+/** Dependencies and tracing context for {@link bindEnvironmentTools}. */
+export interface BindEnvironmentToolsOptions {
+    /** Hue client used to record each action as tool telemetry. */
+    hue: HueClient;
+    /** Environment client bound to the same Hue origin. */
+    client: Pick<EnvironmentClient, "act">;
+    /** Fresh environment run whose closed catalog becomes callables. */
+    run: EnvironmentRun;
+    /** Optional parent span context for generated tool spans. */
+    parentContext?: Context;
+    /** Optional durable invocation-ID factory for caller-owned resume state. */
+    invocationId?(action: string): string;
+}
+/**
+ * Binds a run's generated catalog to plain local callables without changing the agent
+ * framework. Each call is recorded through {@link HueClient.tool}. Catalog entries that
+ * include `mcp` stamp `mcp.server.name` / `mcp.server.version` and `hue.mcp.provider` /
+ * `hue.mcp.surface` so a generic verb is attributed to that MCP server and Hue surface.
+ */
+export declare function bindEnvironmentTools(options: BindEnvironmentToolsOptions): Record<string, EnvironmentTool>;

package/dist/world/tools.js

@@ -0,0 +1,30 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Binds a run's generated catalog to plain local callables without changing the agent
+ * framework. Each call is recorded through {@link HueClient.tool}. Catalog entries that
+ * include `mcp` stamp `mcp.server.name` / `mcp.server.version` and `hue.mcp.provider` /
+ * `hue.mcp.surface` so a generic verb is attributed to that MCP server and Hue surface.
+ */
+export function bindEnvironmentTools(options) {
+    const tools = {};
+    for (const action of options.run.actions) {
+        tools[action.name] = {
+            name: action.name,
+            ...(action.description === undefined ? {} : { description: action.description }),
+            inputSchema: action.inputSchema,
+            execute: async (args = {}) => {
+                const invocationId = options.invocationId?.(action.name) ?? randomUUID();
+                const execute = async () => (await options.client.act(options.run.id, {
+                    invocationId,
+                    action: action.name,
+                    args,
+                })).observation;
+                return options.hue.tool(action.name, args, execute, {
+                    parentContext: options.parentContext,
+                    ...(action.mcp === undefined ? {} : { mcp: action.mcp }),
+                });
+            },
+        };
+    }
+    return tools;
+}