@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/agent/attachments.js

@@ -0,0 +1,228 @@
+import { PermissionDenied } from "../../errors.js";
+import { consumeChatEnvelope } from "../chat/envelope.js";
+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 } from "../errors.js";
+import { identityToken, makeOperations } from "../operations.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { authenticateAgentCaller } from "./authentication.js";
+import { checkRuntimeOperation } from "../mcp/runtime-policy.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`
+ * while they are active. 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. Storage checks current group participation or chat administration; private files
+ * remain confined to their sender and session.
+ */
+export const ATTACHMENTS_PATH = `${AGENT_PATH}/attachments`;
+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({
+    _meta: Schema.optionalKey(Schema.Struct({ _segmentstream: Schema.optionalKey(Schema.Unknown) })),
+    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);
+        /** Authenticates the runtime, then the member it acts for, the chat and the session. */
+        const asAgent = (answer) => (request) => Effect.gen(function* () {
+            const authenticated = yield* authenticateAgentCaller({
+                request,
+                agents,
+                verify: verifyRuntime,
+                allowUnpairedMember: true,
+            });
+            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* () {
+            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 metadata = yield* consumeChatEnvelope(promotion._meta ?? {}, {
+                kind: "runtime",
+                subjectId: caller.principal.id,
+            });
+            const attachmentId = yield* idOf;
+            const { attachments: sourceAttachments, ...sourceFields } = metadata.envelope?.source ?? {};
+            const matchingAttachments = sourceAttachments?.filter((attachment) => attachment.staged_id === attachmentId);
+            const source = metadata.envelope?.source === undefined
+                ? undefined
+                : {
+                    ...metadata.envelope.source,
+                    ...sourceFields,
+                    attachments: matchingAttachments?.length ? matchingAttachments : undefined,
+                };
+            const principal = source === undefined
+                ? caller.principal
+                : yield* agents.actingMember(caller.principal.id, source.provider);
+            if (principal === undefined) {
+                return yield* new PermissionDenied({
+                    message: "Runtime attachment provenance requires a current channel pairing.",
+                });
+            }
+            // This file route permits unpaired members; do not grant posting provenance.
+            // It is nevertheless a verified runtime path and cannot invoke the agent.
+            yield* checkRuntimeOperation({ kind: "runtime", subjectId: caller.principal.id }, promotion);
+            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, principal }, (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,
+                    ...(source === undefined ? {} : { runtime: { source } }),
+                    validateOnly: false,
+                    options: call.options,
+                    identityToken: identityToken(request),
+                })
+                    .pipe(Effect.provideService(CurrentPrincipal, principal), Effect.provideService(RequestId, requestId));
+                return { result: answer.result, edits: answer.edits };
+            }));
+            return json({
+                attachment: attachmentForWire(promoted.attachment),
+                deduplicated: promoted.deduplicated,
+                result: promoted.result,
+            });
+        }))));
+    }));
+}

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

@@ -0,0 +1,22 @@
+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";
+/** Authenticate the runtime and resolve its member; attachment storage also checks chat access. */
+export declare function authenticateAgentCaller(input: {
+    readonly request: HttpServerRequest.HttpServerRequest;
+    readonly agents: AgentStore;
+    readonly verify: RuntimeTokenVerifier;
+    /** Temporary attachments authorize active members against the chat registry, without a pairing. */
+    readonly allowUnpairedMember?: boolean;
+}): 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,58 @@
+import { Effect, Redacted } from "effect";
+import { HttpServerRequest } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { RequestId, forbidden, notFound, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+import { ACT_AS_HEADER, AGENT_TASK_HEADER, agentTaskSecret, 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}$/;
+/** Authenticate the runtime and resolve its member; attachment storage also checks chat access. */
+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."));
+        }
+        // Attachments and member files are a member's; a task, acting as a workflow's user, has none.
+        if (agentTaskSecret(request) !== undefined) {
+            return denied(forbidden(requestId, `This route does not accept ${AGENT_TASK_HEADER}.`));
+        }
+        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
+            : input.allowUnpairedMember
+                ? (yield* agents.member(actAs))?.principal
+                : yield* agents.actingMember(actAs);
+        if (member === undefined) {
+            return denied(input.allowUnpairedMember
+                ? notFound(requestId, "Attachment not found.")
+                : 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/confirmations.d.ts

@@ -0,0 +1,5 @@
+import { Effect } from "effect";
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import type { ConfirmationStore } from "../../runtime/confirmations.js";
+/** Mounted only behind the existing deployment-runtime verifier. No member/model endpoint. */
+export declare function confirmationCommand(store: ConfirmationStore): (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse, never, never>;

package/dist/service/agent/confirmations.js

@@ -0,0 +1,73 @@
+import { Effect, Schema } from "effect";
+import { HttpServerResponse } from "effect/unstable/http";
+const Key = Schema.String.check(Schema.isPattern(/^[0-9a-f]{20}$/));
+const Hash = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/));
+const Member = Schema.String.check(Schema.isUUID());
+const Record = Schema.Struct({
+    id: Schema.String.check(Schema.isPattern(/^hq:[0-9a-f]{64}$/)),
+    key: Key,
+    memberId: Member,
+    inputHash: Hash,
+    expiresAt: Schema.Number,
+    status: Schema.Literal("pending"),
+    data: Schema.Record(Schema.String, Schema.Unknown),
+});
+const Command = Schema.Union([
+    Schema.Struct({ operation: Schema.Literal("create"), record: Record }),
+    Schema.Struct({
+        operation: Schema.Literal("attach"),
+        key: Key,
+        messageId: Schema.String,
+        address: Schema.String,
+    }),
+    Schema.Struct({ operation: Schema.Literal("read"), key: Key }),
+    Schema.Struct({
+        operation: Schema.Literal("decide"),
+        key: Key,
+        memberId: Member,
+        inputHash: Hash,
+        decision: Schema.Literals(["approve", "cancel", "expire"]),
+    }),
+    Schema.Struct({
+        operation: Schema.Literal("finish"),
+        key: Key,
+        status: Schema.Literals(["done", "failed"]),
+    }),
+    Schema.Struct({
+        operation: Schema.Literal("expired"),
+        chatId: Schema.optionalKey(Schema.String),
+    }),
+]);
+/** Mounted only behind the existing deployment-runtime verifier. No member/model endpoint. */
+export function confirmationCommand(store) {
+    return (request) => Effect.gen(function* () {
+        const text = yield* request.text;
+        if (text.length > 100_000) {
+            return HttpServerResponse.empty({ status: 413 });
+        }
+        const value = yield* Effect.try(() => JSON.parse(text));
+        const command = yield* Schema.decodeUnknownEffect(Command)(value);
+        let result;
+        switch (command.operation) {
+            case "create":
+                result = yield* store.create(command.record);
+                break;
+            case "attach":
+                yield* store.attach(command.key, command.messageId, command.address);
+                break;
+            case "read":
+                result = yield* store.read(command.key);
+                break;
+            case "decide":
+                result = yield* store.decide(command);
+                break;
+            case "finish":
+                yield* store.finish(command.key, command.status);
+                break;
+            case "expired":
+                result = yield* store.expired(command.chatId);
+                break;
+        }
+        return HttpServerResponse.jsonUnsafe({ result: result ?? null }, { headers: { "cache-control": "no-store" } });
+    }).pipe(Effect.catch(() => Effect.succeed(HttpServerResponse.empty({ status: 400 }))));
+}

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,45 @@
+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";
+import { withChatMembership } from "../chat/resolve.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;
+        const transport = withChatMembership(options.transport, backend);
+        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* 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,40 @@
+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;
+    /**
+     * Group conversations (`provider:chatId`) the member is in. Their history is readable without
+     * `agent_chat:read`, as their attachments are; see `withChatMembership`.
+     */
+    readonly memberGroups?: ReadonlyArray<string>;
+}) => 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,69 @@
+import { Effect, Schema } from "effect";
+import { PermissionDenied } from "../../errors.js";
+import { isAllowed } from "../../permissions.js";
+import { describeError } from "../metric-query-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, memberGroups }) => {
+        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),
+                            groupChats: memberGroups ?? [],
+                            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);
+    }));
+}