@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/chat/reads.d.ts

@@ -0,0 +1,25 @@
+import type { ChatAttributionSettings } from "../../chat.js";
+import { Effect } from "effect";
+import { ActionRejected, PermissionDenied } from "../../errors.js";
+import { CurrentPrincipal } from "../authentication.js";
+import type { OntologyBackend } from "../runtime-contract.js";
+import type { ConversationTransport } from "../agent/conversations.js";
+import type { ChatList, ChatHistory } from "./schemas.js";
+export declare function chatReads(backend: OntologyBackend["Service"], conversations?: ConversationTransport, attribution?: ChatAttributionSettings): {
+    list: (input: typeof ChatList.Type) => Effect.Effect<{
+        items: {
+            id: string;
+            title: string;
+            provider: string;
+            external_id: string;
+            attribution: string | null;
+        }[];
+        next_cursor: string | null;
+    }, ActionRejected | PermissionDenied | import("../../errors.js").NotFound, CurrentPrincipal>;
+    history: (input: typeof ChatHistory.Type, identityToken: string | undefined) => Effect.Effect<{
+        readonly events: readonly {
+            readonly [x: string]: unknown;
+        }[];
+        readonly nextCursor: string | null;
+    }, ActionRejected | PermissionDenied | import("../agent/conversations.js").ConversationArchiveUnavailable, CurrentPrincipal>;
+};

package/dist/service/chat/reads.js

@@ -0,0 +1,75 @@
+import { Effect } from "effect";
+import { ActionRejected, PermissionDenied } from "../../errors.js";
+import { isAllowed } from "../../permissions.js";
+import { CurrentPrincipal } from "../authentication.js";
+import { currentCaller } from "../caller-context.js";
+import { chatAttribution } from "./attribution.js";
+import { chatResolver, groupConversation, isChatMember } from "./resolve.js";
+export function chatReads(backend, conversations, attribution) {
+    return {
+        list: (input) => Effect.gen(function* () {
+            const principal = yield* CurrentPrincipal;
+            const caller = yield* currentCaller;
+            const query = input.query?.toLowerCase();
+            const items = (yield* chatResolver(backend, principal).list(input.chat))
+                .filter((item) => query === undefined || item.title.toLowerCase().includes(query))
+                .sort((a, b) => a.id.localeCompare(b.id));
+            const user = yield* backend.get({ entity: "user", id: principal.id });
+            const start = input.after === undefined ? 0 : items.findIndex((item) => item.id === input.after) + 1;
+            if (input.after !== undefined && start === 0) {
+                return yield* new ActionRejected({
+                    message: "The chat cursor is invalid. Restart discovery.",
+                });
+            }
+            const limit = input.limit ?? 50;
+            const selected = items.slice(start, start + limit).map((item) => ({
+                id: item.id,
+                title: item.title,
+                provider: item.provider,
+                external_id: item.external_id,
+                attribution: chatAttribution(caller, String(user.name), attribution),
+            }));
+            return {
+                items: selected,
+                next_cursor: start + limit < items.length ? selected.at(-1).id : null,
+            };
+        }),
+        history: (input, identityToken) => Effect.gen(function* () {
+            const principal = yield* CurrentPrincipal;
+            if (principal.kind !== "member") {
+                return yield* new PermissionDenied({ message: "Only members may read conversations." });
+            }
+            const target = yield* chatResolver(backend, principal, "telegram", {
+                memberGroups: true,
+            }).resolve(input.chat);
+            // A group's members read its history, as they read its attachments; agent_chat:read reads
+            // every group. A private chat is read only by its participant.
+            const member = target.kind === "group" &&
+                !isAllowed("agent_chat:read", principal) &&
+                (yield* isChatMember(backend, principal, target.id));
+            if (target.kind === "group"
+                ? !isAllowed("agent_chat:read", principal) && !member
+                : !target.participantIds.includes(principal.id)) {
+                return yield* new PermissionDenied({
+                    message: "This conversation is not readable by the caller.",
+                });
+            }
+            if (!conversations) {
+                return yield* new ActionRejected({
+                    message: "The conversation archive is not configured.",
+                });
+            }
+            return yield* conversations({
+                principal,
+                identityToken,
+                search: {
+                    provider: target.provider,
+                    chatId: target.external_id,
+                    ...(input.before === undefined ? {} : { before: input.before }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                },
+                memberGroups: member ? [groupConversation(target)] : [],
+            });
+        }),
+    };
+}

package/dist/service/chat/resolve.d.ts

@@ -0,0 +1,34 @@
+import { Effect } from "effect";
+import { ActionRejected, PermissionDenied } from "../../errors.js";
+import type { Principal } from "../../runtime.js";
+import type { OntologyBackend } from "../runtime-contract.js";
+import type { ConversationTransport } from "../agent/conversations.js";
+export interface Destination {
+    readonly id: string;
+    readonly title: string;
+    readonly provider: string;
+    readonly external_id: string;
+    readonly kind: "group" | "private";
+    readonly participantIds: ReadonlyArray<string>;
+}
+/** A group chat's conversation in the archive, as attachments name it: `provider:externalId`. */
+export declare const groupConversation: (chat: {
+    readonly provider?: unknown;
+    readonly external_id?: unknown;
+}) => string;
+/** The conversations of the group chats a member is in; none for any other caller. */
+export declare function memberGroupChats(backend: OntologyBackend["Service"], principal: Principal): Effect.Effect<readonly string[], ActionRejected, never>;
+/** Whether a member is in one group chat, which lets them read its history without agent_chat:read. */
+export declare function isChatMember(backend: OntologyBackend["Service"], principal: Principal, chatId: string): Effect.Effect<boolean, ActionRejected, never>;
+/**
+ * A conversation transport that also reads the group chats the member is in, the way a member
+ * reads those chats' attachments: being in a chat is enough, `agent_chat:read` reads them all.
+ */
+export declare function withChatMembership(transport: ConversationTransport, backend: OntologyBackend["Service"]): ConversationTransport;
+export declare function chatResolver(backend: OntologyBackend["Service"], principal: Principal, provider?: string, options?: {
+    /** Also resolve the group chats a member is in without chat read or post permission. */
+    readonly memberGroups?: boolean;
+}): {
+    list: (chat?: string) => Effect.Effect<Destination[], ActionRejected | PermissionDenied, never>;
+    resolve: (chat: string) => Effect.Effect<Destination, ActionRejected | PermissionDenied, never>;
+};

package/dist/service/chat/resolve.js

@@ -0,0 +1,150 @@
+import { Effect } from "effect";
+import { ActionRejected, PermissionDenied } from "../../errors.js";
+import { isAllowed } from "../../permissions.js";
+import { ConversationArchiveUnavailable } from "../agent/conversations.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const denied = () => new PermissionDenied({ message: "Chat discovery requires chat read or post permission." });
+/** Exhaust exact matches, with a fail-closed scan budget so a later page cannot hide ambiguity. */
+function records(backend, entity, query) {
+    return Effect.gen(function* () {
+        const rows = [];
+        let after;
+        for (let page = 0; page < 10; page++) {
+            const found = yield* backend
+                .find({
+                entity,
+                query: { ...query, limit: 200, ...(after === undefined ? {} : { after }) },
+            })
+                .pipe(Effect.mapError((cause) => new ActionRejected({ message: "The chat directory could not be read.", cause })));
+            rows.push(...found.items);
+            if (found.nextCursor === null) {
+                return rows;
+            }
+            after = found.nextCursor;
+        }
+        return yield* new ActionRejected({
+            message: "Too many matching destinations. Use an exact chat ID.",
+        });
+    });
+}
+/** The group chats a member is in: the channel saw them write there, or join. */
+const memberOf = (principal) => ({
+    members: { some: { id: { eq: principal.id } } },
+});
+/** A group chat's conversation in the archive, as attachments name it: `provider:externalId`. */
+export const groupConversation = (chat) => `${String(chat.provider)}:${String(chat.external_id)}`;
+/** The conversations of the group chats a member is in; none for any other caller. */
+export function memberGroupChats(backend, principal) {
+    return Effect.gen(function* () {
+        if (principal.kind !== "member") {
+            return [];
+        }
+        return (yield* records(backend, "agent_chat", { where: memberOf(principal) })).map(groupConversation);
+    });
+}
+/** Whether a member is in one group chat, which lets them read its history without agent_chat:read. */
+export function isChatMember(backend, principal, chatId) {
+    return Effect.gen(function* () {
+        if (principal.kind !== "member") {
+            return false;
+        }
+        return ((yield* records(backend, "agent_chat", {
+            where: { and: [{ id: { eq: chatId } }, memberOf(principal)] },
+        })).length > 0);
+    });
+}
+/**
+ * A conversation transport that also reads the group chats the member is in, the way a member
+ * reads those chats' attachments: being in a chat is enough, `agent_chat:read` reads them all.
+ */
+export function withChatMembership(transport, backend) {
+    return (input) => input.memberGroups !== undefined || input.principal.kind !== "member"
+        ? transport(input)
+        : memberGroupChats(backend, input.principal).pipe(Effect.mapError((cause) => new ConversationArchiveUnavailable({
+            diagnostic: "chat_membership_unavailable",
+            cause,
+        })), Effect.flatMap((memberGroups) => transport({ ...input, memberGroups })));
+}
+export function chatResolver(backend, principal, provider = "telegram", options = {}) {
+    const canGroup = isAllowed("agent_chat:read", principal) || isAllowed("agent_chat:post_message", principal);
+    const memberGroups = options.memberGroups === true && principal.kind === "member";
+    const canDirectory = isAllowed("user:read", principal) || isAllowed("agent_chat:post_message", principal);
+    const destinations = (chat) => Effect.gen(function* () {
+        if (!canGroup && principal.kind !== "member") {
+            return yield* denied();
+        }
+        const privateId = chat?.startsWith(`${provider}:private:`)
+            ? chat.slice(`${provider}:private:`.length)
+            : undefined;
+        const groupId = chat !== undefined && UUID.test(chat);
+        const filters = [
+            ...(chat === undefined ? [] : [groupId ? { id: { eq: chat } } : { title: { eq: chat } }]),
+            ...(canGroup ? [] : [memberOf(principal)]),
+        ];
+        const groups = (!canGroup && !memberGroups) || privateId !== undefined
+            ? []
+            : yield* records(backend, "agent_chat", filters.length === 0
+                ? {}
+                : { where: filters.length === 1 ? filters[0] : { and: filters } });
+        const result = groups
+            .filter((row) => chat === undefined || row.id === chat || row.title === chat)
+            .map((row) => ({
+            id: String(row.id),
+            title: String(row.title),
+            provider: String(row.provider),
+            external_id: String(row.external_id),
+            kind: "group",
+            participantIds: [],
+        }));
+        if (groupId || backend.agents === undefined) {
+            return result;
+        }
+        const members = privateId !== undefined
+            ? (UUID.test(privateId) && (canDirectory || privateId === principal.id)
+                ? [yield* backend.agents.member(privateId)]
+                : []).filter((member) => member !== undefined)
+            : canDirectory
+                ? (yield* records(backend, "user", {
+                    where: {
+                        kind: { eq: "member" },
+                        active: { eq: true },
+                        ...(chat === undefined ? {} : { name: { eq: chat } }),
+                    },
+                })).map((row) => ({ name: String(row.name), principal: { id: String(row.id) } }))
+                : [yield* backend.agents.member(principal.id)].filter((member) => member !== undefined);
+        for (const candidate of members) {
+            const member = yield* backend.agents.member(candidate.principal.id);
+            if (member === undefined ||
+                (chat !== undefined && privateId === undefined && member.name !== chat)) {
+                continue;
+            }
+            const identities = yield* backend.agents.listIdentities(member.principal.id);
+            const identity = identities.find((item) => item.provider === provider && item.revokedAt === null);
+            if (identity !== undefined) {
+                result.push({
+                    id: `${provider}:private:${member.principal.id}`,
+                    title: member.name,
+                    provider,
+                    external_id: identity.externalId,
+                    kind: "private",
+                    participantIds: [member.principal.id],
+                });
+            }
+        }
+        return result;
+    });
+    return {
+        list: destinations,
+        resolve: (chat) => destinations(chat).pipe(Effect.flatMap((items) => {
+            if (items.length === 1) {
+                return Effect.succeed(items[0]);
+            }
+            return Effect.fail(new ActionRejected({
+                message: items.length === 0
+                    ? "No eligible chat matches that ID or exact title."
+                    : "Ambiguous chat. Choose an exact ID: " +
+                        JSON.stringify(items.map(({ id, title, provider }) => ({ id, title, provider }))),
+            }));
+        })),
+    };
+}

package/dist/service/chat/routes.d.ts

@@ -0,0 +1,23 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type TokenVerifier, type SessionExchange } from "../authentication.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+import { RequestId } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import type { BuiltApi } from "../api.js";
+import type { AfterCommitHook } from "../config.js";
+import type { ConnectionTransportFactory } from "../connections.js";
+import type { ReplicationKick } from "../replication.js";
+import { type ConversationTransport } from "../agent/conversations.js";
+import type { ChatDeliveryFactory } from "./delivery.js";
+export declare function chatRoutes(options: {
+    readonly built: BuiltApi;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
+    readonly chatDelivery: ChatDeliveryFactory;
+    readonly conversations?: ConversationTransport;
+    readonly verifyToken: TokenVerifier;
+    readonly verifyRuntime?: RuntimeTokenVerifier;
+    readonly exchangeSession?: SessionExchange;
+}): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

package/dist/service/chat/routes.js

@@ -0,0 +1,75 @@
+import { Cause, Effect, Layer, Schema } from "effect";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { ActionRejected } from "../../errors.js";
+import { withPrincipal, CurrentPrincipal, } from "../authentication.js";
+import { runtimeCredential } from "../runtime-identity.js";
+import { RequestId, failureResponse } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { identityToken, makeOperations } from "../operations.js";
+import { ConversationSearch } from "../agent/conversations.js";
+import { chatReads } from "./reads.js";
+import { withChatMembership } from "./resolve.js";
+import { ChatList, ChatHistory } from "./schemas.js";
+export function chatRoutes(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const conversations = options.conversations && withChatMembership(options.conversations, backend);
+        const reads = chatReads(backend, conversations, options.built.plan.ontology.config.chat?.attribution);
+        const operations = makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate, options.chatDelivery);
+        const planned = options.built.plan.entities.find((entity) => entity.name === "agent_chat");
+        const action = planned.actions.find((candidate) => candidate.name === "post_message");
+        for (const method of ["list", "history", "search", "actions/post_message"]) {
+            yield* router.add("POST", `/api/ontology/chat/${method}`, (request) => Effect.gen(function* () {
+                const bearer = yield* HttpApiBuilder.securityDecode(HttpApiSecurity.bearer).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, request));
+                const runtime = runtimeCredential(options.verifyRuntime, request);
+                const run = Effect.gen(function* () {
+                    const body = yield* request.json.pipe(Effect.mapError(() => new ActionRejected({ message: "Invalid chat request JSON." })));
+                    const decode = (schema) => Schema.decodeUnknownEffect(schema)(body, { onExcessProperty: "error" }).pipe(Effect.mapError(() => new ActionRejected({ message: "Invalid chat request." })));
+                    let result;
+                    switch (method) {
+                        case "list":
+                            result = yield* reads.list(yield* decode(ChatList));
+                            break;
+                        case "history":
+                            result = yield* reads.history(yield* decode(ChatHistory), identityToken(request));
+                            break;
+                        case "search": {
+                            if (!conversations) {
+                                return yield* new ActionRejected({
+                                    message: "The conversation archive is not configured.",
+                                });
+                            }
+                            result = yield* conversations({
+                                search: yield* decode(ConversationSearch),
+                                principal: yield* CurrentPrincipal,
+                                identityToken: identityToken(request),
+                            });
+                            break;
+                        }
+                        case "actions/post_message": {
+                            const payload = yield* decode(Schema.Struct({
+                                input: Schema.Unknown,
+                                options: Schema.optionalKey(Schema.Struct({ validate_only: Schema.optionalKey(Schema.Boolean) })),
+                            }));
+                            result = yield* operations.runAction(planned, action, {
+                                input: payload.input,
+                                validateOnly: payload.options?.validate_only === true,
+                                identityToken: identityToken(request),
+                            });
+                            break;
+                        }
+                    }
+                    return HttpServerResponse.jsonUnsafe(result);
+                }).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+                    ? Effect.failCause(cause)
+                    : Effect.flatMap(RequestId, (requestId) => failureResponse(cause, requestId))));
+                return yield* withPrincipal(bearer, options.verifyToken, backend, run, {
+                    session: { request, exchange: options.exchangeSession },
+                    ...(runtime === undefined ? {} : { runtime }),
+                });
+            }));
+        }
+    }));
+}

package/dist/service/chat/schemas.d.ts

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+export declare const ChatPostWire: Schema.encodeKeys<Schema.Struct<{
+    readonly chat: Schema.String;
+    readonly text: Schema.String;
+    readonly replyTo: Schema.optionalKey<Schema.String>;
+    readonly idempotencyKey: Schema.String;
+}>, {
+    readonly replyTo: "reply_to";
+    readonly idempotencyKey: "idempotency_key";
+}>;
+export declare const RuntimeChatPostWire: Schema.Struct<{
+    readonly chat: Schema.String;
+    readonly text: Schema.String;
+    readonly reply_to: Schema.optionalKey<Schema.String>;
+}>;
+export declare const ChatList: Schema.Struct<{
+    readonly chat: Schema.optionalKey<Schema.String>;
+    readonly query: Schema.optionalKey<Schema.String>;
+    readonly after: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export declare const ChatHistory: Schema.Struct<{
+    readonly chat: Schema.String;
+    readonly before: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+}>;
+export declare const ChatDestination: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly title: Schema.String;
+    readonly provider: Schema.String;
+    readonly external_id: Schema.String;
+    readonly attribution: Schema.NullOr<Schema.String>;
+}>;
+export declare const ChatListResult: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly provider: Schema.String;
+        readonly external_id: Schema.String;
+        readonly attribution: Schema.NullOr<Schema.String>;
+    }>>;
+    readonly next_cursor: Schema.NullOr<Schema.String>;
+}>;

package/dist/service/chat/schemas.js

@@ -0,0 +1,31 @@
+import { Schema } from "effect";
+import { ChatPostInput } from "../../chat.js";
+const Id = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(512));
+export const ChatPostWire = ChatPostInput.pipe(Schema.encodeKeys({ replyTo: "reply_to", idempotencyKey: "idempotency_key" }));
+export const RuntimeChatPostWire = Schema.Struct({
+    chat: ChatPostInput.fields.chat,
+    text: ChatPostInput.fields.text,
+    reply_to: Schema.optionalKey(Id),
+});
+export const ChatList = Schema.Struct({
+    chat: Schema.optionalKey(Id),
+    query: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(512))),
+    after: Schema.optionalKey(Id),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
+});
+export const ChatHistory = Schema.Struct({
+    chat: Id,
+    before: Schema.optionalKey(Id),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
+});
+export const ChatDestination = Schema.Struct({
+    id: Id,
+    title: Schema.String,
+    provider: Schema.String,
+    external_id: Id,
+    attribution: Schema.NullOr(Schema.String),
+});
+export const ChatListResult = Schema.Struct({
+    items: Schema.Array(ChatDestination),
+    next_cursor: Schema.NullOr(Id),
+});