@segmentstream-cloud/ontology 0.26.0 → 0.26.2

package/dist/action.d.ts

@@ -18,7 +18,9 @@ export interface ActionContext<Input, Prepared = undefined> extends PrepareConte
 /** What `prepare` may fail with: the action errors, and connection calls that failed. */
 export type PrepareError = ActionError | ConnectionError;
 /**
- * How an action behaves. Agents confirm destructive or irreversible actions before preparation.
+ * How an action behaves. Agents confirm destructive, irreversible or external actions before
+ * preparation. Actions with connections are external even when both safety hints are false.
+ * Permitted, routine reversible actions can run without confirmation.
  * Custom actions without safety labels require confirmation for backwards compatibility.
  * Idempotence does not decide whether confirmation is needed.
  */

package/dist/service/mcp/server.js

@@ -17,6 +17,7 @@ import { OntologyBackend } from "../runtime-contract.js";
 import { runtimeCredential } from "../runtime-identity.js";
 import { ActionResponse, HistoryPage, HistoryParams, IdParam, Me, } from "../schemas.js";
 import { uploadFields } from "../../storage/attachments.js";
+import { memberFileOperations } from "../member-files.js";
 import { ACTION_OPTIONS_ARGUMENT, mcpTools, visibleTools } from "./tools.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
 export const MCP_PATH = "/mcp";
@@ -169,7 +170,7 @@ function toolFailure(cause, requestId) {
         isError: true,
     }));
 }
-function runTool({ built, operations, aggregate, conversations }, tool, args, request) {
+function runTool({ built, operations, aggregate, conversations, memberFiles }, tool, args, request) {
     return Effect.gen(function* () {
         const { target } = tool;
         switch (target.kind) {
@@ -197,6 +198,8 @@ function runTool({ built, operations, aggregate, conversations }, tool, args, re
                 const { id } = yield* decodeArguments(GetArguments, args);
                 return structured(yield* encoded(schemas.record, yield* operations.get(target.planned, id)));
             }
+            case "member-file":
+                return structured(yield* memberFiles(target.operation, args, identityToken(request)));
             case "conversation-search": {
                 const search = yield* decodeArguments(ConversationSearch, args);
                 const principal = yield* CurrentPrincipal;
@@ -333,6 +336,11 @@ function instructions({ built }, permissions) {
             : []),
         "Call describe for the full catalog: properties, relationships, measures and the actions " +
             "you may run.",
+        "Use the authenticated tool annotations for confirmation: permitted actions classified as " +
+            "non-destructive and reversible need no extra approval. Destructive, irreversible or " +
+            "external actions (openWorldHint) require confirmation before preparation; idempotence " +
+            "alone does not waive it. Present confirmations in the conversation's language using " +
+            "action, entity, field and option labels and readable record titles, never tool names, ids or JSON.",
     ].join("\n\n");
 }
 function negotiate(requested) {
@@ -463,14 +471,19 @@ 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, options.conversations !== undefined);
     return Layer.effectDiscard(Effect.gen(function* () {
         const router = yield* HttpRouter.HttpRouter;
         const backend = yield* OntologyBackend;
+        const tools = mcpTools(options.built, options.conversations !== undefined, {
+            attachments: backend.attachments !== undefined,
+            files: backend.blobs !== undefined,
+        });
+        const operations = makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate, options.agentChannel);
         const server = {
             built: options.built,
             tools,
-            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate, options.agentChannel),
+            operations,
+            memberFiles: memberFileOperations(backend, options.built.plan, operations),
             aggregate: options.aggregates.model,
             conversations: options.conversations,
         };

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

@@ -1,5 +1,6 @@
 import type { JsonSchemaObject } from "../../analyze.js";
 import { type PermissionHolder } from "../../permissions.js";
+import { type MemberFileOperation } from "../member-files.js";
 import type { BuiltApi } from "../api.js";
 import type { PlannedAction, PlannedEntity } from "../plan.js";
 /** How a tool behaves, as MCP's tool annotations say it. */
@@ -28,6 +29,9 @@ export type McpToolTarget = {
     readonly kind: "aggregate";
 } | {
     readonly kind: "conversation-search";
+} | {
+    readonly kind: "member-file";
+    readonly operation: MemberFileOperation;
 };
 /** A tool of the ontology's MCP server, derived from the same plan as the HTTP routes. */
 export interface McpTool {
@@ -60,7 +64,10 @@ 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, conversations?: boolean): ReadonlyArray<McpTool>;
+export declare function mcpTools(built: BuiltApi, conversations?: boolean, storage?: {
+    attachments?: boolean;
+    files?: 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

@@ -8,6 +8,7 @@ import { queryJsonSchema } from "../../query.js";
 import { measureDescription, measuresFor, modelMeasureDescription, modelMeasuresFor, RECORDS_OR_AGGREGATES, } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
 import { uploadFields } from "../../storage/attachments.js";
+import { MEMBER_FILE_SCHEMAS } from "../member-files.js";
 import { actionDescription, requires } from "../descriptions.js";
 import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, AGGREGATE_PERIOD_UNITS, AGGREGATE_PERIODS, HistoryPage, MAXIMUM_TIMEZONE_LENGTH, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
@@ -424,7 +425,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, conversations = false) {
+export function mcpTools(built, conversations = false, storage = {}) {
     const { manifest } = built.plan.ontology;
     const tools = [
         ...GLOBAL_TOOLS,
@@ -482,6 +483,39 @@ export function mcpTools(built, conversations = false) {
             target: { kind: "conversation-search" },
         });
     }
+    const descriptions = {
+        "attachments-list": "List chat attachments by conversation (provider:chat ID), sender member UUID and ISO time range. " +
+            "Returns a bounded page and nextCursor; use before to resume. Includes expired metadata. " +
+            "Administrators with agent_chat:update may access any workspace chat; active group participants " +
+            "and DM senders may access their files.",
+        "attachments-get": "Read metadata of an accessible chat attachment. Expired or purged attachments return a clear error.",
+        "attachments-download": "Download an accessible chat attachment. Returns filename, content type, size, SHA-256 and a " +
+            "short-lived GET grant. Stream the URL's bytes with its supplied headers before expiry; do not " +
+            "forward your app bearer token.",
+        "attachments-promote": "Keep a chat attachment through an ontology action such as document.upload. Supply the action " +
+            "input without the file; the platform adopts the stored revision, fills SHA-256 when declared, " +
+            "and enforces your current action permissions. Retries reuse the promotion result.",
+        "files-download": "Download a stored blob property of a record you may read. property defaults to content. Returns " +
+            "immutable revision metadata, filename, content type, size, SHA-256 and a short-lived GET grant. " +
+            "Stream bytes from the URL with its supplied headers before expiry; do not forward your app " +
+            "bearer token.",
+    };
+    for (const operation of Object.keys(MEMBER_FILE_SCHEMAS)) {
+        if (operation === "files-download" ? !storage.files : !storage.attachments) {
+            continue;
+        }
+        tools.push({
+            name: operation.replaceAll("-", "_"),
+            title: operation.replaceAll("-", " "),
+            description: descriptions[operation],
+            inputSchema: encodedJsonSchema(MEMBER_FILE_SCHEMAS[operation]),
+            annotations: operation === "attachments-promote"
+                ? { readOnlyHint: false, idempotentHint: true, openWorldHint: true }
+                : READ,
+            permissions: [],
+            target: { kind: "member-file", operation },
+        });
+    }
     const seen = new Set();
     const duplicates = tools.filter(({ name }) => seen.size === seen.add(name).size);
     if (duplicates.length > 0) {

package/dist/service/member-file-routes.d.ts

@@ -0,0 +1,22 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type SessionExchange, type TokenVerifier } from "./authentication.js";
+import type { AgentChannelFactory } from "./agent/channel.js";
+import type { AfterCommitHook } from "./config.js";
+import type { ConnectionTransportFactory } from "./connections.js";
+import type { ApiPlan } from "./plan.js";
+import type { ReplicationKick } from "./replication.js";
+import { RequestId } from "./errors.js";
+import { OntologyBackend } from "./runtime-contract.js";
+interface MemberFileRoutesOptions {
+    readonly plan: ApiPlan;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
+    readonly agentChannel?: AgentChannelFactory | undefined;
+    readonly verifyToken: TokenVerifier;
+    readonly exchangeSession?: SessionExchange | undefined;
+}
+/** Authenticated users use these routes; the agent's receive/discard routes stay runtime-owned. */
+export declare function memberFileRoutes(options: MemberFileRoutesOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;
+export {};

package/dist/service/member-file-routes.js

@@ -0,0 +1,52 @@
+import { Cause, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { withPrincipal } from "./authentication.js";
+import { InvalidRequestBody, RequestId, failureResponse } from "./errors.js";
+import { identityToken, makeOperations } from "./operations.js";
+import { memberFileOperations } from "./member-files.js";
+import { OntologyBackend } from "./runtime-contract.js";
+/** Authenticated users use these routes; the agent's receive/discard routes stay runtime-owned. */
+export function memberFileRoutes(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const run = memberFileOperations(backend, options.plan, makeOperations(backend, options.plan, options.hooks, options.connections, options.replicate, options.agentChannel));
+        const route = (kind) => (request) => Effect.gen(function* () {
+            const bearer = yield* HttpApiBuilder.securityDecode(HttpApiSecurity.bearer).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, request));
+            const operation = Effect.gen(function* () {
+                const params = yield* HttpRouter.params;
+                let args = params;
+                if (kind === "attachments-list") {
+                    const query = Object.fromEntries(new URL(request.url, "https://app.invalid").searchParams);
+                    args = {
+                        ...query,
+                        ...(query.limit === undefined ? {} : { limit: Number(query.limit) }),
+                    };
+                }
+                else if (kind === "attachments-promote") {
+                    const body = yield* request.json.pipe(Effect.mapError(() => new InvalidRequestBody({ reason: "invalid_json", issues: [] })));
+                    args =
+                        typeof body === "object" && body !== null && !Array.isArray(body)
+                            ? { ...body, id: params.id }
+                            : body;
+                }
+                const answer = yield* run(kind, args, identityToken(request));
+                return HttpServerResponse.jsonUnsafe(answer, {
+                    headers: { "cache-control": "private, no-store" },
+                });
+            }).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+                ? Effect.failCause(cause)
+                : Effect.flatMap(RequestId, (id) => failureResponse(cause, id))));
+            return yield* withPrincipal(bearer, options.verifyToken, backend, operation, {
+                session: { request, exchange: options.exchangeSession },
+            });
+        });
+        yield* router.add("GET", "/api/ontology/attachments", route("attachments-list"));
+        yield* router.add("GET", "/api/ontology/attachments/:id", route("attachments-get"));
+        yield* router.add("GET", "/api/ontology/attachments/:id/download", route("attachments-download"));
+        yield* router.add("POST", "/api/ontology/attachments/:id/promote", route("attachments-promote"));
+        yield* router.add("GET", "/api/ontology/files/:entity/:id/:property", route("files-download"));
+        yield* router.add("GET", "/api/ontology/files/:entity/:id", route("files-download"));
+    }));
+}

package/dist/service/member-files.d.ts

@@ -0,0 +1,165 @@
+import { Effect, Schema } from "effect";
+import { CurrentPrincipal } from "./authentication.js";
+import { RequestId } from "./errors.js";
+import type { Operations } from "./operations.js";
+import type { ApiPlan } from "./plan.js";
+import type { OntologyBackend } from "./runtime-contract.js";
+export declare const AttachmentFilters: Schema.Struct<{
+    readonly conversation: Schema.optionalKey<Schema.String>;
+    readonly sender_id: 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 declare const MEMBER_FILE_SCHEMAS: {
+    "attachments-list": Schema.Struct<{
+        readonly conversation: Schema.optionalKey<Schema.String>;
+        readonly sender_id: 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>;
+    }>;
+    "attachments-get": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "attachments-download": Schema.Struct<{
+        readonly id: Schema.String;
+    }>;
+    "attachments-promote": Schema.Struct<{
+        readonly id: Schema.String;
+        readonly entity: Schema.String;
+        readonly action: Schema.String;
+        readonly input: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+        readonly field: Schema.optionalKey<Schema.String>;
+        readonly record_id: Schema.optionalKey<Schema.String>;
+    }>;
+    "files-download": Schema.Struct<{
+        readonly entity: Schema.String;
+        readonly id: Schema.String;
+        readonly property: Schema.optionalKey<Schema.String>;
+    }>;
+};
+export type MemberFileOperation = keyof typeof MEMBER_FILE_SCHEMAS;
+export declare function grantForWire(grant: {
+    url: string;
+    method: string;
+    headers: Readonly<Record<string, string>>;
+    expiresAt: string;
+}): {
+    url: string;
+    method: string;
+    headers: Readonly<Record<string, string>>;
+    expires_at: string;
+};
+export declare function attachmentForWire(attachment: import("../storage/attachments.js").AttachmentView): {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+    sha256: string;
+    state: string;
+    created_at: string;
+    expires_at: string;
+    promotion: unknown;
+    conversation: string | undefined;
+    sender_id: string | undefined;
+};
+/** The member REST and MCP surfaces run the same runtime operations and action pipeline. */
+export declare function memberFileOperations(backend: OntologyBackend["Service"], plan: ApiPlan, operations: Operations): (kind: MemberFileOperation, args: unknown, identityToken?: string) => Effect.Effect<{
+    download: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        expires_at: string;
+    };
+    file: {
+        id: string;
+        entity: string;
+        property: string;
+        revision_id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+    attachment?: undefined;
+} | {
+    attachments: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    }[];
+    nextCursor: string | null;
+    attachment?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    deduplicated: boolean;
+    result: {} | null;
+    attachments?: undefined;
+    nextCursor?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+    download?: undefined;
+} | {
+    attachment: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        sha256: string;
+        state: string;
+        created_at: string;
+        expires_at: string;
+        promotion: unknown;
+        conversation: string | undefined;
+        sender_id: string | undefined;
+    };
+    download: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        expires_at: string;
+    };
+    attachments?: undefined;
+    nextCursor?: undefined;
+}, unknown, RequestId | CurrentPrincipal>;

package/dist/service/member-files.js

@@ -0,0 +1,145 @@
+import { Effect, Schema } from "effect";
+import { NotFound } from "../errors.js";
+import { schemaIssues } from "../runtime/validation.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { InvalidRequestBody, RequestId } from "./errors.js";
+const Id = Schema.String.check(Schema.isUUID());
+const DateTime = Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/));
+export const AttachmentFilters = Schema.Struct({
+    conversation: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200))),
+    sender_id: Schema.optionalKey(Id),
+    from: Schema.optionalKey(DateTime),
+    to: Schema.optionalKey(DateTime),
+    before: Schema.optionalKey(Id),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
+});
+const AttachmentId = Schema.Struct({ id: Id });
+const Promotion = Schema.Struct({
+    id: Id,
+    entity: Schema.String,
+    action: Schema.String,
+    input: Schema.optionalKey(Schema.Record(Schema.String, Schema.Unknown)),
+    field: Schema.optionalKey(Schema.String),
+    record_id: Schema.optionalKey(Id),
+});
+const File = Schema.Struct({
+    entity: Schema.String,
+    id: Id,
+    property: Schema.optionalKey(Schema.String),
+});
+export const MEMBER_FILE_SCHEMAS = {
+    "attachments-list": AttachmentFilters,
+    "attachments-get": AttachmentId,
+    "attachments-download": AttachmentId,
+    "attachments-promote": Promotion,
+    "files-download": File,
+};
+export function grantForWire(grant) {
+    return {
+        url: grant.url,
+        method: grant.method,
+        headers: grant.headers,
+        expires_at: grant.expiresAt,
+    };
+}
+export 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,
+        conversation: attachment.conversation,
+        sender_id: attachment.senderId,
+    };
+}
+function decode(schema, input) {
+    return Schema.decodeUnknownEffect(schema)(input, { onExcessProperty: "error" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error) })));
+}
+/** The member REST and MCP surfaces run the same runtime operations and action pipeline. */
+export function memberFileOperations(backend, plan, operations) {
+    return (kind, args, identityToken) => Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const requestId = yield* RequestId;
+        if (kind === "files-download") {
+            const input = yield* decode(File, args);
+            if (!backend.blobs) {
+                return yield* new NotFound({
+                    entity: input.entity,
+                    id: input.id,
+                    message: "File storage is unavailable.",
+                });
+            }
+            const result = yield* backend.blobs.downloadFile(input.entity, input.id, input.property ?? "content", {}, principal);
+            return { ...result, download: grantForWire(result.download) };
+        }
+        if (principal.kind !== "member") {
+            return yield* new NotFound({
+                entity: "attachment",
+                id: "",
+                message: "Attachment not found.",
+            });
+        }
+        const attachments = backend.attachments;
+        if (!attachments) {
+            return yield* new NotFound({
+                entity: "attachment",
+                id: "",
+                message: "Attachment storage is unavailable.",
+            });
+        }
+        if (kind === "attachments-list") {
+            const input = yield* decode(AttachmentFilters, args);
+            if ((input.from !== undefined && !Number.isFinite(Date.parse(input.from))) ||
+                (input.to !== undefined && !Number.isFinite(Date.parse(input.to))) ||
+                (input.from !== undefined &&
+                    input.to !== undefined &&
+                    Date.parse(input.from) > Date.parse(input.to))) {
+                return yield* new InvalidRequestBody({ reason: "invalid_request", issues: [] });
+            }
+            const { sender_id, ...rest } = input;
+            const result = yield* attachments.listForMember({ ...rest, ...(sender_id === undefined ? {} : { senderId: sender_id }) }, principal);
+            return {
+                attachments: result.attachments.map(attachmentForWire),
+                nextCursor: result.nextCursor,
+            };
+        }
+        if (kind === "attachments-promote") {
+            const input = yield* decode(Promotion, args);
+            const promoted = yield* attachments.promoteForMember(input.id, {
+                entity: input.entity,
+                action: input.action,
+                input: input.input ?? {},
+                ...(input.field === undefined ? {} : { field: input.field }),
+                ...(input.record_id === undefined ? {} : { recordId: input.record_id }),
+            }, principal, (call) => Effect.gen(function* () {
+                const entity = plan.entities.find((item) => item.name === call.entity);
+                const action = entity?.actions.find((item) => item.name === call.action);
+                if (!entity || !action) {
+                    return yield* Effect.die(new Error("The promotion action was not planned."));
+                }
+                const answer = yield* operations.runAction(entity, action, {
+                    input: call.input,
+                    options: call.options,
+                    validateOnly: false,
+                    identityToken,
+                });
+                return { result: answer.result, edits: answer.edits };
+            }).pipe(Effect.provideService(CurrentPrincipal, principal), Effect.provideService(RequestId, requestId)));
+            return { ...promoted, attachment: attachmentForWire(promoted.attachment) };
+        }
+        const { id } = yield* decode(AttachmentId, args);
+        if (kind === "attachments-get") {
+            return { attachment: attachmentForWire(yield* attachments.getForMember(id, principal)) };
+        }
+        const result = yield* attachments.readForMember(id, principal);
+        return {
+            attachment: attachmentForWire(result.attachment),
+            download: grantForWire(result.download),
+        };
+    });
+}

package/dist/service/service.js

@@ -4,6 +4,7 @@ import { HttpApiBuilder } from "effect/unstable/httpapi";
 import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-auth.js";
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
+import { memberFileRoutes } from "./member-file-routes.js";
 import { attachmentsLayer } from "./agent/attachments.js";
 import { filesLayer } from "./agent/files.js";
 import { platformConversations } from "./agent/conversations.js";
@@ -131,7 +132,15 @@ export function createOntologyService(ontology, config) {
         verifyToken,
         verifyRuntime,
     });
-    const application = Layer.mergeAll(routes, mcp, agent, attachments, filesLayer({ plan: built.plan, verifyRuntime }), conversations === undefined
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, memberFileRoutes({
+        plan: built.plan,
+        hooks,
+        connections,
+        replicate,
+        agentChannel,
+        verifyToken,
+        exchangeSession,
+    }), filesLayer({ plan: built.plan, verifyRuntime }), conversations === undefined
         ? Layer.empty
         : conversationRoutes({
             transport: conversations,

package/dist/storage/attachments.d.ts

@@ -30,6 +30,8 @@ export interface AttachmentCaller {
      * that reads them. Group attachments are shared across authorized sessions in the same chat.
      */
     readonly sessionId?: string;
+    /** Trusted user boundary; never accepted from agent tool arguments. */
+    readonly access?: "member";
 }
 export interface ReceiveAttachment {
     readonly source: (typeof ATTACHMENT_SOURCES)[number];
@@ -50,6 +52,16 @@ export interface AttachmentView {
     readonly createdAt: string;
     readonly expiresAt: string;
     readonly promotion: unknown;
+    readonly conversation?: string;
+    readonly senderId?: string;
+}
+export interface AttachmentSearch {
+    readonly conversation?: string;
+    readonly senderId?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly before?: string;
+    readonly limit?: number;
 }
 export interface PromotionTarget {
     /** The entity whose action adopts the file, such as `document`. */
@@ -103,6 +115,20 @@ export declare function attachmentRuntime(ontology: Ontology, sql: SqlClient.Sql
         deduplicated: boolean;
         result: {} | null;
     }, unknown, never>;
+    listForMember: (filters: AttachmentSearch, principal: Principal) => Effect.Effect<{
+        attachments: AttachmentView[];
+        nextCursor: string | null;
+    }, PermissionDenied | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    getForMember: (id: string, principal: Principal) => Effect.Effect<AttachmentView, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    readForMember: (id: string, principal: Principal) => Effect.Effect<{
+        attachment: AttachmentView;
+        download: TransferGrant;
+    }, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    promoteForMember: (id: string, target: PromotionTarget, principal: Principal, run: PromotionRunner) => Effect.Effect<{
+        attachment: AttachmentView;
+        deduplicated: boolean;
+        result: {} | null;
+    }, unknown, never>;
 };
 export type AttachmentRuntime = ReturnType<typeof attachmentRuntime>;
 export type AttachmentFailure = ActionRejected | Conflict | NotFound | PermissionDenied;

package/dist/storage/attachments.js

@@ -96,6 +96,8 @@ function view(row) {
         createdAt: row.created_at,
         expiresAt: row.expires_at,
         promotion: row.promotion ?? null,
+        conversation: row.conversation,
+        senderId: row.owner_id,
     };
 }
 /** Persisted phases surround every provider call; no external I/O holds a database transaction. */
@@ -110,6 +112,14 @@ export function attachmentRuntime(ontology, sql, provider) {
             return "denied";
         }
         yield* authorizeBlobOperation(ontology, sql, caller.principal.id, []);
+        if (caller.access === "member") {
+            const admin = yield* authorizeBlobOperation(ontology, sql, caller.principal.id, [
+                "agent_chat:update",
+            ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+            if (admin) {
+                return "administrator";
+            }
+        }
         const separator = caller.conversation.indexOf(":");
         const [chat] = yield* sql.unsafe(`SELECT id::text FROM "agent_chat"
          WHERE provider = $1 AND external_id = $2 FOR SHARE`, [caller.conversation.slice(0, separator), caller.conversation.slice(separator + 1)]);
@@ -148,19 +158,21 @@ export function attachmentRuntime(ontology, sql, provider) {
             caller.principal.id,
             caller.conversation,
             binding.branchId,
-            access === "group" && scope === "session",
+            (access === "group" || access === "administrator") && scope === "session",
         ]);
         const row = rows[0];
         if (!row) {
             return yield* missing(id);
         }
         if (access === "private" &&
+            caller.access !== "member" &&
             scope === "session" &&
             row.session_id !== null &&
             row.session_id !== caller.sessionId) {
             return yield* missing(id);
         }
         if (access === "private" &&
+            caller.access !== "member" &&
             scope === "session" &&
             row.session_id === null &&
             caller.sessionId !== undefined) {
@@ -401,6 +413,9 @@ export function attachmentRuntime(ontology, sql, provider) {
         const prepared = yield* sql.withTransaction(Effect.gen(function* () {
             const row = yield* load(id, caller);
             yield* authorizeBlobOperation(ontology, sql, caller.principal.id, found.permissions, caller.principal.execution);
+            if (caller.access === "member" && row.expired) {
+                return yield* unavailable("The attachment expired or was purged.");
+            }
             if (row.state === "promoted") {
                 return { kind: "done", row };
             }
@@ -419,7 +434,7 @@ export function attachmentRuntime(ontology, sql, provider) {
              WHERE sha256 = $1 AND branch_id = $2 AND state = 'promoted' AND id <> $3::uuid
                AND promotion->>'action' = $4 AND promotion->>'deduplicated_from' IS NULL
                AND conversation = $5 AND (owner_id = $6::uuid OR $7)
-               AND ($7 OR session_id IS NULL OR session_id = $8)
+               AND ($7 OR $9 OR session_id IS NULL OR session_id = $8)
              ORDER BY created_at LIMIT 1`, [
                 row.sha256,
                 binding.branchId,
@@ -427,8 +442,9 @@ export function attachmentRuntime(ontology, sql, provider) {
                 qualified,
                 caller.conversation,
                 caller.principal.id,
-                (yield* accessScope(caller)) === "group",
+                ["group", "administrator"].includes(yield* accessScope(caller)),
                 caller.sessionId ?? null,
+                caller.access === "member",
             ]);
             if (earlier) {
                 const promotion = {
@@ -528,7 +544,106 @@ export function attachmentRuntime(ontology, sql, provider) {
         }));
         return { attachment: view(promoted), deduplicated: false, result: outcome.result ?? null };
     });
-    return { receive, complete, list, read, discard, promote };
+    /** Resolve the chat from storage, then authorize with the same locked loader. */
+    const memberCaller = (id, principal) => sql.withTransaction(Effect.gen(function* () {
+        if (!/^[0-9a-f-]{36}$/i.test(id)) {
+            return yield* missing(id);
+        }
+        const [row] = yield* sql.unsafe(`SELECT conversation FROM "${ATTACHMENTS_TABLE}" WHERE id = $1::uuid AND branch_id = $2`, [id, binding.branchId]);
+        if (!row) {
+            return yield* missing(id);
+        }
+        const caller = {
+            principal,
+            conversation: row.conversation,
+            access: "member",
+        };
+        yield* load(id, caller);
+        return caller;
+    }));
+    const getForMember = (id, principal) => Effect.gen(function* () {
+        const caller = yield* memberCaller(id, principal);
+        const row = yield* sql.withTransaction(load(id, caller));
+        if (!READABLE.has(row.state) || row.expired) {
+            return yield* unavailable("The attachment expired, was purged, or is not ready.");
+        }
+        return view(row);
+    });
+    const readForMember = (id, principal) => Effect.gen(function* () {
+        return yield* read(id, yield* memberCaller(id, principal));
+    });
+    const promoteForMember = (id, target, principal, run) => Effect.gen(function* () {
+        return yield* promote(id, target, yield* memberCaller(id, principal), run);
+    });
+    const listForMember = (filters, principal) => sql.withTransaction(Effect.gen(function* () {
+        const [member] = yield* sql.unsafe(`SELECT kind::text, active FROM "user" WHERE id = $1::uuid FOR SHARE`, [principal.id]);
+        if (member?.kind !== "member" || !member.active) {
+            return yield* missing("chat");
+        }
+        yield* authorizeBlobOperation(ontology, sql, principal.id, []);
+        const admin = yield* authorizeBlobOperation(ontology, sql, principal.id, [
+            "agent_chat:update",
+        ]).pipe(Effect.as(true), Effect.catchTag("PermissionDenied", () => Effect.succeed(false)));
+        if (filters.conversation !== undefined) {
+            const scope = yield* accessScope({
+                principal,
+                conversation: filters.conversation,
+                access: "member",
+            });
+            if (scope === "denied") {
+                return yield* missing("chat");
+            }
+            if (scope === "private") {
+                const [sent] = yield* sql.unsafe(`SELECT 1 FROM "${ATTACHMENTS_TABLE}" WHERE branch_id = $1 AND conversation = $2
+                AND owner_id = $3::uuid LIMIT 1`, [binding.branchId, filters.conversation, principal.id]);
+                if (sent === undefined) {
+                    return yield* missing("chat");
+                }
+            }
+        }
+        const limit = filters.limit ?? 50;
+        const rows = yield* sql.unsafe(`${SELECT} WHERE a.branch_id = $1
+          AND ($2 OR EXISTS (
+            SELECT 1 FROM "agent_chat" c JOIN "agent_chat_members" m ON m.agent_chat_id = c.id
+            WHERE c.provider || ':' || c.external_id = a.conversation AND m.user_id = $3::uuid
+          ) OR (a.owner_id = $3::uuid AND NOT EXISTS (
+            SELECT 1 FROM "agent_chat" c WHERE c.provider || ':' || c.external_id = a.conversation
+          )))
+          AND ($4::text IS NULL OR a.conversation = $4)
+          AND ($5::uuid IS NULL OR a.owner_id = $5::uuid)
+          AND ($6::timestamptz IS NULL OR a.created_at >= $6::timestamptz)
+          AND ($7::timestamptz IS NULL OR a.created_at <= $7::timestamptz)
+          AND ($8::uuid IS NULL OR (a.created_at, a.id) < (
+            SELECT created_at, id FROM "${ATTACHMENTS_TABLE}" WHERE id = $8::uuid AND branch_id = $1
+          ))
+        ORDER BY a.created_at DESC, a.id DESC LIMIT $9`, [
+            binding.branchId,
+            admin,
+            principal.id,
+            filters.conversation ?? null,
+            filters.senderId ?? null,
+            filters.from ?? null,
+            filters.to ?? null,
+            filters.before ?? null,
+            limit + 1,
+        ]);
+        return {
+            attachments: rows.slice(0, limit).map(view),
+            nextCursor: rows.length > limit ? rows[limit - 1].id : null,
+        };
+    }));
+    return {
+        receive,
+        complete,
+        list,
+        read,
+        discard,
+        promote,
+        listForMember,
+        getForMember,
+        readForMember,
+        promoteForMember,
+    };
 }
 /**
  * Expires attachments past their deadline and removes the bytes of every expired or discarded one

package/dist/storage/neon.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListMultipartUploadsCommand, ListPartsCommand, S3Client, UploadPartCommand, } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import { Effect } from "effect";
@@ -168,6 +169,53 @@ export function neonBlobProvider(binding) {
                 throw error;
             }
         }),
+        sha256: (key, size) => attempt("blob.sha256", async () => {
+            const response = await client.send(new GetObjectCommand(object(key)));
+            if (!response.Body) {
+                throw new Error("Neon returned no object body.");
+            }
+            const hash = createHash("sha256");
+            const reader = response.Body.transformToWebStream().getReader();
+            let received = 0;
+            let failure;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    received += value.byteLength;
+                    if (received > size) {
+                        throw new Error("The stored object exceeds its declared size.");
+                    }
+                    hash.update(value);
+                }
+                if (received !== size) {
+                    throw new Error("The stored object does not match its declared size.");
+                }
+                return hash.digest("hex");
+            }
+            catch (cause) {
+                failure = cause;
+                throw cause;
+            }
+            finally {
+                try {
+                    await reader.cancel();
+                }
+                catch (cleanup) {
+                    if (failure !== undefined) {
+                        throw new AggregateError([failure, cleanup], "Hashing and stream cleanup failed.", {
+                            cause: cleanup,
+                        });
+                    }
+                    throw cleanup;
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            }
+        }),
         readPrefix: (key) => attempt("blob.read_prefix", async () => {
             const response = await client.send(new GetObjectCommand({ ...object(key), Range: "bytes=0-511" }));
             if (!response.Body) {

package/dist/storage/provider.d.ts

@@ -60,6 +60,8 @@ declare const BlobProvider_base: Context.ServiceClass<BlobProvider, "@segmentstr
         }>;
     }) => Effect.Effect<void, BlobStorageError>;
     readonly inspect: (key: string) => Effect.Effect<StoredObject | undefined, BlobStorageError>;
+    /** Hash immutable content without buffering it. */
+    readonly sha256: (key: string, size: number) => Effect.Effect<string, BlobStorageError>;
     readonly readPrefix: (key: string) => Effect.Effect<Uint8Array, BlobStorageError>;
     /** The whole object, at most `maxBytes`; for verifying an agent attachment's digest. */
     readonly read: (key: string, maxBytes: number) => Effect.Effect<Uint8Array, BlobStorageError>;

package/dist/storage/sessions.d.ts

@@ -82,6 +82,25 @@ export declare function blobRuntime(ontology: Ontology, sql: SqlClient.SqlClient
         state: string;
         expiresAt: string;
     }, import("../errors.js").PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
-    download: (entityName: string, recordId: string, propertyName: string, input: typeof DownloadRequest.Type, principal: Principal) => Effect.Effect<import("./provider.js").TransferGrant, import("../errors.js").PermissionDenied | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    download: (entityName: string, recordId: string, propertyName: string, input: {
+        readonly inline?: boolean | undefined;
+        readonly revisionId?: string | undefined;
+    }, principal: Principal) => Effect.Effect<import("./provider.js").TransferGrant, import("../errors.js").PermissionDenied | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    downloadFile: (entityName: string, recordId: string, propertyName: string, input: {
+        readonly inline?: boolean | undefined;
+        readonly revisionId?: string | undefined;
+    }, principal: Principal) => Effect.Effect<{
+        file: {
+            id: string;
+            entity: string;
+            property: string;
+            revision_id: string;
+            filename: string;
+            content_type: string;
+            size: number;
+            sha256: string;
+        };
+        download: import("./provider.js").TransferGrant;
+    }, import("../errors.js").PermissionDenied | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
 };
 export type BlobRuntime = ReturnType<typeof blobRuntime>;

package/dist/storage/sessions.js

@@ -299,7 +299,7 @@ export function blobRuntime(ontology, sql, provider) {
       WHERE id = $1::uuid`, [id]);
         return view(yield* load(id, principal));
     }));
-    const download = (entityName, recordId, propertyName, input, principal) => Effect.gen(function* () {
+    const prepareDownload = (entityName, recordId, propertyName, input, principal) => Effect.gen(function* () {
         const entity = ontology.manifest.entities.find((item) => item.name === entityName);
         const property = entity?.properties.find((item) => item.name === propertyName && item.type === "blob");
         if (!entity || !property) {
@@ -319,9 +319,10 @@ export function blobRuntime(ontology, sql, provider) {
                 });
                 revisionId = record[propertyName]?.id;
             }
-            const [blob] = yield* sql.unsafe(`SELECT b.key, b.filename, b.content_type FROM "_blobs" b JOIN "_blob_references" r ON r.blob_id = b.id
-         WHERE b.id = $1::uuid AND b.state = 'retained' AND r.entity_id = $2
-           AND r.property_id = $3 AND r.record_id = $4::uuid FOR SHARE OF b`, [revisionId ?? null, entity.id, property.name, recordId]);
+            const [blob] = yield* sql.unsafe(`SELECT b.id::text, b.key, b.filename, b.content_type, b.size::text
+           FROM "_blobs" b JOIN "_blob_references" r ON r.blob_id = b.id
+         WHERE b.id = $1::uuid AND b.state = 'retained' AND b.branch_id = $5 AND r.entity_id = $2
+           AND r.property_id = $3 AND r.record_id = $4::uuid FOR SHARE OF b`, [revisionId ?? null, entity.id, property.name, recordId, binding.branchId]);
             if (!blob) {
                 return yield* new NotFound({
                     entity: entityName,
@@ -331,13 +332,42 @@ export function blobRuntime(ontology, sql, provider) {
             }
             return blob;
         }));
+        return blob;
+    });
+    const download = (...args) => Effect.gen(function* () {
+        const blob = yield* prepareDownload(...args);
         return yield* provider.download({
             key: blob.key,
             filename: blob.filename,
             contentType: blob.content_type,
-            inline: input.inline === true &&
+            inline: args[3].inline === true &&
                 ["image/jpeg", "image/png"].includes(blob.content_type.toLowerCase()),
         });
     });
-    return { begin, status, part, complete, cancel, download };
+    const downloadFile = (...args) => Effect.gen(function* () {
+        const blob = yield* prepareDownload(...args);
+        const sha256 = yield* provider.sha256(blob.key, Number(blob.size));
+        // Recheck live access after hashing; no provider I/O holds a database transaction.
+        yield* prepareDownload(args[0], args[1], args[2], { revisionId: blob.id }, args[4]);
+        const grant = yield* provider.download({
+            key: blob.key,
+            filename: blob.filename,
+            contentType: blob.content_type,
+            inline: false,
+        });
+        return {
+            file: {
+                id: args[1],
+                entity: args[0],
+                property: args[2],
+                revision_id: blob.id,
+                filename: blob.filename,
+                content_type: blob.content_type,
+                size: Number(blob.size),
+                sha256,
+            },
+            download: grant,
+        };
+    });
+    return { begin, status, part, complete, cancel, download, downloadFile };
 }

package/package.json

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