@segmentstream-cloud/ontology 0.15.0 → 0.16.0

package/README.md

@@ -311,6 +311,45 @@ pair, or when the agent refuses, the action is rejected with the reason. Both ac
 `agent_chat:send_message`), which no role holds until the workspace grants it, and reading
 chats needs `agent_chat:read` by name: `*:read` and `*:*` do not cover `agent_chat`.
 
+### Agent attachments
+
+A file a member sends the agent is a temporary attachment: platform metadata in the runtime
+table `_agent_attachments`, never an ontology record, with its bytes stored once as a revision in
+the ontology's file storage, beside uploads. It belongs to the member, the chat it arrived in and
+the agent session that first reads it, holds its SHA-256, size, type and name, and expires 24
+hours after receipt (`received` → `ready` → `promoted`, `discarded` or `expired`). Files are up
+to 20 MB, what Telegram lets a bot download; a member holds at most 50 live attachments. The
+table exists on deployments with file storage; the migration adds it beside the file tables, also
+to a database an earlier SDK migrated.
+
+Only the agent calls these routes, with its runtime token, `X-SegmentStream-Act-As`, the chat in
+`X-SegmentStream-Agent-Conversation` (`telegram:<chat id>`) and, inside a turn, the session in
+`X-SegmentStream-Agent-Session`. Another member's attachment, another chat's or another
+session's answers 404; an expired or discarded one answers 409; a deactivated member's 403.
+
+| Route                                                | Does                                                                                                    |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `POST /api/ontology/agent/attachments`               | `{ source, source_ref, filename, content_type, size, sha256 }` → `{ attachment, upload? }`, a PUT grant |
+| `POST /api/ontology/agent/attachments/{id}/complete` | Verifies the stored bytes' size and SHA-256 → `{ attachment }` in `ready`                               |
+| `GET /api/ontology/agent/attachments`                | `{ attachments }`: the caller's readable attachments in this chat and session                           |
+| `GET /api/ontology/agent/attachments/{id}`           | `{ attachment, download }`: a one-minute GET grant                                                      |
+| `POST /api/ontology/agent/attachments/{id}/promote`  | `{ entity, action, input?, field?, record_id? }` → `{ attachment, deduplicated, result }`               |
+| `POST /api/ontology/agent/attachments/{id}/discard`  | Revokes it at once → `{ attachment }`                                                                   |
+
+Promotion keeps a file by running an action that takes an upload, such as an authored
+`document.upload` with `uploads.for(Document, "content")`, as the member and with their
+permissions. The service mints a completed upload ticket on the attachment's existing revision,
+fills the action's upload field (and `sha256`, when the input has one and the caller left it
+out), and runs the action with an idempotency key derived from the attachment, action and
+input, and the ticket's create intent; the action consumes the ticket as it would a browser
+upload, without copying the bytes. The target property's `accept` and `maxBytes` apply. A file
+whose SHA-256 an earlier attachment already promoted through the same action answers that
+promotion with `deduplicated: true` instead of a second record. Storage maintenance expires
+attachments past their deadline and removes the files no record adopted.
+
+An MCP action tool whose input takes an upload also accepts `_options: { idempotency_key,
+create_intent }`, the options the REST route takes beside `input`, so an MCP client can run it.
+
 ## The `segmentstream-ontology` binary
 
 Run the binary in the `ontology/` folder. The entry defaults to `./index.ts`. The binary

package/dist/migrate/apply.js

@@ -6,6 +6,7 @@ import { isNoopMigration } from "./model.js";
 import { planMigration } from "./plan.js";
 import { REPLICATION_DDL, REPLICATION_SCHEMA_VERSION, replicationEntityDdl, } from "../replication/schema.js";
 import { createReplicationBaseline } from "../replication/baseline.js";
+import { ATTACHMENTS_TABLE } from "../storage/tables.js";
 import { resolveReplicationSelection } from "../replication/model.js";
 import { AGENT_TABLES, API_KEYS_TABLE, CATALOG_TABLE, OAUTH_TABLES, USER_ROLES_TABLE, quoteIdentifier, quoteLiteral, } from "./storage.js";
 const CATALOG = quoteIdentifier(CATALOG_TABLE);
@@ -172,6 +173,7 @@ export const RUNTIME_TABLES = [
     API_KEYS_TABLE,
     ...OAUTH_TABLES,
     ...AGENT_TABLES,
+    ATTACHMENTS_TABLE,
 ];
 /**
  * The runtime tables the database has, for `planMigration`'s `existingTables`: a database that an

package/dist/migrate/plan.js

@@ -1,5 +1,5 @@
 import { isValueMatched, } from "../manifest.js";
-import { BLOB_TABLES_DDL } from "../storage/tables.js";
+import { ATTACHMENTS_TABLE, ATTACHMENT_TABLES_DDL, BLOB_TABLES_DDL } from "../storage/tables.js";
 import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
 import { AGENT_TABLES, AGENT_TABLES_DDL, CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, OAUTH_TABLES, OAUTH_TABLES_DDL, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, blobForeignKey, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
 const GLOBAL_KINDS = new Set(["table", "type", "index"]);
@@ -94,13 +94,23 @@ export function planMigration(input) {
             }));
         }
     }
-    if (storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob")) &&
+    const storesFiles = storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob"));
+    if (storesFiles &&
         !current?.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))) {
         draft.runtimeTables.push(step({
             kind: "createCatalog",
             classification: "additive",
-            description: "Create the ontology's file revision and upload tables.",
-            sql: BLOB_TABLES_DDL,
+            description: "Create the ontology's file revision, upload and agent attachment tables.",
+            sql: [...BLOB_TABLES_DDL, ...ATTACHMENT_TABLES_DDL],
+        }));
+    }
+    else if (storesFiles && input.existingTables?.has(ATTACHMENTS_TABLE) === false) {
+        // File storage an earlier SDK created lacks the agent's attachments, added since.
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the agent's temporary attachment table beside the file tables.",
+            sql: ATTACHMENT_TABLES_DDL,
         }));
     }
     planDrops({ pairs, removedEntities, addedEntities, allowDrops, draft });

package/dist/runtime/service-binding.js

@@ -3,6 +3,7 @@ import { Effect, Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import { neonBlobProvider } from "../storage/neon.js";
 import { maintainBlobStorage } from "../storage/maintenance.js";
+import { attachmentRuntime } from "../storage/attachments.js";
 import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
@@ -33,8 +34,10 @@ export function backendLayer(ontology, blobStorage) {
             ? yield* Effect.acquireRelease(Effect.sync(() => neonBlobProvider(binding)), (provider) => Effect.sync(() => provider.close?.()))
             : undefined;
         const blobs = provider ? blobRuntime(ontology, sql, provider) : undefined;
+        const attachments = provider ? attachmentRuntime(ontology, sql, provider) : undefined;
         return OntologyBackend.of({
             ...(blobs ? { blobs } : {}),
+            ...(attachments ? { attachments } : {}),
             ...(provider ? { maintainBlobs: maintainBlobStorage(sql, provider) } : {}),
             runAction: (input) => withSql(runAction(ontology, {
                 entity: input.entity,

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

@@ -0,0 +1,37 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type TokenVerifier } from "../authentication.js";
+import type { AfterCommitHook } from "../config.js";
+import type { ConnectionTransportFactory } from "../connections.js";
+import { RequestId } from "../errors.js";
+import type { ApiPlan } from "../plan.js";
+import type { ReplicationKick } from "../replication.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+import type { AgentChannelFactory } from "./channel.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 declare const ATTACHMENTS_PATH = "/api/ontology/agent/attachments";
+/** The chat an attachment belongs to, such as `telegram:12345`. */
+export declare const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
+/** The agent session the request comes from. */
+export declare const SESSION_HEADER = "x-segmentstream-agent-session";
+export interface AttachmentRoutesOptions {
+    readonly plan: ApiPlan;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
+    readonly agentChannel?: AgentChannelFactory | undefined;
+    readonly verifyToken: TokenVerifier;
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+}
+/**
+ * The attachment routes. Without file storage or the agent tables, or while runtime authentication
+ * is disabled, it serves nothing.
+ */
+export declare function attachmentsLayer(options: AttachmentRoutesOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

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/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));

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`,

package/dist/service/mcp/tools.js

@@ -7,6 +7,7 @@ import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { queryJsonSchema } from "../../query.js";
 import { measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
+import { uploadFields } from "../../storage/attachments.js";
 import { actionDescription, requires } from "../descriptions.js";
 import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, HistoryPage, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
@@ -160,6 +161,37 @@ function readTools(planned, schemas, built) {
         },
     ];
 }
+/**
+ * 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 const ACTION_OPTIONS_ARGUMENT = "_options";
+const ACTION_OPTIONS_SCHEMA = {
+    type: "object",
+    description: "Options of an action that stores an uploaded file: idempotency_key, required with an upload, " +
+        "and create_intent, the one the upload was begun with when it creates a record.",
+    properties: {
+        idempotency_key: { type: "string", minLength: 1, maxLength: 128 },
+        create_intent: { type: "string", format: "uuid" },
+    },
+    additionalProperties: false,
+};
+/** The input schema of an action tool; one that consumes an upload also takes its options. */
+function actionToolInput(action) {
+    const schema = rootObject(actionInputJsonSchema(action.input));
+    const properties = schema.properties;
+    if (uploadFields(action.input).length === 0 ||
+        schema.type !== "object" ||
+        properties === undefined ||
+        ACTION_OPTIONS_ARGUMENT in properties) {
+        return schema;
+    }
+    return {
+        ...schema,
+        properties: { ...properties, [ACTION_OPTIONS_ARGUMENT]: ACTION_OPTIONS_SCHEMA },
+    };
+}
 function actionTool(planned, plannedAction) {
     const { name, action, permissions } = plannedAction;
     const hints = hintsOf(planned, plannedAction);
@@ -167,7 +199,7 @@ function actionTool(planned, plannedAction) {
         name: mcpToolName(planned.name, name),
         title: `${planned.resolved.entity.definition.label}: ${humanize(name).toLowerCase()}`,
         description: actionDescription(plannedAction),
-        inputSchema: rootObject(actionInputJsonSchema(action.input)),
+        inputSchema: actionToolInput(action),
         annotations: {
             readOnlyHint: false,
             destructiveHint: hints.destructive,

package/dist/service/runtime-contract.d.ts

@@ -1,4 +1,5 @@
 import { Context, Schema, type Effect, type Layer, type Redacted } from "effect";
+import type { AttachmentRuntime } from "../storage/attachments.js";
 import type { BlobRuntime } from "../storage/sessions.js";
 import type { BlobStorageBinding } from "../storage/provider.js";
 import type { AnyAction } from "../action.js";
@@ -247,6 +248,8 @@ export interface AgentStore {
 }
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
     readonly blobs?: BlobRuntime;
+    /** The agent's temporary attachments, on deployments with file storage. */
+    readonly attachments?: AttachmentRuntime;
     readonly maintainBlobs?: Effect.Effect<{
         readonly removed: number;
     }, unknown>;

package/dist/service/service.js

@@ -4,6 +4,7 @@ import { HttpApiBuilder } from "effect/unstable/httpapi";
 import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-auth.js";
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
+import { attachmentsLayer } from "./agent/attachments.js";
 import { deployedAgentChannel } from "./agent/channel.js";
 import { agentLayer } from "./agent/server.js";
 import { makeAggregates } from "./aggregate.js";
@@ -116,7 +117,16 @@ export function createOntologyService(ontology, config) {
             agentChannel,
         }), oauthLayer({ verifyToken }));
     const agent = agentLayer({ verifyToken, verifyRuntime, exchangeSession });
-    const application = Layer.mergeAll(routes, mcp, agent, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
+    const attachments = attachmentsLayer({
+        plan: built.plan,
+        hooks,
+        connections,
+        replicate,
+        agentChannel,
+        verifyToken,
+        verifyRuntime,
+    });
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;
     return {