@segmentstream-cloud/ontology 0.14.0 → 0.16.0

package/dist/service/agent/attachments.js

@@ -0,0 +1,225 @@
+import { Cause, Effect, Layer, Redacted, Result, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { ATTACHMENT_SOURCES, } from "../../storage/attachments.js";
+import { schemaIssues } from "../../runtime/validation.js";
+import { CurrentPrincipal } from "../authentication.js";
+import { RequestId, errorBodyForWire, failureResponse, forbidden, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+import { identityToken, makeOperations } from "../operations.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { ACT_AS_HEADER, logRuntimeRejection, } from "../runtime-identity.js";
+import { AGENT_PATH } from "./server.js";
+/**
+ * The agent's temporary attachments over HTTP (`docs/agent.md`, "Attachments"). Only the
+ * deployment's runtime token reaches these routes, acting as the member in `X-SegmentStream-Act-As`
+ * while they are active and paired. The chat and the agent session come from the agent's runtime in
+ * `X-SegmentStream-Agent-Conversation` and `X-SegmentStream-Agent-Session`, never from the model's
+ * tool arguments; every operation is confined to that member, chat and session.
+ */
+export const ATTACHMENTS_PATH = `${AGENT_PATH}/attachments`;
+/** The chat an attachment belongs to, such as `telegram:12345`. */
+export const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
+/** The agent session the request comes from. */
+export const SESSION_HEADER = "x-segmentstream-agent-session";
+const CONVERSATION = /^[a-z][a-z0-9_-]{0,31}:[A-Za-z0-9:_-]{1,200}$/;
+const SESSION = /^[A-Za-z0-9:_.-]{1,200}$/;
+const NO_STORE = { "cache-control": "no-store" };
+const Received = Schema.Struct({
+    source: Schema.Literals(ATTACHMENT_SOURCES),
+    source_ref: Schema.String,
+    filename: Schema.String,
+    content_type: Schema.String,
+    size: Schema.Int,
+    sha256: Schema.String,
+});
+const Promotion = Schema.Struct({
+    entity: Schema.String,
+    action: Schema.String,
+    input: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+    field: Schema.optionalKey(Schema.String),
+    record_id: Schema.optionalKey(Schema.String),
+});
+function json(body, status = 200) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: NO_STORE });
+}
+function attachmentForWire(attachment) {
+    return {
+        id: attachment.id,
+        filename: attachment.filename,
+        content_type: attachment.contentType,
+        size: attachment.size,
+        sha256: attachment.sha256,
+        state: attachment.state,
+        created_at: attachment.createdAt,
+        expires_at: attachment.expiresAt,
+        promotion: attachment.promotion,
+    };
+}
+function grantForWire(grant) {
+    return {
+        url: grant.url,
+        method: grant.method,
+        headers: grant.headers,
+        expires_at: grant.expiresAt,
+    };
+}
+function decodeBody(schema, request) {
+    return Effect.gen(function* () {
+        const text = yield* Effect.orDie(request.text);
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = undefined;
+        }
+        const decoded = yield* Effect.result(Schema.decodeUnknownEffect(schema)(body, { errors: "all", onExcessProperty: "error" }));
+        return Result.isFailure(decoded)
+            ? { ok: false, issues: schemaIssues(decoded.failure) }
+            : { ok: true, value: decoded.success };
+    });
+}
+function invalidBody(requestId, issues) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "invalid_request",
+        detail: "The request body is invalid.",
+        requestId,
+        issues: issues,
+    }), { status: 400 });
+}
+/** Answers a failure the way every other route does: expected ones by status, the rest as 500. */
+function answered(effect) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        return yield* effect.pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+            ? Effect.failCause(cause)
+            : failureResponse(cause, requestId)));
+    });
+}
+/**
+ * The attachment routes. Without file storage or the agent tables, or while runtime authentication
+ * is disabled, it serves nothing.
+ */
+export function attachmentsLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const attachments = backend.attachments;
+        const agents = backend.agents;
+        const verifyRuntime = options.verifyRuntime;
+        if (attachments === undefined || agents === undefined || verifyRuntime === undefined) {
+            return;
+        }
+        const operations = makeOperations(backend, options.plan, options.hooks, options.connections, options.replicate, options.agentChannel);
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        /** Authenticates the runtime, then the member it acts for, the chat and the session. */
+        const asAgent = (answer) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+            const token = Redacted.value(bearer);
+            const verified = token === "" ? undefined : yield* Effect.promise(() => verifyRuntime(token));
+            switch (verified?.status) {
+                case "valid":
+                    break;
+                case "invalid":
+                    yield* logRuntimeRejection(verified.reason);
+                    return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
+                case "unavailable":
+                    return toServerResponse(unavailable(requestId));
+                default:
+                    return toServerResponse(forbidden(requestId, "Only the app's agent calls this route."));
+            }
+            const actAs = request.headers[ACT_AS_HEADER]?.trim() ?? "";
+            const conversation = request.headers[CONVERSATION_HEADER]?.trim() ?? "";
+            const session = request.headers[SESSION_HEADER]?.trim() ?? "";
+            const member = actAs === "" ? undefined : yield* agents.actingMember(actAs);
+            if (member === undefined) {
+                return toServerResponse(forbidden(requestId, "The member is inactive or has not paired with the agent."));
+            }
+            if (!CONVERSATION.test(conversation) || (session !== "" && !SESSION.test(session))) {
+                return toServerResponse(forbidden(requestId, "The agent names the chat and session of every request."));
+            }
+            return yield* answer(request, {
+                principal: member,
+                conversation,
+                ...(session === "" ? {} : { sessionId: session }),
+            }, attachments);
+        });
+        const idOf = Effect.map(HttpRouter.params, (params) => params.id ?? "");
+        yield* router.add("POST", ATTACHMENTS_PATH, asAgent((request, caller, runtime) => answered(Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const body = yield* decodeBody(Received, request);
+            if (!body.ok) {
+                return invalidBody(requestId, body.issues);
+            }
+            const received = yield* runtime.receive({
+                source: body.value.source,
+                sourceRef: body.value.source_ref,
+                filename: body.value.filename,
+                contentType: body.value.content_type,
+                size: body.value.size,
+                sha256: body.value.sha256,
+            }, caller);
+            return json({
+                attachment: attachmentForWire(received.attachment),
+                ...(received.upload ? { upload: grantForWire(received.upload) } : {}),
+            }, 201);
+        }))));
+        yield* router.add("POST", `${ATTACHMENTS_PATH}/:id/complete`, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const attachment = yield* runtime.complete(yield* idOf, caller);
+            return json({ attachment: attachmentForWire(attachment) });
+        }))));
+        yield* router.add("GET", ATTACHMENTS_PATH, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const listed = yield* runtime.list(caller);
+            return json({ attachments: listed.map(attachmentForWire) });
+        }))));
+        yield* router.add("GET", `${ATTACHMENTS_PATH}/:id`, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const { attachment, download } = yield* runtime.read(yield* idOf, caller);
+            return json({
+                attachment: attachmentForWire(attachment),
+                download: grantForWire(download),
+            });
+        }))));
+        yield* router.add("POST", `${ATTACHMENTS_PATH}/:id/discard`, asAgent((_, caller, runtime) => answered(Effect.gen(function* () {
+            const attachment = yield* runtime.discard(yield* idOf, caller);
+            return json({ attachment: attachmentForWire(attachment) });
+        }))));
+        yield* router.add("POST", `${ATTACHMENTS_PATH}/:id/promote`, asAgent((request, caller, runtime) => answered(Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const body = yield* decodeBody(Promotion, request);
+            if (!body.ok) {
+                return invalidBody(requestId, body.issues);
+            }
+            const promotion = body.value;
+            const promoted = yield* runtime.promote(yield* idOf, {
+                entity: promotion.entity,
+                action: promotion.action,
+                input: promotion.input ?? {},
+                ...(promotion.field === undefined ? {} : { field: promotion.field }),
+                ...(promotion.record_id === undefined ? {} : { recordId: promotion.record_id }),
+            }, caller, (call) => Effect.gen(function* () {
+                const planned = options.plan.entities.find((entity) => entity.name === call.entity);
+                const action = planned?.actions.find((item) => item.name === call.action);
+                if (planned === undefined || action === undefined) {
+                    return yield* Effect.die(new Error("The promotion's action was not planned."));
+                }
+                // The action runs as the member, with the after-commit hooks and connections
+                // of any other call.
+                const answer = yield* operations
+                    .runAction(planned, action, {
+                    input: call.input,
+                    validateOnly: false,
+                    options: call.options,
+                    identityToken: identityToken(request),
+                })
+                    .pipe(Effect.provideService(CurrentPrincipal, caller.principal), Effect.provideService(RequestId, requestId));
+                return { result: answer.result, edits: answer.edits };
+            }));
+            return json({
+                attachment: attachmentForWire(promoted.attachment),
+                deduplicated: promoted.deduplicated,
+                result: promoted.result,
+            });
+        }))));
+    }));
+}

package/dist/service/agent/channel.d.ts

@@ -0,0 +1,16 @@
+import { AgentChannel } from "../../agent-chat.js";
+import type { AgentStore } from "../runtime-contract.js";
+/** The agent's route for messages the ontology asks it to deliver, on the production deployment. */
+export declare const AGENT_MESSAGES_PATH = "/eve/v1/telegram/messages";
+/** The agent of one action request: its token and the agent tables. */
+export type AgentChannelFactory = (input: {
+    /** The deployment's Vercel OIDC token, from the request or the environment. */
+    readonly identityToken: string | undefined;
+    readonly store: AgentStore | undefined;
+}) => AgentChannel["Service"];
+/**
+ * The agent of a deployment that has one, at `https://<VERCEL_PROJECT_PRODUCTION_URL>`. Each message
+ * goes to {@link AGENT_MESSAGES_PATH} with the deployment's Vercel OIDC token, which the agent
+ * verifies as its own project's. A member's private chat is their live Telegram identity.
+ */
+export declare function deployedAgentChannel(agentUrl: string, fetchImpl?: typeof fetch): AgentChannelFactory;

package/dist/service/agent/channel.js

@@ -0,0 +1,88 @@
+import { Effect, Option, Schema } from "effect";
+import { TELEGRAM } from "../../agent-chat.js";
+import { ActionRejected } from "../../errors.js";
+import { describeError } from "../aggregate-platform.js";
+/** The agent's route for messages the ontology asks it to deliver, on the production deployment. */
+export const AGENT_MESSAGES_PATH = "/eve/v1/telegram/messages";
+/** How long the agent may take to accept a message; it answers once the message is queued. */
+const DELIVERY_TIMEOUT_MS = 30_000;
+/** The agent's error body: `{ "error": "channels_disabled" }` and the like. */
+const AgentError = Schema.Struct({
+    error: Schema.optionalKey(Schema.String),
+    detail: Schema.optionalKey(Schema.String),
+});
+const rejected = (message) => new ActionRejected({ message });
+const UNREACHABLE = "The agent could not be reached, so the message was not delivered. Try again.";
+/**
+ * A delivery that got no answer (DNS, TLS, a timeout, a dropped body): the caught error is logged
+ * for the operator, with the token redacted, and the caller is told only that the agent was
+ * unreachable.
+ */
+function deliveryFailed(error, token) {
+    const diagnostic = error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unreachable";
+    const redact = (text) => text.split(token).join("[redacted]");
+    return Effect.logWarning("ontology.agent.delivery_failed").pipe(Effect.annotateLogs({ diagnostic, error: describeError(error, redact) }), Effect.andThen(Effect.fail(rejected(UNREACHABLE))));
+}
+/**
+ * What the caller is told when the agent does not accept the message, by its status and body. The
+ * status and the agent's error code are logged; the body is not.
+ */
+function refusal(status, text) {
+    const body = Option.getOrElse(Schema.decodeUnknownOption(Schema.fromJsonString(AgentError))(text), () => ({}));
+    return Effect.logWarning("ontology.agent.delivery_refused").pipe(Effect.annotateLogs({ status, diagnostic: body.error ?? "refused" }), Effect.andThen(Effect.fail(refusalMessage(status, body))));
+}
+/** The caller's message for a refusal, by the agent's status and decoded error body. */
+function refusalMessage(status, body) {
+    switch (status) {
+        case 400:
+            return rejected(`The agent refused the message as invalid${body.detail ? `: ${body.detail}` : "."}`);
+        case 401:
+        case 403:
+            return rejected("The agent refused the deployment's token, so the message was not delivered.");
+        case 404:
+            return rejected("The deployed agent does not take messages from the ontology. Redeploy the agent with an " +
+                "SDK that does.");
+        case 503:
+            return body.error === "channels_disabled"
+                ? rejected("The agent's channels run only in the production deployment, so it cannot deliver " +
+                    "the message from here.")
+                : rejected("The agent is temporarily unavailable, so the message was not delivered. Try again.");
+        default:
+            return rejected(UNREACHABLE);
+    }
+}
+/**
+ * The agent of a deployment that has one, at `https://<VERCEL_PROJECT_PRODUCTION_URL>`. Each message
+ * goes to {@link AGENT_MESSAGES_PATH} with the deployment's Vercel OIDC token, which the agent
+ * verifies as its own project's. A member's private chat is their live Telegram identity.
+ */
+export function deployedAgentChannel(agentUrl, fetchImpl = fetch) {
+    const url = `${agentUrl}${AGENT_MESSAGES_PATH}`;
+    return ({ identityToken, store }) => ({
+        privateChat: (userId) => store === undefined
+            ? Effect.succeed(undefined)
+            : store
+                .listIdentities(userId)
+                .pipe(Effect.map((identities) => identities.find((identity) => identity.provider === TELEGRAM)?.externalId)),
+        send: (message) => identityToken === undefined || identityToken === ""
+            ? Effect.fail(rejected("The request carries no Vercel OIDC token, which the agent requires. Messages are " +
+                "sent from the production deployment."))
+            : Effect.tryPromise({
+                try: async (signal) => {
+                    const response = await fetchImpl(url, {
+                        method: "POST",
+                        headers: {
+                            authorization: `Bearer ${identityToken}`,
+                            "content-type": "application/json",
+                            accept: "application/json",
+                        },
+                        body: JSON.stringify(message),
+                        redirect: "error",
+                        signal: AbortSignal.any([signal, AbortSignal.timeout(DELIVERY_TIMEOUT_MS)]),
+                    });
+                    return { ok: response.ok, status: response.status, text: await response.text() };
+                },
+                catch: (error) => error,
+            }).pipe(Effect.catch((error) => deliveryFailed(error, identityToken)), Effect.flatMap((answer) => answer.ok ? Effect.void : refusal(answer.status, answer.text))),
+    });
+}

package/dist/service/agent/protocol.d.ts

@@ -26,6 +26,20 @@ export declare const PairingRequest: Schema.Struct<{
     readonly display: Schema.optionalKey<Schema.NullOr<Schema.String>>;
 }>;
 export type PairingRequest = typeof PairingRequest.Type;
+/**
+ * `POST /api/ontology/agent/chats/seen`: a group chat the agent saw a message in, and who wrote, or
+ * the paired member who left it, or the agent itself leaving it, or the group it was before it
+ * became a supergroup.
+ */
+export declare const ChatSeenRequest: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly externalId: Schema.String;
+    readonly title: Schema.String;
+    readonly memberId: Schema.optionalKey<Schema.String>;
+    readonly leftMemberId: Schema.optionalKey<Schema.String>;
+    readonly agentLeft: Schema.optionalKey<Schema.Literal<true>>;
+    readonly migratedFrom: Schema.optionalKey<Schema.String>;
+}>;
 /** An identity on the wire, as the member's connect page and settings show it. */
 export declare function identityForWire(identity: AgentIdentity): {
     id: string;

package/dist/service/agent/protocol.js

@@ -40,6 +40,32 @@ export const PairingRequest = Schema.Struct({
         description: "How the channel names the account, shown to the member who approves.",
     })),
 });
+/** A chat's id on the channel. */
+const ChatId = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_EXTERNAL_ID_LENGTH));
+/**
+ * `POST /api/ontology/agent/chats/seen`: a group chat the agent saw a message in, and who wrote, or
+ * the paired member who left it, or the agent itself leaving it, or the group it was before it
+ * became a supergroup.
+ */
+export const ChatSeenRequest = Schema.Struct({
+    provider: Provider,
+    externalId: ChatId.annotate({ description: "The chat's id on the channel." }),
+    title: Schema.String.check(Schema.isMaxLength(MAX_DISPLAY_LENGTH)).annotate({
+        description: "The chat's name on the channel.",
+    }),
+    memberId: Schema.optionalKey(Schema.String.annotate({
+        description: "The user id of the member who wrote, when the sender is paired.",
+    })),
+    leftMemberId: Schema.optionalKey(Schema.String.annotate({
+        description: "The user id of a paired member who left the chat, to unlink from its members.",
+    })),
+    agentLeft: Schema.optionalKey(Schema.Literal(true).annotate({
+        description: "The agent itself left the chat or was removed: every member is unlinked.",
+    })),
+    migratedFrom: Schema.optionalKey(ChatId.annotate({
+        description: "The chat's id before it became a supergroup: its record moves to externalId.",
+    })),
+});
 /** An identity on the wire, as the member's connect page and settings show it. */
 export function identityForWire(identity) {
     return {

package/dist/service/agent/server.d.ts

@@ -19,7 +19,8 @@ export interface AgentServerOptions {
     readonly exchangeSession: SessionExchange | undefined;
 }
 /**
- * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * The routes that pair channel accounts with members for the app's own agent, and record the group
+ * chats it sees. Runtime routes take
  * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
  * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
  * Without the agent tables, it serves nothing.

package/dist/service/agent/server.js

@@ -10,11 +10,12 @@ import { secretHash } from "../oauth/protocol.js";
 import { clientAddress, fixedWindowLimiter, } from "../rate-limit.js";
 import { OntologyBackend } from "../runtime-contract.js";
 import { logRuntimeRejection } from "../runtime-identity.js";
-import { PAIRING_TTL_MS, PairingRequest, canonicalPairingCode, identityForWire, memberForWire, newPairingCode, } from "./protocol.js";
+import { ChatSeenRequest, PAIRING_TTL_MS, PairingRequest, canonicalPairingCode, identityForWire, memberForWire, newPairingCode, } from "./protocol.js";
 /** The agent's endpoints, under the ontology service's path. */
 export const AGENT_PATH = `${BASE_PATH}/agent`;
 const PAIRINGS_PATH = `${AGENT_PATH}/pairings`;
 const IDENTITIES_PATH = `${AGENT_PATH}/identities`;
+const CHATS_SEEN_PATH = `${AGENT_PATH}/chats/seen`;
 /**
  * Pairings one client address may start per minute; each one is a row in the database. The agent's
  * functions share a few egress addresses, so the limit leaves room for a busy channel.
@@ -153,6 +154,25 @@ function resolveIdentity(store) {
         return json(memberForWire(member));
     });
 }
+/**
+ * `POST /api/ontology/agent/chats/seen` (runtime): the agent saw a message in a group chat. The chat
+ * is recorded, or its title kept current, a paired writer joins its members and a paired member who
+ * left is unlinked from them, or all of them when the agent itself left; the answer says what the
+ * chat is for, so that the agent knows it.
+ */
+function seeChat(store) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const decoded = Schema.decodeUnknownResult(ChatSeenRequest)(yield* jsonBody(request), {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        return json(yield* store.seeChat(decoded.success));
+    });
+}
 /** `GET /api/ontology/agent/identities` (member): the member's own live identities. */
 function listIdentities(store, member) {
     return Effect.gen(function* () {
@@ -174,7 +194,8 @@ function revokeIdentity(store, member) {
     });
 }
 /**
- * The routes that pair channel accounts with members for the app's own agent. Runtime routes take
+ * The routes that pair channel accounts with members for the app's own agent, and record the group
+ * chats it sees. Runtime routes take
  * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
  * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
  * Without the agent tables, it serves nothing.
@@ -230,6 +251,7 @@ export function agentLayer(options) {
         yield* router.add("POST", `${PAIRINGS_PATH}/:code/approve`, asMember((_, member) => approvePairing(store, member)));
         yield* router.add("GET", IDENTITIES_PATH, asMember((_, member) => listIdentities(store, member)));
         yield* router.add("GET", `${IDENTITIES_PATH}/:provider/:external_id`, asRuntime(() => resolveIdentity(store)));
+        yield* router.add("POST", CHATS_SEEN_PATH, asRuntime(seeChat(store)));
         yield* router.add("DELETE", `${IDENTITIES_PATH}/:id`, asMember((_, member) => revokeIdentity(store, member)));
     }));
 }

package/dist/service/aggregate-platform.d.ts

@@ -47,6 +47,11 @@ export interface AggregateEnvironment {
     readonly appCredential?: Redacted.Redacted<string>;
     readonly manifestHash: string;
 }
+/**
+ * A failed call for the operator: name, message and stack, then each cause, with every occurrence
+ * of the credential replaced.
+ */
+export declare function describeError(error: unknown, redact: (text: string) => string, depth?: number): string;
 /**
  * SegmentStream's `POST /api/v1/workspaces/{id}/aggregate`, and its per-entity
  * `…/entities/{entity}/aggregate`, called with the workspace app credential. `undefined` when the deployment has none, or when SegmentStream's origin is plain

package/dist/service/aggregate-platform.js

@@ -58,7 +58,7 @@ function securePlatform(origin) {
  * A failed call for the operator: name, message and stack, then each cause, with every occurrence
  * of the credential replaced.
  */
-function describeError(error, redact, depth = 0) {
+export function describeError(error, redact, depth = 0) {
     if (!(error instanceof Error)) {
         return redact(String(error));
     }

package/dist/service/config.d.ts

@@ -37,6 +37,11 @@ export declare const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES: {
     readonly audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE";
     readonly projectId: "VERCEL_PROJECT_ID";
 };
+/**
+ * The project's production domain, which Vercel sets: the agent of a deployment with runtime identity
+ * takes the messages of `agent_chat.send_message` there.
+ */
+export declare const AGENT_HOST_VARIABLE = "VERCEL_PROJECT_PRODUCTION_URL";
 /** Where the workspace's Neon Auth issues and publishes the keys of its users' tokens. */
 export interface NeonAuthEnvironment {
     /** The Auth URL, such as `https://ep-….neon.tech/ontology/auth`. Its origin is the issuer. */
@@ -68,6 +73,11 @@ export interface OntologyEnvironment {
      * authenticate, acting as the member `X-SegmentStream-Act-As` names.
      */
     readonly runtimeIdentity?: RuntimeIdentityConfig;
+    /**
+     * The agent's origin, `https://<VERCEL_PROJECT_PRODUCTION_URL>`, set with `runtimeIdentity`:
+     * `agent_chat.send_message` hands messages to the agent there.
+     */
+    readonly agentUrl?: string;
     /**
      * The local grant `segmentstream exec --connection …` passed, in development. Without it, actions
      * call connections through SegmentStream with the deployment's Vercel OIDC token.

package/dist/service/config.js

@@ -34,6 +34,11 @@ export const RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES = {
     audience: "SEGMENTSTREAM_RUNTIME_OIDC_AUDIENCE",
     projectId: "VERCEL_PROJECT_ID",
 };
+/**
+ * The project's production domain, which Vercel sets: the agent of a deployment with runtime identity
+ * takes the messages of `agent_chat.send_message` there.
+ */
+export const AGENT_HOST_VARIABLE = "VERCEL_PROJECT_PRODUCTION_URL";
 /** The service cannot start: its configuration is incomplete or invalid. */
 export class OntologyServiceConfigError extends Schema.TaggedError()("OntologyServiceConfigError", { message: Schema.String }) {
 }
@@ -160,6 +165,9 @@ export function configFromEnv(environment = process.env) {
             : {}),
         ...(neonAuth === undefined ? {} : { neonAuth }),
         ...(runtimeIdentity === undefined ? {} : { runtimeIdentity }),
+        ...(runtimeIdentity === undefined || read(AGENT_HOST_VARIABLE) === ""
+            ? {}
+            : { agentUrl: normalizeUrl(AGENT_HOST_VARIABLE, `https://${read(AGENT_HOST_VARIABLE)}`) }),
         ...(localConnections === undefined ? {} : { localConnections }),
     };
 }

package/dist/service/handlers.d.ts

@@ -4,6 +4,7 @@ import type { Aggregates } from "./aggregate.js";
 import { type BuiltApi } from "./api.js";
 import type { AfterCommitHook } from "./config.js";
 import type { ReplicationKick } from "./replication.js";
+import type { AgentChannelFactory } from "./agent/channel.js";
 import type { ConnectionTransportFactory } from "./connections.js";
 import { type RateLimit } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
@@ -13,4 +14,4 @@ import { OntologyBackend } from "./runtime-contract.js";
  */
 export declare const SIGN_IN_CHECK_LIMIT: RateLimit;
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, aggregates: Aggregates): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;
+export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, aggregates: Aggregates, agentChannel: AgentChannelFactory | undefined): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;

package/dist/service/handlers.js

@@ -216,8 +216,8 @@ function storageHandlers(built) {
     }));
 }
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export function handlersLayer(built, hooks, connections, replicate, aggregates) {
-    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate);
+export function handlersLayer(built, hooks, connections, replicate, aggregates, agentChannel) {
+    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate, agentChannel);
     const layers = [
         serviceHandlers(built, operationsOf, aggregates.model),
         ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))

package/dist/service/mcp/server.d.ts

@@ -4,6 +4,7 @@ import type { Aggregates } from "../aggregate.js";
 import type { BuiltApi } from "../api.js";
 import { type TokenVerifier } from "../authentication.js";
 import type { AfterCommitHook } from "../config.js";
+import type { AgentChannelFactory } from "../agent/channel.js";
 import type { ConnectionTransportFactory } from "../connections.js";
 import { RequestId } from "../errors.js";
 import type { ReplicationKick } from "../replication.js";
@@ -23,6 +24,8 @@ export interface McpServerOptions {
     readonly verifyRuntime?: RuntimeTokenVerifier | undefined;
     /** The facade the aggregate routes run; the aggregate tool runs its model-level aggregate. */
     readonly aggregates: Aggregates;
+    /** The workspace's agent, for `agent_chat.send_message`; `undefined` without one. */
+    readonly agentChannel?: AgentChannelFactory | undefined;
 }
 /**
  * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can

package/dist/service/mcp/server.js

@@ -1,4 +1,4 @@
-import { Cause, Data, Effect, Layer, Option, Schema } from "effect";
+import { Cause, Data, Effect, Layer, Option, Schema, SchemaTransformation } from "effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
 import { encodeManifest } from "../../manifest.js";
@@ -14,7 +14,8 @@ import { identityToken, makeOperations, toQuery } from "../operations.js";
 import { OntologyBackend } from "../runtime-contract.js";
 import { runtimeCredential } from "../runtime-identity.js";
 import { ActionResponse, HistoryPage, HistoryParams, IdParam, Me, } from "../schemas.js";
-import { mcpTools, visibleTools } from "./tools.js";
+import { uploadFields } from "../../storage/attachments.js";
+import { ACTION_OPTIONS_ARGUMENT, mcpTools, visibleTools } from "./tools.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
 export const MCP_PATH = "/mcp";
 /** The MCP revisions the server speaks, newest first. */
@@ -66,6 +67,23 @@ function decodeArguments(schema, args) {
         onExcessProperty: "error",
     }).pipe(Effect.mapError((error) => new InvalidArguments({ issues: schemaIssues(error.issue) })));
 }
+/** The `_options` argument of an action tool that consumes an upload. */
+const McpActionOptions = Schema.Struct({
+    idempotency_key: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128))),
+    create_intent: Schema.optionalKey(Schema.String.check(Schema.isUUID())),
+}).pipe(Schema.decodeTo(Schema.Struct({
+    idempotencyKey: Schema.optionalKey(Schema.String),
+    createIntent: Schema.optionalKey(Schema.String),
+}), SchemaTransformation.transform({
+    decode: (value) => ({
+        ...(value.idempotency_key === undefined ? {} : { idempotencyKey: value.idempotency_key }),
+        ...(value.create_intent === undefined ? {} : { createIntent: value.create_intent }),
+    }),
+    encode: (value) => ({
+        ...(value.idempotencyKey === undefined ? {} : { idempotency_key: value.idempotencyKey }),
+        ...(value.createIntent === undefined ? {} : { create_intent: value.createIntent }),
+    }),
+})));
 /** What the service sends: a value encoded with the schema of the matching HTTP route. */
 function encoded(schema, value) {
     return Schema.encodeUnknownEffect(schema)(value).pipe(Effect.orDie);
@@ -178,9 +196,14 @@ function runTool({ built, operations, aggregate }, tool, args, request) {
                 return structured(yield* encoded(HistoryPage, yield* operations.history(target.planned, id, params)));
             }
             case "action": {
+                const { [ACTION_OPTIONS_ARGUMENT]: rawOptions, ...input } = args;
+                const options = rawOptions === undefined || uploadFields(target.action.action.input).length === 0
+                    ? undefined
+                    : yield* decodeArguments(McpActionOptions, rawOptions);
                 const answer = yield* operations.runAction(target.planned, target.action, {
-                    input: args,
+                    input: options === undefined ? args : input,
                     validateOnly: false,
+                    ...(options === undefined ? {} : { options }),
                     identityToken: identityToken(request),
                 });
                 return structured(yield* encoded(ActionResponse, answer));
@@ -417,7 +440,7 @@ export function mcpLayer(options) {
         const server = {
             built: options.built,
             tools,
-            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate),
+            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate, options.agentChannel),
             aggregate: options.aggregates.model,
         };
         yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, options.verifyRuntime, backend));

package/dist/service/mcp/tools.d.ts

@@ -43,6 +43,12 @@ export interface McpTool {
     readonly inputSchemaFor?: (caller: PermissionHolder) => JsonSchemaObject | undefined;
     readonly target: McpToolTarget;
 }
+/**
+ * The argument an action that consumes an upload takes beside its input: the idempotency key the
+ * runtime requires of it, and the create intent the upload was begun with. The service removes it
+ * before the input is validated.
+ */
+export declare const ACTION_OPTIONS_ARGUMENT = "_options";
 /**
  * The MCP tools of an ontology: `describe` and `me`, `aggregate` when the ontology has measures,
  * then for every stored entity `find`, `get`,