@segmentstream-cloud/ontology 0.20.0 → 0.21.0

package/README.md

@@ -370,7 +370,7 @@ both are recorded, moves the members and a missing `purpose` and `whenToUse` to
 deletes the old one. `provider`, `externalId`, `title` and `lastMessageAt` are
 managed. Members set `purpose` and `whenToUse` with the generated
 `agent_chat.update`, the chat's only generated action. The built-in action
-`agent_chat.send_message` (`{ message, chat?, person? }`, `message` at most 4000 characters) asks the agent to write to the chat
+`agent_chat.send_message` (`{ message, chat?, person?, document_ids? }`, `message` at most 4000 characters) asks the agent to write to the chat
 given, else to the person's one chat, else to their paired private chat; a person in several
 chats is refused with the candidates, or only their number without `agent_chat:read`. The service posts the message to the agent at
 `https://<VERCEL_PROJECT_PRODUCTION_URL>/eve/v1/telegram/messages` with the deployment's OIDC
@@ -382,6 +382,30 @@ chats needs `agent_chat:read` by name: `*:read` and `*:*` do not cover `agent_ch
 
 ### Agent attachments
 
+Ontology SDK 0.21.0 adds `documentIds` to the authored action input (`document_ids` on REST/MCP):
+an optional array of at most ten `document` record UUIDs. Before posting anything to the agent,
+the action checks `document:read`, every record's existence and its single file property.
+Missing files refuse the request; unreadable files require the read permission; ambiguous file
+properties are refused. Requests without the field retain their previous behavior. The service
+requires a paired member requester for requests with documents, since the agent downloads as
+that member; services and unpaired requesters may still send requests without documents. It
+forwards `documentIds` to `POST /eve/v1/telegram/messages`; agent SDK 0.5.0 includes the ids in
+`<agent_request>` and sends the stored bytes with `segmentstream__attachments_send`.
+
+`GET /api/ontology/agent/files/:entity/:id[/:property]` returns `{ file, download }` for the
+current file property of an ontology record. Like temporary attachment routes, it requires a
+production runtime bearer token, `X-SegmentStream-Act-As` naming an active paired member,
+and the agent conversation/session headers. It checks `<entity>:read` before returning metadata
+and rechecks live permissions when granting a download pinned to that revision. The response is
+uncached; the download grant is short lived. Without a property the entity must have exactly one
+file property. Missing records/files return `not_found`, missing read access `forbidden`, and
+non-file or ambiguous properties `unsupported`.
+
+Outbound Telegram uploads currently have an effective **2 MiB multipart request limit** in the
+connection proxy, including overhead, even though Telegram accepts larger files. The agent splits
+compatible albums to fit and returns per-file errors. Group purpose and document restrictions
+still apply; a member's read access alone does not authorize sharing a restricted document in a group.
+
 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

package/dist/agent-chat.d.ts

@@ -14,6 +14,8 @@ export interface AgentMessage {
     };
     /** The request for the agent, written as an instruction to it. */
     readonly message: string;
+    /** Document record ids to send with the request; absent from older requests. */
+    readonly documentIds?: ReadonlyArray<string>;
     /** Whom the agent should address, when the caller named someone. */
     readonly person: {
         readonly id: string;
@@ -63,6 +65,7 @@ export declare const AgentChat: import("./entity.js").Entity<"agent_chat", {
 }, {
     readonly sendMessage: import("./action.js").Action<Schema.Struct<{
         readonly message: import("./property.js").Property<string, false, false>;
+        readonly documentIds: Schema.optionalKey<Schema.$Array<Schema.String>>;
         readonly chat: Schema.optionalKey<Schema.Codec<string, string, never, never>>;
         readonly person: Schema.optionalKey<Schema.Codec<string, string, never, never>>;
     }>, {

package/dist/agent-chat.js

@@ -6,6 +6,7 @@ import { isAllowed, permissionOf, READ_VERB } from "./permissions.js";
 import { p } from "./property.js";
 import { rel } from "./relationship.js";
 import { User } from "./user.js";
+import { AgentFileRecords } from "./runtime/files.js";
 /** The only channel the agent delivers to so far, and the provider of its chats. */
 export const TELEGRAM = "telegram";
 /**
@@ -84,12 +85,16 @@ export const AgentChat = entity("agent_chat", {
             "chats is refused with the candidates (id, title, purpose, when to use; only their number " +
             "without agent_chat:read): call again with chat. The agent then writes in that chat and " +
             "handles the replies there, in that chat's own session; this action only delivers the " +
-            "request and does not wait for an answer. Requires an agent deployed in the workspace.",
+            "request and does not wait for an answer. document_ids optionally names up to ten readable " +
+            "document records to attach with the question. Requires an agent deployed in the workspace.",
         input: Schema.Struct({
             message: p.text({
                 maxLength: 4000,
                 description: "The request for the agent, as an instruction: what to ask or tell, of whom.",
             }),
+            documentIds: Schema.optionalKey(Schema.Array(Schema.String.check(Schema.isUUID()))
+                .check(Schema.isMaxLength(10))
+                .annotate({ description: "Up to ten document record ids the requester may read." })),
             chat: p.ref("agent_chat", { optional: true, description: "The agent chat to write in." }),
             person: p.ref("user", {
                 optional: true,
@@ -103,6 +108,19 @@ export const AgentChat = entity("agent_chat", {
             if (Option.isNone(channel)) {
                 return yield* new ActionRejected({ message: NO_AGENT });
             }
+            if (input.documentIds !== undefined && input.documentIds.length > 0) {
+                const files = yield* Effect.serviceOption(AgentFileRecords);
+                if (Option.isNone(files)) {
+                    return yield* new ActionRejected({
+                        message: "This runtime cannot validate stored documents.",
+                    });
+                }
+                for (const id of input.documentIds) {
+                    yield* files.value
+                        .resolve({ entity: "document", id }, principal)
+                        .pipe(Effect.catchTag("UnsupportedFile", (error) => Effect.fail(new ActionRejected({ message: error.message }))));
+                }
+            }
             const person = input.person === undefined ? undefined : yield* User.get(input.person);
             if (person !== undefined && (person.kind !== "member" || !person.active)) {
                 return yield* new ActionRejected({
@@ -158,9 +176,15 @@ export const AgentChat = entity("agent_chat", {
             // The agent acts as a member only through their pairing.
             const actAs = principal.kind === "member" &&
                 (yield* channel.value.privateChat(principal.id)) !== undefined;
+            if ((input.documentIds?.length ?? 0) > 0 && !actAs) {
+                return yield* new ActionRejected({
+                    message: "Sending documents requires a member requester with a paired Telegram account.",
+                });
+            }
             yield* channel.value.send({
                 target,
                 message: input.message,
+                ...(input.documentIds === undefined ? {} : { documentIds: input.documentIds }),
                 person: person === undefined ? null : { id: person.id, name: person.name },
                 requester: {
                     id: requester.id,

package/dist/runtime/files.d.ts

@@ -0,0 +1,39 @@
+import { Context, Effect, Schema } from "effect";
+import { NotFound, PermissionDenied } from "../errors.js";
+import type { OntologyManifest } from "../manifest.js";
+import type { OntologyReads, Principal } from "../runtime.js";
+export interface FileReference {
+    readonly entity: string;
+    readonly id: string;
+    readonly property?: string;
+}
+declare const UnsupportedFile_base: Schema.Class<UnsupportedFile, Schema.TaggedStruct<"UnsupportedFile", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UnsupportedFile extends UnsupportedFile_base {
+}
+/** Resolve only declared file properties, checking permission before reading any record. */
+export declare function resolveFileRecord(input: {
+    readonly manifest: OntologyManifest;
+    readonly reads: Pick<OntologyReads["Service"], "get">;
+    readonly principal: Principal;
+    readonly reference: FileReference;
+}): Effect.Effect<{
+    entity: string;
+    id: string;
+    property: string;
+    file: {
+        readonly id: string;
+        readonly filename: string;
+        readonly contentType: string;
+        readonly size: number;
+        readonly createdAt: string;
+    };
+}, PermissionDenied | NotFound | UnsupportedFile, never>;
+declare const AgentFileRecords_base: Context.ServiceClass<AgentFileRecords, "@segmentstream-cloud/ontology/AgentFileRecords", {
+    readonly resolve: (reference: FileReference, principal: Principal) => ReturnType<typeof resolveFileRecord>;
+}>;
+/** File validation in an action's prepare, bound to its ontology and read runtime. */
+export declare class AgentFileRecords extends AgentFileRecords_base {
+}
+export {};

package/dist/runtime/files.js

@@ -0,0 +1,44 @@
+import { Context, Effect, Schema } from "effect";
+import { BlobValue } from "../blob.js";
+import { NotFound, PermissionDenied } from "../errors.js";
+import { isAllowed, permissionOf, READ_VERB } from "../permissions.js";
+export class UnsupportedFile extends Schema.TaggedError()("UnsupportedFile", {
+    message: Schema.String,
+}) {
+}
+/** Resolve only declared file properties, checking permission before reading any record. */
+export function resolveFileRecord(input) {
+    return Effect.gen(function* () {
+        const { entity: entityName, id, property: propertyName } = input.reference;
+        const permission = permissionOf(entityName, READ_VERB);
+        if (!isAllowed(permission, input.principal)) {
+            return yield* new PermissionDenied({ permission, message: "The file requires read access." });
+        }
+        const entity = input.manifest.entities.find((candidate) => candidate.name === entityName);
+        if (entity === undefined) {
+            return yield* new NotFound({ entity: entityName, id, message: "File record not found." });
+        }
+        const properties = entity.properties.filter((candidate) => candidate.type === "blob");
+        const property = propertyName === undefined
+            ? properties.length === 1
+                ? properties[0]
+                : undefined
+            : properties.find((candidate) => candidate.name === propertyName);
+        if (property === undefined) {
+            return yield* new UnsupportedFile({
+                message: "Name a file property; the entity must have exactly one when property is omitted.",
+            });
+        }
+        const record = yield* input.reads.get({ entity: entityName, id });
+        const file = record[property.name];
+        if (file === null || file === undefined) {
+            return yield* new NotFound({ entity: entityName, id, message: "File not found." });
+        }
+        // Runtime records are decoded already; malformed stored metadata is an operator failure.
+        const decoded = yield* Schema.decodeUnknownEffect(BlobValue)(file).pipe(Effect.orDie);
+        return { entity: entityName, id, property: property.name, file: decoded };
+    });
+}
+/** File validation in an action's prepare, bound to its ontology and read runtime. */
+export class AgentFileRecords extends Context.Service()("@segmentstream-cloud/ontology/AgentFileRecords") {
+}

package/dist/runtime/pipeline.js

@@ -14,6 +14,7 @@ import { UnknownAction, ValidationIssue } from "./errors.js";
 import { generatedActions } from "./generated-actions.js";
 import { Edit } from "./history.js";
 import { makeOntologyRuntime } from "./sql-runtime.js";
+import { AgentFileRecords, resolveFileRecord } from "./files.js";
 import { validate } from "./validation.js";
 /** How long `prepare` may take, connection calls included; each call has its own 30 s deadline. */
 export const PREPARE_TIMEOUT = Duration.seconds(60);
@@ -243,7 +244,9 @@ function prepare(ontology, sql, action, context, connections, qualified) {
             find: ({ entity, options }) => runtime.find({ entity, options: { ...options, forUpdate: false } }),
         };
         const run = Effect.suspend(() => action.prepare(context));
-        return yield* run.pipe(Effect.provideService(OntologyReads, reads), Effect.provideContext(connectionContext(action.connections, transport ?? NO_CONNECTIONS)), Effect.timeoutOrElse({
+        return yield* run.pipe(Effect.provideService(OntologyReads, reads), Effect.provideService(AgentFileRecords, {
+            resolve: (reference, principal) => resolveFileRecord({ manifest: ontology.manifest, reads, reference, principal }),
+        }), Effect.provideContext(connectionContext(action.connections, transport ?? NO_CONNECTIONS)), Effect.timeoutOrElse({
             duration: PREPARE_TIMEOUT,
             orElse: () => Effect.fail(new ConnectionError({
                 connection: action.connections.map((handle) => handle.key).join(","),

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

@@ -7,8 +7,9 @@ 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 { RuntimeTokenVerifier } from "../runtime-identity.js";
 import type { AgentChannelFactory } from "./channel.js";
+export { CONVERSATION_HEADER, SESSION_HEADER } from "./authentication.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`
@@ -17,10 +18,6 @@ import type { AgentChannelFactory } from "./channel.js";
  * 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>;

package/dist/service/agent/attachments.js

@@ -1,14 +1,14 @@
-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 { Cause, Effect, Layer, Result, Schema } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
 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 { RequestId, errorBodyForWire, failureResponse } 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 { authenticateAgentCaller } from "./authentication.js";
 import { AGENT_PATH } from "./server.js";
+export { CONVERSATION_HEADER, SESSION_HEADER } from "./authentication.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`
@@ -17,12 +17,6 @@ import { AGENT_PATH } from "./server.js";
  * 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),
@@ -111,39 +105,16 @@ export function attachmentsLayer(options) {
             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 authenticated = yield* authenticateAgentCaller({
+                request,
+                agents,
+                verify: verifyRuntime,
+            });
+            return authenticated.ok
+                ? yield* answer(request, authenticated.caller, attachments)
+                : authenticated.response;
         });
         const idOf = Effect.map(HttpRouter.params, (params) => params.id ?? "");
         yield* router.add("POST", ATTACHMENTS_PATH, asAgent((request, caller, runtime) => answered(Effect.gen(function* () {

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

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { HttpServerRequest } from "effect/unstable/http";
+import type { AttachmentCaller } from "../../storage/attachments.js";
+import { RequestId } from "../errors.js";
+import type { AgentStore } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+export declare const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
+export declare const SESSION_HEADER = "x-segmentstream-agent-session";
+/** Both temporary attachments and stored files require the runtime and its paired member. */
+export declare function authenticateAgentCaller(input: {
+    readonly request: HttpServerRequest.HttpServerRequest;
+    readonly agents: AgentStore;
+    readonly verify: RuntimeTokenVerifier;
+}): Effect.Effect<{
+    readonly ok: false;
+    readonly response: import("effect/unstable/http/HttpServerResponse").HttpServerResponse;
+} | {
+    readonly ok: true;
+    readonly caller: AttachmentCaller;
+}, never, RequestId | HttpServerRequest.ParsedSearchParams>;

package/dist/service/agent/authentication.js

@@ -0,0 +1,48 @@
+import { Effect, Redacted } from "effect";
+import { HttpServerRequest } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { RequestId, forbidden, toServerResponse, unauthorized, unavailable } from "../errors.js";
+import { ACT_AS_HEADER, logRuntimeRejection, } from "../runtime-identity.js";
+export const CONVERSATION_HEADER = "x-segmentstream-agent-conversation";
+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}$/;
+/** Both temporary attachments and stored files require the runtime and its paired member. */
+export function authenticateAgentCaller(input) {
+    return Effect.gen(function* () {
+        const { request, agents, verify } = input;
+        const requestId = yield* RequestId;
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        const bearer = yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+        const token = Redacted.value(bearer);
+        const verified = token === "" ? undefined : yield* Effect.promise(() => verify(token));
+        const denied = (response) => ({ ok: false, response: toServerResponse(response) });
+        switch (verified?.status) {
+            case "valid":
+                break;
+            case "invalid":
+                yield* logRuntimeRejection(verified.reason);
+                return denied(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
+            case "unavailable":
+                return denied(unavailable(requestId));
+            default:
+                return denied(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 denied(forbidden(requestId, "The member is inactive or has not paired with the agent."));
+        }
+        if (!CONVERSATION.test(conversation) || (session !== "" && !SESSION.test(session))) {
+            return denied(forbidden(requestId, "The agent names the chat and session of every request."));
+        }
+        const caller = {
+            principal: member,
+            conversation,
+            ...(session === "" ? {} : { sessionId: session }),
+        };
+        return { ok: true, caller };
+    });
+}

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

@@ -0,0 +1,12 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { RequestId } from "../errors.js";
+import type { ApiPlan } from "../plan.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import type { RuntimeTokenVerifier } from "../runtime-identity.js";
+export declare const FILES_PATH = "/api/ontology/agent/files";
+/** A short-lived download grant, issued only after the runtime's member may read the file. */
+export declare function filesLayer(options: {
+    readonly plan: ApiPlan;
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+}): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

package/dist/service/agent/files.js

@@ -0,0 +1,69 @@
+import { Cause, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { resolveFileRecord } from "../../runtime/files.js";
+import { isUuid } from "../../query.js";
+import { RequestId, failureResponse, notFound, toServerResponse } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { authenticateAgentCaller } from "./authentication.js";
+import { AGENT_PATH } from "./server.js";
+export const FILES_PATH = `${AGENT_PATH}/files`;
+/** A short-lived download grant, issued only after the runtime's member may read the file. */
+export function filesLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const { blobs, agents } = backend;
+        const verify = options.verifyRuntime;
+        if (blobs === undefined || agents === undefined || verify === undefined) {
+            return;
+        }
+        const read = (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const authenticated = yield* authenticateAgentCaller({ request, agents, verify });
+            if (!authenticated.ok) {
+                return authenticated.response;
+            }
+            const params = yield* HttpRouter.params;
+            const id = params.id ?? "";
+            if (!isUuid(id)) {
+                return toServerResponse(notFound(requestId, "File record not found."));
+            }
+            const resolved = yield* resolveFileRecord({
+                manifest: options.plan.ontology.manifest,
+                reads: backend,
+                principal: authenticated.caller.principal,
+                reference: {
+                    entity: params.entity ?? "",
+                    id,
+                    ...(params.property === undefined ? {} : { property: params.property }),
+                },
+            });
+            // Pin the revision read above. download rechecks live permissions in its transaction.
+            const download = yield* blobs.download(resolved.entity, resolved.id, resolved.property, { revisionId: resolved.file.id }, authenticated.caller.principal);
+            return HttpServerResponse.jsonUnsafe({
+                file: {
+                    id,
+                    entity: resolved.entity,
+                    property: resolved.property,
+                    filename: resolved.file.filename,
+                    content_type: resolved.file.contentType,
+                    size: resolved.file.size,
+                },
+                download: {
+                    url: download.url,
+                    method: download.method,
+                    headers: download.headers,
+                    expires_at: download.expiresAt,
+                },
+            }, { headers: { "cache-control": "no-store" } });
+        }).pipe(Effect.catchTag("UnsupportedFile", (error) => Effect.map(RequestId, (requestId) => HttpServerResponse.jsonUnsafe({
+            error: "unsupported",
+            detail: error.message,
+            request_id: requestId,
+        }, { status: 422 }))), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+            ? Effect.failCause(cause)
+            : Effect.flatMap(RequestId, (requestId) => failureResponse(cause, requestId))));
+        yield* router.add("GET", `${FILES_PATH}/:entity/:id`, read);
+        yield* router.add("GET", `${FILES_PATH}/:entity/:id/:property`, read);
+    }));
+}

package/dist/service/agent/server.js

@@ -170,7 +170,13 @@ function seeChat(store) {
         if (Result.isFailure(decoded)) {
             return invalidBody(requestId, schemaIssues(decoded.failure));
         }
-        return json(yield* store.seeChat(decoded.success));
+        const chat = yield* store.seeChat(decoded.success);
+        yield* Effect.logInfo("ontology.agent.chat_reported").pipe(Effect.annotateLogs({
+            requestId,
+            provider: decoded.success.provider,
+            chatId: decoded.success.externalId,
+        }));
+        return json(chat);
     });
 }
 /** `GET /api/ontology/agent/identities` (member): the member's own live identities. */

package/dist/service/service.js

@@ -5,6 +5,7 @@ import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-au
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
 import { attachmentsLayer } from "./agent/attachments.js";
+import { filesLayer } from "./agent/files.js";
 import { platformConversations } from "./agent/conversations.js";
 import { conversationRoutes } from "./agent/conversation-routes.js";
 import { deployedAgentChannel } from "./agent/channel.js";
@@ -130,7 +131,7 @@ export function createOntologyService(ontology, config) {
         verifyToken,
         verifyRuntime,
     });
-    const application = Layer.mergeAll(routes, mcp, agent, attachments, conversations === undefined
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, filesLayer({ plan: built.plan, verifyRuntime }), conversations === undefined
         ? Layer.empty
         : conversationRoutes({
             transport: conversations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",