@segmentstream-cloud/ontology 0.14.0 → 0.16.0

package/dist/service/mcp/tools.js

@@ -7,6 +7,7 @@ import { isAllowed, permissionOf, READ_VERB } from "../../permissions.js";
 import { queryJsonSchema } from "../../query.js";
 import { measuresFor, RECORDS_OR_AGGREGATES } from "../../render.js";
 import { actionInputJsonSchema } from "../../runtime/generated-actions.js";
+import { uploadFields } from "../../storage/attachments.js";
 import { actionDescription, requires } from "../descriptions.js";
 import { AGGREGATE_FILTER_OPERATORS, AGGREGATE_GRANULARITIES, AGGREGATE_LIMITS, HistoryPage, Me, } from "../schemas.js";
 const DEFS = "#/$defs/";
@@ -160,6 +161,37 @@ function readTools(planned, schemas, built) {
         },
     ];
 }
+/**
+ * The argument an action that consumes an upload takes beside its input: the idempotency key the
+ * runtime requires of it, and the create intent the upload was begun with. The service removes it
+ * before the input is validated.
+ */
+export const ACTION_OPTIONS_ARGUMENT = "_options";
+const ACTION_OPTIONS_SCHEMA = {
+    type: "object",
+    description: "Options of an action that stores an uploaded file: idempotency_key, required with an upload, " +
+        "and create_intent, the one the upload was begun with when it creates a record.",
+    properties: {
+        idempotency_key: { type: "string", minLength: 1, maxLength: 128 },
+        create_intent: { type: "string", format: "uuid" },
+    },
+    additionalProperties: false,
+};
+/** The input schema of an action tool; one that consumes an upload also takes its options. */
+function actionToolInput(action) {
+    const schema = rootObject(actionInputJsonSchema(action.input));
+    const properties = schema.properties;
+    if (uploadFields(action.input).length === 0 ||
+        schema.type !== "object" ||
+        properties === undefined ||
+        ACTION_OPTIONS_ARGUMENT in properties) {
+        return schema;
+    }
+    return {
+        ...schema,
+        properties: { ...properties, [ACTION_OPTIONS_ARGUMENT]: ACTION_OPTIONS_SCHEMA },
+    };
+}
 function actionTool(planned, plannedAction) {
     const { name, action, permissions } = plannedAction;
     const hints = hintsOf(planned, plannedAction);
@@ -167,7 +199,7 @@ function actionTool(planned, plannedAction) {
         name: mcpToolName(planned.name, name),
         title: `${planned.resolved.entity.definition.label}: ${humanize(name).toLowerCase()}`,
         description: actionDescription(plannedAction),
-        inputSchema: rootObject(actionInputJsonSchema(action.input)),
+        inputSchema: actionToolInput(action),
         annotations: {
             readOnlyHint: false,
             destructiveHint: hints.destructive,

package/dist/service/operations.d.ts

@@ -5,6 +5,7 @@ import type { Query, QueryResult } from "../query.js";
 import { CurrentPrincipal } from "./authentication.js";
 import type { AfterCommitHook } from "./config.js";
 import type { ReplicationKick } from "./replication.js";
+import type { AgentChannelFactory } from "./agent/channel.js";
 import { type ConnectionTransportFactory } from "./connections.js";
 import { InvalidActionInput, RequestId } from "./errors.js";
 import type { ApiPlan, PlannedAction, PlannedEntity, Traversal } from "./plan.js";
@@ -59,8 +60,11 @@ export interface Caller {
     readonly permissions: ReadonlyArray<string>;
 }
 type Backend = OntologyBackend["Service"];
-/** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick): {
+/**
+ * The operations of a planned ontology, bound to its backend, after-commit hooks, connections and,
+ * on deployments with one, the workspace's agent.
+ */
+export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, agentChannel?: AgentChannelFactory): {
     /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
     find: (planned: PlannedEntity, query: Query) => Effect.Effect<QueryResult<Readonly<Record<string, unknown>>>, PermissionDenied | import("../index.js").InvalidQuery, CurrentPrincipal>;
     /** One record. Requires `read` on the entity. */

package/dist/service/operations.js

@@ -6,6 +6,7 @@ import { PermissionDenied } from "../errors.js";
 import { toCamelCase } from "../names.js";
 import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
 import { CurrentPrincipal } from "./authentication.js";
+import { AgentChannel } from "../agent-chat.js";
 import { OIDC_TOKEN_HEADER } from "./connections.js";
 import { InvalidActionInput, RequestId } from "./errors.js";
 /**
@@ -145,12 +146,12 @@ function traverseOf(backend, targets, planned, traversal, id, query) {
         return page(yield* backend.find({ entity: traversal.target, query: { ...query, where } }));
     });
 }
-function runActionOf(backend, ontology, hooks, connections, replicate) {
+function runActionOf(backend, ontology, hooks, connections, replicate, agentChannel) {
     return (planned, { name, generated }, call) => Effect.gen(function* () {
         const principal = yield* CurrentPrincipal;
         const requestId = yield* RequestId;
         const hook = hooks.get(`${planned.name}.${name}`);
-        const outcome = yield* backend.runAction({
+        const run = backend.runAction({
             entity: planned.name,
             action: name,
             input: call.input,
@@ -175,6 +176,10 @@ function runActionOf(backend, ontology, hooks, connections, replicate) {
                 }
                 : {}),
         });
+        // Built-in actions reach the workspace's agent through it, when the deployment has one.
+        const outcome = yield* agentChannel === undefined
+            ? run
+            : run.pipe(Effect.provideService(AgentChannel, agentChannel({ identityToken: call.identityToken, store: backend.agents })));
         const { issues } = outcome.validation;
         if (!outcome.validation.ok && !call.validateOnly) {
             return yield* new InvalidActionInput({ issues });
@@ -208,8 +213,11 @@ function callerOf(backend) {
         };
     });
 }
-/** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export function makeOperations(backend, plan, hooks, connections, replicate) {
+/**
+ * The operations of a planned ontology, bound to its backend, after-commit hooks, connections and,
+ * on deployments with one, the workspace's agent.
+ */
+export function makeOperations(backend, plan, hooks, connections, replicate, agentChannel) {
     const targets = relationshipTargets(plan);
     return {
         /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
@@ -221,7 +229,7 @@ export function makeOperations(backend, plan, hooks, connections, replicate) {
         /** The records a relationship reaches from one record, as a page of the target entity. */
         traverse: (planned, traversal, id, query) => traverseOf(backend, targets, planned, traversal, id, query),
         /** Runs an action as the caller, with the action's after-commit hook and connections. */
-        runAction: runActionOf(backend, plan.ontology, hooks, connections, replicate),
+        runAction: runActionOf(backend, plan.ontology, hooks, connections, replicate, agentChannel),
         /** The caller's user, roles and permissions. It needs no permission. */
         caller: callerOf(backend),
     };

package/dist/service/runtime-contract.d.ts

@@ -1,4 +1,5 @@
 import { Context, Schema, type Effect, type Layer, type Redacted } from "effect";
+import type { AttachmentRuntime } from "../storage/attachments.js";
 import type { BlobRuntime } from "../storage/sessions.js";
 import type { BlobStorageBinding } from "../storage/provider.js";
 import type { AnyAction } from "../action.js";
@@ -180,6 +181,13 @@ export interface AgentMember {
     readonly name: string;
     readonly principal: Principal;
 }
+/** A group chat the agent saw, as `POST /api/ontology/agent/chats/seen` answers. */
+export interface SeenChat {
+    readonly id: string;
+    readonly title: string;
+    readonly purpose: string | null;
+    readonly whenToUse: string | null;
+}
 /**
  * Where the app's agent keeps pairing codes and the identities they create: the runtime's agent
  * tables in the workspace database. Codes are stored only as SHA-256 hashes. Expiry is checked
@@ -218,9 +226,30 @@ export interface AgentStore {
     readonly member: (userId: string) => Effect.Effect<AgentMember | undefined>;
     /** The member a runtime caller acts for: active, and with a live identity. */
     readonly actingMember: (userId: string) => Effect.Effect<Principal | undefined>;
+    /**
+     * Records a message the agent saw in a group chat: creates the `agent_chat` or keeps its title
+     * current, records when the chat last had a message (at most every 15 minutes, so that history
+     * keeps it without a row per message), links the writer to its members when they are an active
+     * member, and unlinks `leftMemberId`, a member who left, when linked. With `agentLeft`, the agent
+     * itself left the chat: every member is unlinked, and the chat stays. With `migratedFrom`, the
+     * chat had that id before it became a supergroup: its record moves to `externalId`, or, when both
+     * ids have one, the new record takes the old one's members, and its purpose and when to use where
+     * it has none. Concurrent calls for one chat leave one record.
+     */
+    readonly seeChat: (input: {
+        readonly provider: string;
+        readonly externalId: string;
+        readonly title: string;
+        readonly memberId?: string;
+        readonly leftMemberId?: string;
+        readonly agentLeft?: true;
+        readonly migratedFrom?: string;
+    }) => Effect.Effect<SeenChat>;
 }
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
     readonly blobs?: BlobRuntime;
+    /** The agent's temporary attachments, on deployments with file storage. */
+    readonly attachments?: AttachmentRuntime;
     readonly maintainBlobs?: Effect.Effect<{
         readonly removed: number;
     }, unknown>;

package/dist/service/service.js

@@ -4,6 +4,8 @@ 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 { attachmentsLayer } from "./agent/attachments.js";
+import { deployedAgentChannel } from "./agent/channel.js";
 import { agentLayer } from "./agent/server.js";
 import { makeAggregates } from "./aggregate.js";
 import { platformAggregates } from "./aggregate-platform.js";
@@ -89,11 +91,15 @@ export function createOntologyService(ontology, config) {
             ? deployedConnections(config)
             : localConnections(config.localConnections));
     const replicate = deployedReplication(config);
+    // The agent's runtime identity is configured only on deployments that have an agent.
+    const agentChannel = config.runtimeIdentity === undefined || config.agentUrl === undefined
+        ? undefined
+        : deployedAgentChannel(config.agentUrl);
     const aggregates = makeAggregates({
         manifest: ontology.manifest,
         transport: platformAggregates({ ...config, manifestHash: ontology.manifest.hash }),
     });
-    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections, replicate, aggregates)), Layer.provide([
+    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections, replicate, aggregates, agentChannel)), Layer.provide([
         authenticationLayer(verifyToken, exchangeSession, verifyRuntime),
         ErrorResponsesLive,
         storageMaintenanceAuthenticationLayer(config.storageMaintenanceKey),
@@ -108,9 +114,19 @@ export function createOntologyService(ontology, config) {
             verifyRuntime,
             replicate,
             aggregates,
+            agentChannel,
         }), oauthLayer({ verifyToken }));
     const agent = agentLayer({ verifyToken, verifyRuntime, exchangeSession });
-    const application = Layer.mergeAll(routes, mcp, agent, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
+    const attachments = attachmentsLayer({
+        plan: built.plan,
+        hooks,
+        connections,
+        replicate,
+        agentChannel,
+        verifyToken,
+        verifyRuntime,
+    });
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;
     return {

package/dist/storage/attachments.d.ts

@@ -0,0 +1,117 @@
+import { Effect, Schema } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { ActionRejected, Conflict, NotFound, type PermissionDenied } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import type { Principal } from "../runtime.js";
+import type { BlobProvider, TransferGrant } from "./provider.js";
+/**
+ * The agent's temporary attachments: a file a member sends the app's agent is stored once, as a
+ * `_blobs` revision in the ontology's private file storage, and belongs to that member, the chat it
+ * arrived in and the agent session that first reads it. Nothing about it is an ontology record. It
+ * expires 24 hours after receipt; within that time the member's agent may read it, discard it, or
+ * promote it into a record through an action, which adopts the same stored object without copying
+ * it. Every operation re-derives the owner, chat and session from the caller, never from input.
+ */
+/** The largest file the agent takes: what Telegram's Bot API lets a bot download. */
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** How long an attachment stays readable after it arrives; reads never extend it. */
+export declare const ATTACHMENT_TTL_HOURS = 24;
+/** Live attachments one member may hold at once, so a busy chat cannot fill the storage. */
+export declare const MAX_LIVE_ATTACHMENTS = 50;
+export declare const ATTACHMENT_SOURCES: readonly ["telegram"];
+/** Who asks, as the agent's runtime knows it: the member, their chat and the agent session. */
+export interface AttachmentCaller {
+    readonly principal: Principal;
+    /** The chat the attachment arrived in, such as `telegram:12345`. */
+    readonly conversation: string;
+    /**
+     * The agent session the request comes from. The first session that reads an attachment owns it;
+     * other sessions of the same chat, such as one after a reset, never see it.
+     */
+    readonly sessionId?: string;
+}
+export interface ReceiveAttachment {
+    readonly source: (typeof ATTACHMENT_SOURCES)[number];
+    /** Identifies the file at its source, such as the message and attachment index; retries reuse it. */
+    readonly sourceRef: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface AttachmentView {
+    readonly id: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly state: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly promotion: unknown;
+}
+export interface PromotionTarget {
+    /** The entity whose action adopts the file, such as `document`. */
+    readonly entity: string;
+    /** The action, such as `upload` or `create`. */
+    readonly action: string;
+    /** The action's input without the file; the field that takes the upload is filled in. */
+    readonly input: Readonly<Record<string, unknown>>;
+    /** The input field that takes the upload, when the action has more than one. */
+    readonly field?: string;
+    /** The record the action updates, for an action that sets the file on an existing record. */
+    readonly recordId?: string;
+}
+/** Runs the promotion's action as the caller, with the upload's options. */
+export type PromotionRunner = (input: {
+    readonly entity: string;
+    readonly action: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly options: {
+        readonly idempotencyKey: string;
+        readonly createIntent?: string;
+    };
+}) => Effect.Effect<{
+    readonly result: unknown;
+    readonly edits: ReadonlyArray<unknown>;
+}, unknown>;
+/** The fields of an action's input that take an upload, with the property each one writes. */
+export declare function uploadFields(input: Schema.Top): ReadonlyArray<{
+    readonly field: string;
+    readonly entity: string;
+    readonly property: string;
+}>;
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export declare function attachmentRuntime(ontology: Ontology, sql: SqlClient.SqlClient, provider: BlobProvider["Service"]): {
+    receive: (input: ReceiveAttachment, caller: AttachmentCaller) => Effect.Effect<{
+        attachment: AttachmentView;
+        upload?: undefined;
+    } | {
+        attachment: AttachmentView;
+        upload: TransferGrant;
+    }, ActionRejected | PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    complete: (id: string, caller: AttachmentCaller) => Effect.Effect<AttachmentView, ActionRejected | PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    list: (caller: AttachmentCaller) => Effect.Effect<AttachmentView[], PermissionDenied | import("effect/unstable/sql/SqlError").SqlError, never>;
+    read: (id: string, caller: AttachmentCaller) => Effect.Effect<{
+        attachment: AttachmentView;
+        download: TransferGrant;
+    }, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    discard: (id: string, caller: AttachmentCaller) => Effect.Effect<AttachmentView, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    promote: (id: string, target: PromotionTarget, caller: AttachmentCaller, 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;
+/**
+ * Expires attachments past their deadline and removes the bytes of every expired or discarded one
+ * that no record adopted. A revision a promotion ticket still points at is left to the upload
+ * maintenance, once the ticket is canceled. Runs from the storage maintenance schedule, so files
+ * expire while the agent is idle.
+ */
+export declare function maintainAttachments(sql: SqlClient.SqlClient, provider: BlobProvider["Service"], limit?: number): Effect.Effect<{
+    expired: number;
+    removed: number;
+}, import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;