@nylorun/agents 0.9.0-beta → 0.11.0-beta

package/dist/served-definitions.js

@@ -0,0 +1,100 @@
+/** The definitions an application serves Actions for (`createActionHandler`). */
+import { AgentManifestSchema } from "@nylorun/core/contracts";
+import { agentFrom, delegateOf, hashManifest, isFlowDelegate, isBuiltWorkflow, } from "@nylorun/core/define";
+import { assertNoMiddlewareClosures } from "./client.js";
+import { env } from "./http.js";
+/** The implementation version to register: the option, `NYLORUN_IMPLEMENTATION_VERSION`, or `dev`. */
+export function implementationVersionOf(options) {
+    return (options.implementationVersion ??
+        env("NYLORUN_IMPLEMENTATION_VERSION") ??
+        "dev");
+}
+/** Agents embedded in a v2 workflow: served here, but saved only as part of the workflow. */
+const embeddedAgents = new WeakMap();
+/** The ids among `agents` that are saved only as part of another definition. */
+export function embeddedIn(agents) {
+    return embeddedAgents.get(agents) ?? new Set();
+}
+/**
+ * Every definition `sources` serves, by id: the agents and workflows passed in, the agents
+ * a v2 workflow embeds, and flow agents used as tools. `owner` names the caller in errors.
+ */
+export function buildAgents(sources, owner) {
+    const agents = new Map();
+    const embedded = new Set();
+    /**
+     * Agents embedded in another definition (a v2 flow's agents, a flow agent used as a
+     * tool) may be reached from more than one place; the same definition is served once.
+     */
+    const sameAsServed = (id, manifest) => {
+        const served = agents.get(id);
+        if (!served)
+            return false;
+        if (hashManifest(served.manifest) === hashManifest(manifest))
+            return true;
+        throw new Error(`Duplicate connected agent ${id}`);
+    };
+    const addAgent = (built, shared = false) => {
+        assertNoMiddlewareClosures(built);
+        AgentManifestSchema.parse(built.manifest);
+        if (shared ? sameAsServed(built.id, built.manifest) : agents.has(built.id)) {
+            if (!shared)
+                throw new Error(`Duplicate connected agent ${built.id}`);
+            return;
+        }
+        agents.set(built.id, built);
+        for (const tool of built.getBinding().tools) {
+            const delegate = delegateOf(tool);
+            if (!delegate || !isFlowDelegate(delegate))
+                continue;
+            // A flow agent used as a tool runs in its own linked session: serve its code too.
+            if (!delegate.workflow)
+                throw new Error(`Flow agent '${delegate.manifest.id}' is used as a tool by '${built.id}' but has no local implementation`);
+            addWorkflow(delegate.workflow, true);
+            embedded.add(delegate.workflow.id);
+        }
+    };
+    const addWorkflow = (workflow, shared = false) => {
+        if (shared ? sameAsServed(workflow.id, workflow.manifest) : agents.has(workflow.id)) {
+            if (!shared)
+                throw new Error(`Duplicate connected agent ${workflow.id}`);
+            return;
+        }
+        agents.set(workflow.id, workflow);
+        const v2 = workflow.manifest.workflowSchemaVersion === 2;
+        for (const binding of Object.values(workflow.getBinding().agents)) {
+            addAgent(agentFrom(binding.manifest, binding.implementations), v2);
+            if (v2)
+                embedded.add(binding.manifest.id);
+        }
+    };
+    for (const source of sources) {
+        if (isBuiltWorkflow(source)) {
+            addWorkflow(source);
+            continue;
+        }
+        const built = source.build?.() ?? source;
+        if (isBuiltWorkflow(built)) {
+            addWorkflow(built);
+            continue;
+        }
+        addAgent(built);
+    }
+    if (!agents.size)
+        throw new Error(`${owner} requires at least one agent`);
+    // A definition passed in directly is saved on its own, even if another one embeds it.
+    for (const source of sources)
+        embedded.delete(source.id);
+    embeddedAgents.set(agents, embedded);
+    return agents;
+}
+/**
+ * The manifest hash served for a workflow's flow actions. A run is pinned to one workflow
+ * manifest, and its stage keys may shift between deploys, so flow actions for another hash
+ * are left for whoever serves it.
+ */
+export function flowManifestHash(agent) {
+    return isBuiltWorkflow(agent) && agent.manifest.workflowSchemaVersion === 2
+        ? hashManifest(agent.manifest)
+        : undefined;
+}

package/dist/session-client.d.ts

@@ -0,0 +1,282 @@
+/**
+ * The Tenant API client classes, with no Node-only imports so a browser bundle can load them
+ * (`@nylorun/agents/browser`). `client.ts` adds `createClient`, which resolves the
+ * connection from the environment or the Project link.
+ */
+import type { AgentManifest, BuiltAgent, BuiltWorkflow, JsonValue, SandboxToolName, WorkflowManifest } from "@nylorun/core/define";
+import { type SubjectScope, type CredentialInfo, type CredentialSelection, type SandboxRequest, type SessionCommand, type VaultInfo } from "@nylorun/core/contracts";
+import { AccessClient, TokensClient } from "./access.js";
+import { Transport, type Destination } from "./http.js";
+/** Application-principal access to a session's sandbox built-ins (workflows.md §8). */
+export type SessionSandbox = {
+    readonly [K in SandboxToolName]: (args: Record<string, unknown>) => Promise<unknown>;
+};
+export interface AgentSource {
+    readonly id: string;
+    readonly manifest: AgentManifest | WorkflowManifest;
+    build?(): BuiltAgent | BuiltWorkflow;
+    getBinding?: BuiltAgent["getBinding"] | BuiltWorkflow["getBinding"];
+}
+/** Closures stay on the live binding. The published manifest cannot name them. */
+export declare function assertNoMiddlewareClosures(agent: AgentSource): void;
+export interface SessionView {
+    id: string;
+    agentId: string;
+    ownerUserId: string;
+    status: string;
+    activeTurnId: string | null;
+    waits?: unknown;
+    [key: string]: unknown;
+}
+export interface ActAsOptions {
+    /** What the subject may do; the Runtime grants nothing else. Default `["sessions:own"]`. */
+    scopes?: readonly SubjectScope[];
+}
+export declare class AgentsClient {
+    readonly transport: Transport;
+    /** The subject this client acts for (`as`), or `undefined` for the principal itself. */
+    readonly subject: string | undefined;
+    constructor(destination?: Destination);
+    /**
+     * A client that acts for `subject`: every call sends `Nylorun-Subject` and
+     * `Nylorun-Scopes`, and the Runtime limits it to the scopes and to the subject's own sessions
+     * and vaults (Host feature `subject-headers`). For app servers, which authenticate the person
+     * themselves and hold the key; nothing is minted, cached or refreshed.
+     */
+    as(subject: string, options?: ActAsOptions): AgentsClient;
+    /**
+     * Mints subject tokens for signed-in people (Host feature `subject-tokens`), so their
+     * browser or app calls the Runtime directly. Application key only.
+     */
+    get tokens(): TokensClient;
+    /** The access policy, signing keys and revocations (Host feature `subject-tokens`). */
+    get access(): AccessClient;
+    /** The Runtime's protocol features, including optional ones such as `transcript-events`. */
+    hostFeatures(options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly string[]>;
+    listAgents(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        agents: {
+            manifest: AgentManifest;
+        }[];
+    }>;
+    listSessions(options?: {
+        agentId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        sessions: SessionView[];
+    }>;
+    saveAgent(agent: AgentSource | BuiltWorkflow, options: {
+        implementationVersion: string;
+        requestId?: string;
+    }): Promise<unknown>;
+    createSession(options: {
+        id?: string;
+        agentId: string;
+        ownerUserId: string;
+        info?: Record<string, unknown>;
+        requestId?: string;
+        vaultIds?: readonly string[];
+        credentialSelections?: readonly CredentialSelection[];
+        /**
+         * The session's sandbox: omit for the Tenant default, `false` for none, `{ session }` to share
+         * another session's, or an inline sandbox (`image`, `network.allow`, `resources`) checked
+         * against the Tenant's limits. Fixed once the session exists.
+         */
+        sandbox?: SandboxRequest;
+    }): Promise<SessionClient>;
+    createVault(options: {
+        name: string;
+        ownerUserId: string;
+        metadata?: Record<string, string>;
+        idempotencyKey: string;
+        requestId?: string;
+    }): Promise<VaultInfo>;
+    listVaults(ownerUserId: string, signal?: AbortSignal): Promise<{
+        vaults: VaultInfo[];
+    }>;
+    getVault(vaultId: string, signal?: AbortSignal): Promise<VaultInfo>;
+    deleteVault(vaultId: string): Promise<{
+        id: string;
+    }>;
+    createCredential(vaultId: string, options: {
+        name: string;
+        idempotencyKey: string;
+        requestId?: string;
+        auth: {
+            type: "bearer";
+            url: string;
+            token: string;
+        } | {
+            type: "oauth";
+            url: string;
+            accessToken: string;
+            expiresAt?: string | null;
+            refresh?: {
+                tokenEndpoint: string;
+                clientId: string;
+                refreshToken: string;
+                tokenEndpointAuth: {
+                    type: "none";
+                } | {
+                    type: "client_secret_basic";
+                    clientSecret: string;
+                } | {
+                    type: "client_secret_post";
+                    clientSecret: string;
+                };
+            };
+        };
+    }): Promise<CredentialInfo>;
+    listCredentials(vaultId: string, signal?: AbortSignal): Promise<{
+        credentials: CredentialInfo[];
+    }>;
+    getCredential(vaultId: string, credentialId: string, signal?: AbortSignal): Promise<CredentialInfo>;
+    rotateCredential(vaultId: string, credentialId: string, options: {
+        idempotencyKey: string;
+        requestId?: string;
+        auth: {
+            type: "bearer";
+            token: string;
+        } | {
+            type: "oauth";
+            accessToken: string;
+            expiresAt?: string | null;
+        };
+    }): Promise<CredentialInfo>;
+    deleteCredential(vaultId: string, credentialId: string): Promise<{
+        id: string;
+    }>;
+    session(sessionId: string): SessionClient;
+}
+export type CommandOptions = {
+    idempotencyKey: string;
+    requestId?: string;
+    signal?: AbortSignal;
+};
+export declare class SessionClient {
+    private readonly transport;
+    readonly id: string;
+    readonly sandbox: SessionSandbox;
+    constructor(transport: Transport, id: string);
+    private get path();
+    inspect(signal?: AbortSignal): Promise<SessionView>;
+    /** Pending waits / interactions from the session inspect view. */
+    pending(signal?: AbortSignal): Promise<{}>;
+    command(command: SessionCommand, signal?: AbortSignal): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    /**
+     * Start a turn. Strings become `message.content`; any other JSON value becomes
+     * `message.data` (workflows.md §5).
+     */
+    input(value: string | JsonValue, options: CommandOptions): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    approve(interactionId: string, approved: boolean, options: CommandOptions): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    respond(interactionId: string, value: JsonValue, options: CommandOptions): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    cancel(options: CommandOptions & {
+        reason?: string;
+    }): Promise<{
+        status: "accepted";
+        turnId: string | null;
+        cursor: string | null;
+        requestId: string;
+    }>;
+    /** `agent` narrows to one agent used as a tool: its delegationId or its path. */
+    history(options?: {
+        cursor?: string;
+        agent?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        items: ({
+            schema: "nylorun.event/2";
+            eventId: string;
+            tenantId: string;
+            sessionId: string;
+            runId: string | null;
+            turnId: string | null;
+            incarnation: number;
+            epoch: number;
+            seq: number;
+            cursor: string;
+            time: string;
+            schemaVersion: number;
+            source: {
+                kind: "api" | "controller" | "edge" | "egress-gate" | "evidence" | "harness" | "human" | "init" | "loop" | "model-gate" | "operator" | "sandboxd" | "supervisor" | "tool-gate";
+                id: string;
+            };
+            evidence: "asserted" | "attested" | "claimed" | "measured" | "observed";
+            trace?: {
+                traceId: string;
+                spanId: string;
+                parentSpanId?: string | undefined;
+            } | undefined;
+            visibility: "internal" | "public" | "restricted";
+            retention: "full" | "metadata";
+            type: string;
+            payload: unknown;
+        } | import("@nylorun/core/contracts").SessionEvent)[];
+        cursor: string | null;
+    }>;
+    observe(options?: {
+        cursor?: string;
+        signal?: AbortSignal;
+        follow?: boolean;
+    }): AsyncGenerator<{
+        schema: "nylorun.event/2";
+        eventId: string;
+        tenantId: string;
+        sessionId: string;
+        runId: string | null;
+        turnId: string | null;
+        incarnation: number;
+        epoch: number;
+        seq: number;
+        cursor: string;
+        time: string;
+        schemaVersion: number;
+        source: {
+            kind: "api" | "controller" | "edge" | "egress-gate" | "evidence" | "harness" | "human" | "init" | "loop" | "model-gate" | "operator" | "sandboxd" | "supervisor" | "tool-gate";
+            id: string;
+        };
+        evidence: "asserted" | "attested" | "claimed" | "measured" | "observed";
+        trace?: {
+            traceId: string;
+            spanId: string;
+            parentSpanId?: string | undefined;
+        } | undefined;
+        visibility: "internal" | "public" | "restricted";
+        retention: "full" | "metadata";
+        type: string;
+        payload: unknown;
+    }, void, unknown>;
+    private observeOne;
+    /**
+     * Own session stream plus linked agent sessions announced in `node.agent`
+     * events, merged by `time` then arrival order (workflows.md §11).
+     */
+    private observeFollowing;
+}
+export { RuntimeError, IncompatibleRuntimeError } from "./http.js";
+export type { Destination, IncompatibleReason } from "./http.js";
+export type { LiveEvent } from "@nylorun/core/contracts";
+export { AccessClient, PublishableKeysClient, SigningKeysClient, TokensClient, } from "./access.js";