@segmentstream-cloud/ontology 0.18.2 → 0.20.0

package/dist/action.d.ts

@@ -18,13 +18,15 @@ 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, as MCP tool annotations tell agents. Clients such as Claude ask the user
- * before they run a destructive tool. Without hints an action is taken as destructive and not
- * idempotent.
+ * How an action behaves. Agents confirm destructive or irreversible actions before preparation.
+ * Custom actions without safety labels require confirmation for backwards compatibility.
+ * Idempotence does not decide whether confirmation is needed.
  */
 export interface ActionHints {
-    /** Whether the action may overwrite or remove what someone decided. Default true. */
+    /** Whether the action destroys records or established decisions. Unlabelled actions default true. */
     readonly destructive?: boolean;
+    /** Whether the effect cannot be fully undone, such as sending a notification. Default false. */
+    readonly irreversible?: boolean;
     /** Whether running it again with the same input changes nothing more. Default false. */
     readonly idempotent?: boolean;
 }
@@ -79,7 +81,8 @@ interface ActionOptions<Input extends Schema.Top> {
     readonly permission?: string;
     /**
      * How the action behaves, for the agents that run it over MCP. Set `destructive: false` for an
-     * action that only adds or that history makes easy to reverse, and `idempotent: true` for one
+     * routine reversible action, `irreversible: true` for an effect without a complete undo, and
+     * `idempotent: true` for one
      * that a repeated call leaves as it was.
      */
     readonly hints?: ActionHints;

package/dist/analyze.js

@@ -641,8 +641,8 @@ function resolveActions(candidate, scope) {
     }
     return actions;
 }
-const HINT_NAMES = ["destructive", "idempotent"];
-/** The action's `hints`: an object of booleans, `destructive` and `idempotent`. */
+const HINT_NAMES = ["destructive", "irreversible", "idempotent"];
+/** The action's `hints`: an object of booleans, `destructive`, `irreversible` and `idempotent`. */
 function resolveHints(path, action, report) {
     const declared = action.hints;
     if (declared === undefined) {

package/dist/manifest.d.ts

@@ -108,10 +108,11 @@ export declare const ActionManifest: Schema.Struct<{
     readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
     /**
      * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-     * declares hints; absent reads as destructive and not idempotent.
+     * declares hints; absent safety labels require agent confirmation for compatibility.
      */
     readonly hints: Schema.optionalKey<Schema.Struct<{
         readonly destructive: Schema.optionalKey<Schema.Boolean>;
+        readonly irreversible: Schema.optionalKey<Schema.Boolean>;
         readonly idempotent: Schema.optionalKey<Schema.Boolean>;
     }>>;
 }>;
@@ -244,10 +245,11 @@ export declare const EntityManifest: Schema.Struct<{
         readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
         /**
          * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-         * declares hints; absent reads as destructive and not idempotent.
+         * declares hints; absent safety labels require agent confirmation for compatibility.
          */
         readonly hints: Schema.optionalKey<Schema.Struct<{
             readonly destructive: Schema.optionalKey<Schema.Boolean>;
+            readonly irreversible: Schema.optionalKey<Schema.Boolean>;
             readonly idempotent: Schema.optionalKey<Schema.Boolean>;
         }>>;
     }>>;
@@ -391,10 +393,11 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             /**
              * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-             * declares hints; absent reads as destructive and not idempotent.
+             * declares hints; absent safety labels require agent confirmation for compatibility.
              */
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -541,10 +544,11 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             /**
              * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-             * declares hints; absent reads as destructive and not idempotent.
+             * declares hints; absent safety labels require agent confirmation for compatibility.
              */
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -690,10 +694,11 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             /**
              * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-             * declares hints; absent reads as destructive and not idempotent.
+             * declares hints; absent safety labels require agent confirmation for compatibility.
              */
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -789,6 +794,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly connections?: readonly string[] | undefined;
             readonly hints?: {
                 readonly destructive?: boolean | undefined;
+                readonly irreversible?: boolean | undefined;
                 readonly idempotent?: boolean | undefined;
             } | undefined;
         }[];
@@ -894,6 +900,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly connections?: readonly string[] | undefined;
             readonly hints?: {
                 readonly destructive?: boolean | undefined;
+                readonly irreversible?: boolean | undefined;
                 readonly idempotent?: boolean | undefined;
             } | undefined;
         }[];

package/dist/manifest.js

@@ -104,10 +104,11 @@ export const ActionManifest = Schema.Struct({
     connections: Schema.optionalKey(Schema.Array(Schema.String)),
     /**
      * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-     * declares hints; absent reads as destructive and not idempotent.
+     * declares hints; absent safety labels require agent confirmation for compatibility.
      */
     hints: Schema.optionalKey(Schema.Struct({
         destructive: Schema.optionalKey(Schema.Boolean),
+        irreversible: Schema.optionalKey(Schema.Boolean),
         idempotent: Schema.optionalKey(Schema.Boolean),
     })),
 });

package/dist/migrate/model.d.ts

@@ -128,6 +128,7 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly hints: Schema.optionalKey<Schema.Struct<{
                     readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                    readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                     readonly idempotent: Schema.optionalKey<Schema.Boolean>;
                 }>>;
             }>>;
@@ -240,6 +241,7 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly hints: Schema.optionalKey<Schema.Struct<{
                     readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                    readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                     readonly idempotent: Schema.optionalKey<Schema.Boolean>;
                 }>>;
             }>>;

package/dist/service/agent/conversation-routes.d.ts

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

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

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

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

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

package/dist/service/agent/conversations.js

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

package/dist/service/errors.js

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

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

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

package/dist/service/mcp/server.js

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

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

@@ -6,6 +6,8 @@ import type { PlannedAction, PlannedEntity } from "../plan.js";
 export interface McpToolAnnotations {
     readonly readOnlyHint: boolean;
     readonly destructiveHint?: boolean;
+    /** Ontology extension: whether the action has an effect without a complete undo. */
+    readonly irreversibleHint?: boolean;
     readonly idempotentHint?: boolean;
     /** Whether the tool reaches beyond the ontology: true for actions that call connections. */
     readonly openWorldHint: boolean;
@@ -24,6 +26,8 @@ export type McpToolTarget = {
     readonly kind: "me";
 } | {
     readonly kind: "aggregate";
+} | {
+    readonly kind: "conversation-search";
 };
 /** A tool of the ontology's MCP server, derived from the same plan as the HTTP routes. */
 export interface McpTool {
@@ -56,7 +60,7 @@ export declare const ACTION_OPTIONS_ARGUMENT = "_options";
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
  * `check` already refuses.
  */
-export declare function mcpTools(built: BuiltApi): ReadonlyArray<McpTool>;
+export declare function mcpTools(built: BuiltApi, conversations?: boolean): ReadonlyArray<McpTool>;
 /**
  * The tools a caller may see: those whose every permission the caller's roles grant, each with the
  * caller's input schema.

package/dist/service/mcp/tools.js

@@ -65,22 +65,28 @@ function historyInput(label) {
 const READ = { readOnlyHint: true, openWorldHint: false };
 /** The hints of generated actions, which only their name tells apart. */
 const GENERATED_HINTS = {
-    create: { destructive: false, idempotent: false },
-    update: { destructive: true, idempotent: true },
-    delete: { destructive: true, idempotent: true },
-    link: { destructive: false, idempotent: true },
-    unlink: { destructive: true, idempotent: true },
+    create: { destructive: false, irreversible: false, idempotent: false },
+    update: { destructive: false, irreversible: false, idempotent: true },
+    delete: { destructive: true, irreversible: false, idempotent: true },
+    link: { destructive: false, irreversible: false, idempotent: true },
+    unlink: { destructive: false, irreversible: false, idempotent: true },
 };
 /** MCP's defaults for a tool that writes: it may destroy, and repeating it may change more. */
-const AUTHORED_DEFAULT = { destructive: true, idempotent: false };
+const AUTHORED_DEFAULT = {
+    destructive: true,
+    irreversible: false,
+    idempotent: false,
+};
 function hintsOf(planned, { name, generated }) {
     if (generated) {
         return name.startsWith(GENERATED_UPSERT_PREFIX)
-            ? { destructive: true, idempotent: true }
+            ? { destructive: false, irreversible: false, idempotent: true }
             : (GENERATED_HINTS[name] ?? AUTHORED_DEFAULT);
     }
     const declared = planned.resolved.actions.find((candidate) => candidate.name === name)?.hints;
-    return { ...AUTHORED_DEFAULT, ...declared };
+    // A safety label classifies the action; idempotence alone does not opt out of confirmation.
+    const classified = declared?.destructive !== undefined || declared?.irreversible !== undefined;
+    return { ...AUTHORED_DEFAULT, ...(classified ? { destructive: false } : {}), ...declared };
 }
 /** How an agent reaches the records a relationship leads to, with the tools it has. */
 function relatedHint(planned, traversal) {
@@ -208,6 +214,7 @@ function actionTool(planned, plannedAction) {
         annotations: {
             readOnlyHint: false,
             destructiveHint: hints.destructive,
+            irreversibleHint: hints.irreversible,
             idempotentHint: hints.idempotent,
             openWorldHint: action.connections.length > 0,
         },
@@ -402,7 +409,7 @@ function aggregateTool(manifest) {
  * as they have no record routes. Throws {@link InvalidOntology} when two tools share a name, which
  * `check` already refuses.
  */
-export function mcpTools(built) {
+export function mcpTools(built, conversations = false) {
     const { manifest } = built.plan.ontology;
     const tools = [
         ...GLOBAL_TOOLS,
@@ -416,6 +423,50 @@ export function mcpTools(built) {
         tools.push(...readTools(planned, schemas, built));
         tools.push(...planned.actions.map((action) => actionTool(planned, action)));
     }
+    if (conversations) {
+        const index = tools.findIndex((tool) => tool.name === "agent_chat_history");
+        if (index >= 0) {
+            const tool = tools[index];
+            const rest = { ...tool };
+            delete rest.outputSchema;
+            tools[index] = {
+                ...rest,
+                description: tool.description +
+                    " Also returns conversation.events: message texts, reply/silent decisions and reasons, " +
+                    "tool calls/results and attachment references. Conversation pagination uses conversation_before " +
+                    "separately from the audit after cursor.",
+                inputSchema: {
+                    ...tool.inputSchema,
+                    properties: {
+                        ...tool.inputSchema.properties,
+                        conversation_before: {
+                            type: "string",
+                            description: "conversation.nextCursor from the previous page.",
+                        },
+                    },
+                },
+            };
+        }
+        tools.push({
+            name: "agent_chat_search",
+            title: "Search stored conversations",
+            description: "Search retained conversation messages, decisions and tool calls by text, provider chat ID, " +
+                "sender ID, topic and date range. Returns only groups you may read (agent_chat:read) and DMs " +
+                "in which you participated. Dates are ISO 8601; before is the nextCursor of the previous page. " +
+                "Workspace administrators can read all DMs through the platform API.",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    ...Object.fromEntries(["q", "provider", "chatId", "threadId", "senderId", "from", "to", "before"].map((key) => [key, { type: "string", maxLength: 1000 }])),
+                    limit: { type: "integer", minimum: 1, maximum: 200 },
+                },
+            },
+            annotations: READ,
+            permissions: [],
+            target: { kind: "conversation-search" },
+        });
+    }
     const seen = new Set();
     const duplicates = tools.filter(({ name }) => seen.size === seen.add(name).size);
     if (duplicates.length > 0) {

package/dist/service/schemas.d.ts

@@ -235,6 +235,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -353,6 +354,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;

package/dist/service/service.js

@@ -5,6 +5,8 @@ import { storageMaintenanceAuthenticationLayer } from "../storage/maintenance-au
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
 import { attachmentsLayer } from "./agent/attachments.js";
+import { platformConversations } from "./agent/conversations.js";
+import { conversationRoutes } from "./agent/conversation-routes.js";
 import { deployedAgentChannel } from "./agent/channel.js";
 import { agentLayer } from "./agent/server.js";
 import { makeAggregates } from "./aggregate.js";
@@ -95,6 +97,7 @@ export function createOntologyService(ontology, config) {
     const agentChannel = config.runtimeIdentity === undefined || config.agentUrl === undefined
         ? undefined
         : deployedAgentChannel(config.agentUrl);
+    const conversations = config.runtimeIdentity === undefined ? undefined : platformConversations(config);
     const aggregates = makeAggregates({
         manifest: ontology.manifest,
         transport: platformAggregates({ ...config, manifestHash: ontology.manifest.hash }),
@@ -115,6 +118,7 @@ export function createOntologyService(ontology, config) {
             replicate,
             aggregates,
             agentChannel,
+            conversations,
         }), oauthLayer({ verifyToken }));
     const agent = agentLayer({ verifyToken, verifyRuntime, exchangeSession });
     const attachments = attachmentsLayer({
@@ -126,7 +130,14 @@ export function createOntologyService(ontology, config) {
         verifyToken,
         verifyRuntime,
     });
-    const application = Layer.mergeAll(routes, mcp, agent, attachments, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
+    const application = Layer.mergeAll(routes, mcp, agent, attachments, conversations === undefined
+        ? Layer.empty
+        : conversationRoutes({
+            transport: conversations,
+            verifyToken,
+            verifyRuntime,
+            exchangeSession,
+        }), DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;
     return {

package/package.json

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