@segmentstream-cloud/ontology 0.19.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/conversation-routes.d.ts

@@ -0,0 +1,14 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type SessionExchange, type TokenVerifier } from "../authentication.js";
+import { RequestId } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+import { type ConversationTransport } from "./conversations.js";
+/** Same member scope as MCP, accessible to app clients with their usual bearer/session. */
+export declare function conversationRoutes(options: {
+    readonly transport: ConversationTransport;
+    readonly verifyToken: TokenVerifier;
+    readonly verifyRuntime?: RuntimeTokenVerifier | undefined;
+    readonly exchangeSession?: SessionExchange | undefined;
+}): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

package/dist/service/agent/conversation-routes.js

@@ -0,0 +1,43 @@
+import { Effect, Layer, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { CurrentPrincipal, withPrincipal, } from "../authentication.js";
+import { RequestId, expectedFailure, errorBodyForWire } from "../errors.js";
+import { identityToken } from "../operations.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { runtimeCredential } from "../runtime-identity.js";
+import { ConversationSearch } from "./conversations.js";
+/** Same member scope as MCP, accessible to app clients with their usual bearer/session. */
+export function conversationRoutes(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        yield* router.add("POST", "/api/ontology/agent/conversations/search", (request) => Effect.gen(function* () {
+            const bearer = yield* HttpApiBuilder.securityDecode(HttpApiSecurity.bearer).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, request));
+            const operation = Effect.gen(function* () {
+                const search = yield* Schema.decodeUnknownEffect(ConversationSearch)(yield* request.json);
+                const principal = yield* CurrentPrincipal;
+                const page = yield* options.transport({
+                    search,
+                    principal,
+                    identityToken: identityToken(request),
+                });
+                return HttpServerResponse.jsonUnsafe(page, {
+                    headers: { "cache-control": "private, no-store" },
+                });
+            }).pipe(Effect.catch((error) => Effect.gen(function* () {
+                const requestId = yield* RequestId;
+                const failure = expectedFailure(error, requestId);
+                return HttpServerResponse.jsonUnsafe(errorBodyForWire(failure?.body ?? {
+                    error: "invalid_request",
+                    detail: "The conversation request is invalid.",
+                    requestId,
+                }), { status: failure?.status ?? 400 });
+            })));
+            return yield* withPrincipal(bearer, options.verifyToken, backend, operation, {
+                runtime: runtimeCredential(options.verifyRuntime, request),
+                session: { request, exchange: options.exchangeSession },
+            });
+        }));
+    }));
+}

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

@@ -0,0 +1,35 @@
+import { Effect, Schema } from "effect";
+import type { Principal } from "../../runtime.js";
+import { PermissionDenied } from "../../errors.js";
+import type { OntologyEnvironment } from "../config.js";
+export declare const ConversationSearch: Schema.Struct<{
+    readonly q: Schema.optionalKey<Schema.String>;
+    readonly provider: Schema.optionalKey<Schema.String>;
+    readonly chatId: Schema.optionalKey<Schema.String>;
+    readonly threadId: Schema.optionalKey<Schema.String>;
+    readonly senderId: Schema.optionalKey<Schema.String>;
+    readonly from: Schema.optionalKey<Schema.String>;
+    readonly to: Schema.optionalKey<Schema.String>;
+    readonly before: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export type ConversationSearch = typeof ConversationSearch.Type;
+export declare const ConversationPage: Schema.Struct<{
+    readonly events: Schema.$Array<Schema.$Record<Schema.String, Schema.Unknown>>;
+    readonly nextCursor: Schema.NullOr<Schema.String>;
+}>;
+export type ConversationPage = typeof ConversationPage.Type;
+declare const ConversationArchiveUnavailable_base: Schema.Class<ConversationArchiveUnavailable, Schema.TaggedStruct<"ConversationArchiveUnavailable", {
+    readonly diagnostic: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ConversationArchiveUnavailable extends ConversationArchiveUnavailable_base {
+}
+export type ConversationTransport = (input: {
+    readonly search: ConversationSearch;
+    readonly principal: Principal;
+    readonly identityToken: string | undefined;
+}) => Effect.Effect<ConversationPage, ConversationArchiveUnavailable | PermissionDenied>;
+/** The authenticated ontology service forwards its resolved member, never a caller-supplied ID. */
+export declare function platformConversations(environment: OntologyEnvironment, fetchImpl?: typeof fetch): ConversationTransport;
+export {};

package/dist/service/agent/conversations.js

@@ -0,0 +1,68 @@
+import { Effect, Schema } from "effect";
+import { PermissionDenied } from "../../errors.js";
+import { isAllowed } from "../../permissions.js";
+import { describeError } from "../aggregate-platform.js";
+const Filter = Schema.String.check(Schema.isMaxLength(1000));
+export const ConversationSearch = Schema.Struct({
+    q: Schema.optionalKey(Filter),
+    provider: Schema.optionalKey(Filter),
+    chatId: Schema.optionalKey(Filter),
+    threadId: Schema.optionalKey(Filter),
+    senderId: Schema.optionalKey(Filter),
+    from: Schema.optionalKey(Filter),
+    to: Schema.optionalKey(Filter),
+    before: Schema.optionalKey(Filter),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
+});
+export const ConversationPage = Schema.Struct({
+    events: Schema.Array(Schema.Record(Schema.String, Schema.Unknown)),
+    nextCursor: Schema.NullOr(Schema.String),
+});
+export class ConversationArchiveUnavailable extends Schema.TaggedError()("ConversationArchiveUnavailable", { diagnostic: Schema.String, cause: Schema.optionalKey(Schema.Unknown) }) {
+}
+/** The authenticated ontology service forwards its resolved member, never a caller-supplied ID. */
+export function platformConversations(environment, fetchImpl = fetch) {
+    return ({ search, principal, identityToken }) => {
+        if (principal.kind !== "member") {
+            return Effect.fail(new PermissionDenied({
+                message: "Only members may read conversations.",
+                permission: "conversation:participant",
+            }));
+        }
+        if (!identityToken) {
+            return Effect.fail(new ConversationArchiveUnavailable({ diagnostic: "runtime_identity_missing" }));
+        }
+        return Effect.tryPromise({
+            try: async (signal) => {
+                const base = `${environment.segmentstreamUrl}/api/internal/v1/workspaces/`;
+                const response = await fetchImpl(`${base}${encodeURIComponent(environment.workspaceId)}/agent/conversations/search`, {
+                    method: "POST",
+                    redirect: "error",
+                    headers: {
+                        "content-type": "application/json",
+                        "x-segmentstream-organization-id": environment.organizationId,
+                        "x-segmentstream-runtime-identity": identityToken,
+                    },
+                    body: JSON.stringify({
+                        search,
+                        reader: {
+                            participantId: principal.id,
+                            groups: isAllowed("agent_chat:read", principal),
+                            admin: false,
+                        },
+                    }),
+                    signal: AbortSignal.any([signal, AbortSignal.timeout(15_000)]),
+                });
+                if (!response.ok) {
+                    throw new Error(`Conversation archive returned HTTP ${response.status}; ` +
+                        `request ${response.headers.get("x-request-id") ?? "unknown"}.`);
+                }
+                return Schema.decodeUnknownSync(ConversationPage)(await response.json());
+            },
+            catch: (cause) => new ConversationArchiveUnavailable({ diagnostic: "archive_request_failed", cause }),
+        }).pipe(Effect.tapError((error) => Effect.logWarning("ontology.conversations.read_failed").pipe(Effect.annotateLogs({
+            diagnostic: error.diagnostic,
+            error: describeError(error.cause, (text) => text.split(identityToken).join("[redacted]")),
+        }))));
+    };
+}

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/errors.js

@@ -385,6 +385,17 @@ export function expectedFailure(error, requestId) {
             },
         };
     }
+    if (Predicate.isTagged(error, "ConversationArchiveUnavailable")) {
+        return {
+            status: 502,
+            body: {
+                error: "conversation_archive_unavailable",
+                detail: "The conversation archive is unavailable. Try again shortly.",
+                requestId,
+                retryable: true,
+            },
+        };
+    }
     if (Predicate.isTagged(error, "AggregateUpstreamUnavailable")) {
         const { reason } = error;
         return {

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 ConversationTransport } from "../agent/conversations.js";
 import type { AgentChannelFactory } from "../agent/channel.js";
 import type { ConnectionTransportFactory } from "../connections.js";
 import { RequestId } from "../errors.js";
@@ -26,6 +27,7 @@ export interface McpServerOptions {
     readonly aggregates: Aggregates;
     /** The workspace's agent, for `agent_chat.send_message`; `undefined` without one. */
     readonly agentChannel?: AgentChannelFactory | undefined;
+    readonly conversations?: ConversationTransport | undefined;
 }
 /**
  * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can

package/dist/service/mcp/server.js

@@ -6,6 +6,7 @@ import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { SCOPE_MISMATCH } from "../aggregate-platform.js";
 import { CurrentPrincipal, withPrincipal } from "../authentication.js";
 import { catalogFor } from "../catalog.js";
+import { ConversationSearch } from "../agent/conversations.js";
 import { describeCatalog, measureDescription, measuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
 import { RequestId, errorBodyForWire, expectedFailure, internalError, schemaIssues, } from "../errors.js";
 import { publicOrigin } from "../oauth/protocol.js";
@@ -89,7 +90,11 @@ function encoded(schema, value) {
     return Schema.encodeUnknownEffect(schema)(value).pipe(Effect.orDie);
 }
 const GetArguments = Schema.Struct({ id: IdParam });
-const HistoryArguments = Schema.Struct({ id: IdParam, ...HistoryParams });
+const HistoryArguments = Schema.Struct({
+    id: IdParam,
+    ...HistoryParams,
+    conversation_before: Schema.optionalKey(Schema.String),
+});
 function structured(value) {
     return { text: JSON.stringify(value), structured: value };
 }
@@ -163,7 +168,7 @@ function toolFailure(cause, requestId) {
         isError: true,
     }));
 }
-function runTool({ built, operations, aggregate }, tool, args, request) {
+function runTool({ built, operations, aggregate, conversations }, tool, args, request) {
     return Effect.gen(function* () {
         const { target } = tool;
         switch (target.kind) {
@@ -191,9 +196,30 @@ function runTool({ built, operations, aggregate }, tool, args, request) {
                 const { id } = yield* decodeArguments(GetArguments, args);
                 return structured(yield* encoded(schemas.record, yield* operations.get(target.planned, id)));
             }
+            case "conversation-search": {
+                const search = yield* decodeArguments(ConversationSearch, args);
+                const principal = yield* CurrentPrincipal;
+                return structured(yield* conversations({ search, principal, identityToken: identityToken(request) }));
+            }
             case "history": {
-                const { id, ...params } = yield* decodeArguments(HistoryArguments, args);
-                return structured(yield* encoded(HistoryPage, yield* operations.history(target.planned, id, params)));
+                const { id, conversation_before, ...params } = yield* decodeArguments(HistoryArguments, args);
+                const audit = yield* encoded(HistoryPage, yield* operations.history(target.planned, id, params));
+                if (target.planned.name !== "agent_chat" || conversations === undefined) {
+                    return structured(audit);
+                }
+                const chat = yield* operations.get(target.planned, id);
+                const principal = yield* CurrentPrincipal;
+                const conversation = yield* conversations({
+                    principal,
+                    identityToken: identityToken(request),
+                    search: {
+                        provider: String(chat.provider),
+                        chatId: String(chat.external_id),
+                        ...(params.limit === undefined ? {} : { limit: params.limit }),
+                        ...(conversation_before === undefined ? {} : { before: conversation_before }),
+                    },
+                });
+                return structured({ ...audit, conversation });
             }
             case "action": {
                 const { [ACTION_OPTIONS_ARGUMENT]: rawOptions, ...input } = args;
@@ -433,7 +459,7 @@ function handlePost(server, verifyToken, verifyRuntime, backend) {
  * authentication. `GET` and `DELETE`, which open a server stream and end a session, answer 405.
  */
 export function mcpLayer(options) {
-    const tools = mcpTools(options.built);
+    const tools = mcpTools(options.built, options.conversations !== undefined);
     return Layer.effectDiscard(Effect.gen(function* () {
         const router = yield* HttpRouter.HttpRouter;
         const backend = yield* OntologyBackend;
@@ -442,6 +468,7 @@ export function mcpLayer(options) {
             tools,
             operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate, options.agentChannel),
             aggregate: options.aggregates.model,
+            conversations: options.conversations,
         };
         yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, options.verifyRuntime, backend));
         yield* router.add("GET", MCP_PATH, METHOD_NOT_ALLOWED);

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

@@ -26,6 +26,8 @@ export type McpToolTarget = {
     readonly kind: "me";
 } | {
     readonly kind: "aggregate";
+} | {
+    readonly kind: "conversation-search";
 };
 /** A tool of the ontology's MCP server, derived from the same plan as the HTTP routes. */
 export interface McpTool {
@@ -58,7 +60,7 @@ export declare const ACTION_OPTIONS_ARGUMENT = "_options";
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
  * `check` already refuses.
  */
-export declare function mcpTools(built: BuiltApi): ReadonlyArray<McpTool>;
+export declare function mcpTools(built: BuiltApi, conversations?: boolean): ReadonlyArray<McpTool>;
 /**
  * The tools a caller may see: those whose every permission the caller's roles grant, each with the
  * caller's input schema.

package/dist/service/mcp/tools.js

@@ -409,7 +409,7 @@ function aggregateTool(manifest) {
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
  * `check` already refuses.
  */
-export function mcpTools(built) {
+export function mcpTools(built, conversations = false) {
     const { manifest } = built.plan.ontology;
     const tools = [
         ...GLOBAL_TOOLS,
@@ -423,6 +423,50 @@ export function mcpTools(built) {
         tools.push(...readTools(planned, schemas, built));
         tools.push(...planned.actions.map((action) => actionTool(planned, action)));
     }
+    if (conversations) {
+        const index = tools.findIndex((tool) => tool.name === "agent_chat_history");
+        if (index >= 0) {
+            const tool = tools[index];
+            const rest = { ...tool };
+            delete rest.outputSchema;
+            tools[index] = {
+                ...rest,
+                description: tool.description +
+                    " Also returns conversation.events: message texts, reply/silent decisions and reasons, " +
+                    "tool calls/results and attachment references. Conversation pagination uses conversation_before " +
+                    "separately from the audit after cursor.",
+                inputSchema: {
+                    ...tool.inputSchema,
+                    properties: {
+                        ...tool.inputSchema.properties,
+                        conversation_before: {
+                            type: "string",
+                            description: "conversation.nextCursor from the previous page.",
+                        },
+                    },
+                },
+            };
+        }
+        tools.push({
+            name: "agent_chat_search",
+            title: "Search stored conversations",
+            description: "Search retained conversation messages, decisions and tool calls by text, provider chat ID, " +
+                "sender ID, topic and date range. Returns only groups you may read (agent_chat:read) and DMs " +
+                "in which you participated. Dates are ISO 8601; before is the nextCursor of the previous page. " +
+                "Workspace administrators can read all DMs through the platform API.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    ...Object.fromEntries(["q", "provider", "chatId", "threadId", "senderId", "from", "to", "before"].map((key) => [key, { type: "string", maxLength: 1000 }])),
+                    limit: { type: "integer", minimum: 1, maximum: 200 },
+                },
+            },
+            annotations: READ,
+            permissions: [],
+            target: { kind: "conversation-search" },
+        });
+    }
     const seen = new Set();
     const duplicates = tools.filter(({ name }) => seen.size === seen.add(name).size);
     if (duplicates.length > 0) {

package/dist/service/service.js

@@ -5,6 +5,9 @@ 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";
 import { agentLayer } from "./agent/server.js";
 import { makeAggregates } from "./aggregate.js";
@@ -95,6 +98,7 @@ export function createOntologyService(ontology, config) {
     const agentChannel = config.runtimeIdentity === undefined || config.agentUrl === undefined
         ? undefined
         : deployedAgentChannel(config.agentUrl);
+    const conversations = config.runtimeIdentity === undefined ? undefined : platformConversations(config);
     const aggregates = makeAggregates({
         manifest: ontology.manifest,
         transport: platformAggregates({ ...config, manifestHash: ontology.manifest.hash }),
@@ -115,6 +119,7 @@ export function createOntologyService(ontology, config) {
             replicate,
             aggregates,
             agentChannel,
+            conversations,
         }), oauthLayer({ verifyToken }));
     const agent = agentLayer({ verifyToken, verifyRuntime, exchangeSession });
     const attachments = attachmentsLayer({
@@ -126,7 +131,14 @@ export function createOntologyService(ontology, config) {
         verifyToken,
         verifyRuntime,
     });
-    const application = Layer.mergeAll(routes, mcp, agent, attachments, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, filesLayer({ plan: built.plan, verifyRuntime }), conversations === undefined
+        ? Layer.empty
+        : conversationRoutes({
+            transport: conversations,
+            verifyToken,
+            verifyRuntime,
+            exchangeSession,
+        }), DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.19.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",