@segmentstream/ontology 0.0.0-stage → 0.92.0

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

@@ -0,0 +1,90 @@
+import { Schema } from "effect";
+import type { Principal } from "../../runtime.js";
+import type { AgentIdentity } from "../runtime-contract.js";
+/** How long a member has to open the connect link, sign in and approve the pairing. */
+export declare const PAIRING_TTL_MS: number;
+/**
+ * The letters and digits a pairing code uses: no 0/O, 1/I/L, so that a code read aloud or typed from
+ * a phone comes out right. 31 symbols, 8 of them: about 40 bits, against ten minutes of guessing by
+ * signed-in members only.
+ */
+export declare const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+export declare const PAIRING_CODE_LENGTH = 8;
+/** A new pairing code, from the operating system's random source without modulo bias. */
+export declare function newPairingCode(): string;
+/**
+ * A code as the member's browser sends it, in the canonical form it was hashed in: upper case,
+ * without the spaces or dashes someone may type between groups. `undefined` when it cannot be one.
+ */
+export declare function canonicalPairingCode(value: string): string | undefined;
+/** A channel's name: `telegram`, `slack`. It is part of a URL path and of every identity. */
+export declare const Provider: Schema.String;
+/** `POST /api/ontology/agent/pairings`: the account an unknown sender writes from. */
+export declare const PairingRequest: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly external_id: Schema.String;
+    readonly display: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>;
+export declare const ResolveIdentityRequest: Schema.Struct<{
+    readonly chat: Schema.Literals<readonly ["private", "group"]>;
+    readonly turn: Schema.Boolean;
+    readonly username: Schema.optionalKey<Schema.String>;
+    readonly notice_version: Schema.optionalKey<Schema.String>;
+    readonly notice_sha256: Schema.optionalKey<Schema.String>;
+    readonly limits: Schema.optionalKey<Schema.Struct<{
+        readonly perSender: Schema.optionalKey<Schema.Struct<{
+            readonly turnsPerMinute: Schema.optionalKey<Schema.Int>;
+            readonly turnsPerDay: Schema.optionalKey<Schema.Int>;
+        }>>;
+        readonly newUsersPerHour: Schema.optionalKey<Schema.Int>;
+        readonly workspaceTurnsPerDay: Schema.optionalKey<Schema.Int>;
+    }>>;
+    readonly provider: Schema.String;
+    readonly external_id: Schema.String;
+    readonly display: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>;
+export declare const IdentityNoticeRequest: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly external_id: Schema.String;
+    readonly sha256: Schema.String;
+    readonly version: Schema.optionalKey<Schema.String>;
+}>;
+export declare const LimitNoticeRequest: Schema.Struct<{
+    readonly notification_id: Schema.String;
+    readonly delivered: Schema.Boolean;
+}>;
+export type PairingRequest = typeof PairingRequest.Type;
+/**
+ * `POST /api/ontology/agent/chats/seen`: a group chat the agent saw a message in, and who wrote, or
+ * the paired member who left it, or the agent itself leaving it, or the group it was before it
+ * became a supergroup.
+ */
+export declare const ChatSeenRequest: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly externalId: Schema.String;
+    readonly title: Schema.String;
+    readonly memberId: Schema.optionalKey<Schema.String>;
+    readonly leftMemberId: Schema.optionalKey<Schema.String>;
+    readonly agentLeft: Schema.optionalKey<Schema.Literal<true>>;
+    readonly migratedFrom: Schema.optionalKey<Schema.String>;
+}>;
+/** An identity on the wire, as the member's connect page and settings show it. */
+export declare function identityForWire(identity: AgentIdentity): {
+    created_at: string;
+    username?: string | undefined;
+    id: string;
+    provider: string;
+    external_id: string;
+    display: string | null;
+};
+/** The member the agent acts for, as `GET …/identities/{provider}/{external_id}` answers. */
+export declare function memberForWire(input: {
+    readonly name: string;
+    readonly principal: Principal;
+}): {
+    user: {
+        id: string;
+        name: string;
+    };
+    roles: readonly string[];
+};

package/dist/service/agent/protocol.js

@@ -0,0 +1,114 @@
+import { randomInt } from "node:crypto";
+import { Schema } from "effect";
+/** How long a member has to open the connect link, sign in and approve the pairing. */
+export const PAIRING_TTL_MS = 10 * 60 * 1000;
+/**
+ * The letters and digits a pairing code uses: no 0/O, 1/I/L, so that a code read aloud or typed from
+ * a phone comes out right. 31 symbols, 8 of them: about 40 bits, against ten minutes of guessing by
+ * signed-in members only.
+ */
+export const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+export const PAIRING_CODE_LENGTH = 8;
+const PAIRING_CODE = new RegExp(`^[${PAIRING_CODE_ALPHABET}]{${PAIRING_CODE_LENGTH}}$`);
+/** A new pairing code, from the operating system's random source without modulo bias. */
+export function newPairingCode() {
+    let code = "";
+    for (let index = 0; index < PAIRING_CODE_LENGTH; index++) {
+        code += PAIRING_CODE_ALPHABET[randomInt(PAIRING_CODE_ALPHABET.length)];
+    }
+    return code;
+}
+/**
+ * A code as the member's browser sends it, in the canonical form it was hashed in: upper case,
+ * without the spaces or dashes someone may type between groups. `undefined` when it cannot be one.
+ */
+export function canonicalPairingCode(value) {
+    const code = value.replace(/[\s-]/g, "").toUpperCase();
+    return PAIRING_CODE.test(code) ? code : undefined;
+}
+const MAX_EXTERNAL_ID_LENGTH = 256;
+const MAX_DISPLAY_LENGTH = 200;
+/** A channel's name: `telegram`, `slack`. It is part of a URL path and of every identity. */
+export const Provider = Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9_-]{0,31}$/)).annotate({
+    description: "The channel, such as telegram: lower case letters, digits, - and _.",
+});
+/** `POST /api/ontology/agent/pairings`: the account an unknown sender writes from. */
+export const PairingRequest = Schema.Struct({
+    provider: Provider,
+    external_id: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_EXTERNAL_ID_LENGTH)).annotate({ description: "The account's id on the channel." }),
+    display: Schema.optionalKey(Schema.NullOr(Schema.String.check(Schema.isMaxLength(MAX_DISPLAY_LENGTH))).annotate({
+        description: "How the channel names the account, shown to the member who approves.",
+    })),
+});
+/** Trusted runtime resolution: channel admission and limits run before expensive processing. */
+const PositiveLimit = Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(1_000_000_000));
+export const ResolveIdentityRequest = Schema.Struct({
+    ...PairingRequest.fields,
+    chat: Schema.Literals(["private", "group"]),
+    turn: Schema.Boolean,
+    username: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(MAX_DISPLAY_LENGTH))),
+    notice_version: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200))),
+    notice_sha256: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/))),
+    limits: Schema.optionalKey(Schema.Struct({
+        perSender: Schema.optionalKey(Schema.Struct({
+            turnsPerMinute: Schema.optionalKey(PositiveLimit),
+            turnsPerDay: Schema.optionalKey(PositiveLimit),
+        })),
+        newUsersPerHour: Schema.optionalKey(PositiveLimit),
+        workspaceTurnsPerDay: Schema.optionalKey(PositiveLimit),
+    })),
+});
+export const IdentityNoticeRequest = Schema.Struct({
+    provider: Provider,
+    external_id: PairingRequest.fields.external_id,
+    sha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+    version: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200))),
+});
+export const LimitNoticeRequest = Schema.Struct({
+    notification_id: Schema.String.check(Schema.isUUID()),
+    delivered: Schema.Boolean,
+});
+/** A chat's id on the channel. */
+const ChatId = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(MAX_EXTERNAL_ID_LENGTH));
+/**
+ * `POST /api/ontology/agent/chats/seen`: a group chat the agent saw a message in, and who wrote, or
+ * the paired member who left it, or the agent itself leaving it, or the group it was before it
+ * became a supergroup.
+ */
+export const ChatSeenRequest = Schema.Struct({
+    provider: Provider,
+    externalId: ChatId.annotate({ description: "The chat's id on the channel." }),
+    title: Schema.String.check(Schema.isMaxLength(MAX_DISPLAY_LENGTH)).annotate({
+        description: "The chat's name on the channel.",
+    }),
+    memberId: Schema.optionalKey(Schema.String.annotate({
+        description: "The user id of the member who wrote, when the sender is paired.",
+    })),
+    leftMemberId: Schema.optionalKey(Schema.String.annotate({
+        description: "The user id of a paired member who left the chat, to unlink from its members.",
+    })),
+    agentLeft: Schema.optionalKey(Schema.Literal(true).annotate({
+        description: "The agent itself left the chat or was removed: every member is unlinked.",
+    })),
+    migratedFrom: Schema.optionalKey(ChatId.annotate({
+        description: "The chat's id before it became a supergroup: its record moves to externalId.",
+    })),
+});
+/** An identity on the wire, as the member's connect page and settings show it. */
+export function identityForWire(identity) {
+    return {
+        id: identity.id,
+        provider: identity.provider,
+        external_id: identity.externalId,
+        display: identity.display,
+        ...(identity.username === undefined ? {} : { username: identity.username }),
+        created_at: identity.createdAt.toISOString(),
+    };
+}
+/** The member the agent acts for, as `GET …/identities/{provider}/{external_id}` answers. */
+export function memberForWire(input) {
+    return {
+        user: { id: input.principal.id, name: input.name },
+        roles: input.principal.roles,
+    };
+}

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

@@ -0,0 +1,28 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type SessionExchange, type TokenVerifier } from "../authentication.js";
+import { RequestId } from "../errors.js";
+import { type RateLimit } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { type RuntimeTokenVerifier } from "../runtime-identity.js";
+/** The agent's endpoints, under the ontology service's path. */
+export declare const AGENT_PATH = "/api/ontology/agent";
+/**
+ * Pairings one client address may start per minute; each one is a row in the database. The agent's
+ * functions share a few egress addresses, so the limit leaves room for a busy channel.
+ */
+export declare const PAIRING_LIMIT: RateLimit;
+export interface AgentServerOptions {
+    readonly verifyToken: TokenVerifier;
+    /** The deployment's runtime tokens; `undefined` while runtime authentication is disabled. */
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+    readonly exchangeSession: SessionExchange | undefined;
+}
+/**
+ * The routes that pair channel accounts with members for the app's own agent, and record the group
+ * chats it sees. Runtime routes take
+ * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
+ * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
+ * Without the agent tables, it serves nothing.
+ */
+export declare function agentLayer(options: AgentServerOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

package/dist/service/agent/server.js

@@ -0,0 +1,374 @@
+import { confirmationCommand } from "./confirmations.js";
+import { randomUUID } from "node:crypto";
+import { Effect, Layer, Redacted, Result, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { schemaIssues } from "../../runtime/validation.js";
+import { BASE_PATH } from "../api.js";
+import { CurrentPrincipal, withPrincipal, } from "../authentication.js";
+import { RequestId, errorBodyForWire, forbidden, notFound, rateLimited, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+import { secretHash } from "../oauth/protocol.js";
+import { clientAddress, fixedWindowLimiter, } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { AGENT_TASK_HEADER, agentTaskSecret, logRuntimeRejection, } from "../runtime-identity.js";
+import { ChatSeenRequest, ResolveIdentityRequest, IdentityNoticeRequest, LimitNoticeRequest, PAIRING_TTL_MS, PairingRequest, canonicalPairingCode, identityForWire, memberForWire, newPairingCode, } from "./protocol.js";
+/** The agent's endpoints, under the ontology service's path. */
+export const AGENT_PATH = `${BASE_PATH}/agent`;
+const PAIRINGS_PATH = `${AGENT_PATH}/pairings`;
+const IDENTITIES_PATH = `${AGENT_PATH}/identities`;
+const CHATS_SEEN_PATH = `${AGENT_PATH}/chats/seen`;
+/**
+ * Pairings one client address may start per minute; each one is a row in the database. The agent's
+ * functions share a few egress addresses, so the limit leaves room for a busy channel.
+ */
+export const PAIRING_LIMIT = { limit: 60, windowMs: 60_000, maxKeys: 10_000 };
+/** A fresh code collides with a live one about never; a few attempts make it never in practice. */
+const CODE_ATTEMPTS = 3;
+const NO_STORE = { "cache-control": "no-store" };
+function json(body, status = 200) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: NO_STORE });
+}
+function jsonBody(request) {
+    return Effect.map(Effect.orDie(request.text), (text) => {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+function invalidBody(requestId, issues) {
+    return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+        error: "invalid_request",
+        detail: "The request body is invalid.",
+        requestId,
+        issues,
+    }), { status: 400 });
+}
+function pairingNotFound(requestId) {
+    return toServerResponse(notFound(requestId, "The pairing code expired or was already used. Send the agent a message for a new link."));
+}
+function routeParam(name) {
+    return Effect.map(HttpRouter.params, (params) => params[name] ?? "");
+}
+/**
+ * `POST /api/ontology/agent/pairings` (runtime): a sender the agent does not know gets a short code
+ * that a signed-in member approves on the app's connect page. Only the code's hash is stored.
+ */
+function createPairing(store, limiter) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const retryAfter = limiter.take(clientAddress(request));
+        if (retryAfter !== undefined) {
+            return toServerResponse(rateLimited(requestId, "Too many pairings; try again in a minute.", retryAfter));
+        }
+        const body = yield* jsonBody(request);
+        const decoded = Schema.decodeUnknownResult(PairingRequest)(body, {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        const { provider, external_id: externalId, display } = decoded.success;
+        const trimmedDisplay = display?.trim() || null;
+        for (let attempt = 0; attempt < CODE_ATTEMPTS; attempt++) {
+            const code = newPairingCode();
+            const expiresAt = new Date(Date.now() + PAIRING_TTL_MS);
+            const saved = yield* store.savePairing({
+                id: randomUUID(),
+                codeHash: secretHash(code),
+                provider,
+                externalId,
+                display: trimmedDisplay,
+                expiresAt,
+            });
+            if (saved) {
+                return json({ code, expires_at: expiresAt.toISOString() }, 201);
+            }
+        }
+        return yield* Effect.die(new Error("No free pairing code after several attempts."));
+    });
+}
+/** `GET /api/ontology/agent/pairings/:code` (member): what the connect page shows. */
+function describePairing(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const pairing = code === undefined ? undefined : yield* store.findPairing(secretHash(code));
+        if (pairing === undefined) {
+            return pairingNotFound(requestId);
+        }
+        return json({
+            provider: pairing.provider,
+            display: pairing.display,
+            expires_at: pairing.expiresAt.toISOString(),
+        });
+    });
+}
+/**
+ * `POST /api/ontology/agent/pairings/:code/approve` (member): pairs the account with the signed-in
+ * member, once. Another member's live account cannot be claimed. A member may replace their own
+ * previous account on the same provider.
+ */
+function approvePairing(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const code = canonicalPairingCode(yield* routeParam("code"));
+        const identity = code === undefined
+            ? undefined
+            : yield* store
+                .approvePairing({
+                codeHash: secretHash(code),
+                userId: member.id,
+                identityId: randomUUID(),
+            })
+                .pipe(Effect.catchTag("IdentityInUse", () => Effect.succeed("identity_in_use")));
+        if (identity === "identity_in_use") {
+            return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+                error: "identity_in_use",
+                detail: "identity_in_use",
+                requestId,
+            }), { status: 409, headers: NO_STORE });
+        }
+        if (identity === undefined) {
+            return pairingNotFound(requestId);
+        }
+        yield* Effect.logInfo("ontology.agent.paired").pipe(Effect.annotateLogs({ identityId: identity.id, provider: identity.provider, requestId }));
+        return json({ identity: identityForWire(identity) });
+    });
+}
+/**
+ * `GET /api/ontology/agent/identities/:provider/:external_id` (runtime): the member an account acts
+ * as, with the roles they hold now. 404 for an account nobody paired; 403 once its identity was
+ * revoked or its member deactivated.
+ */
+function resolveIdentity(store) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const provider = yield* routeParam("provider");
+        const externalId = yield* routeParam("external_id");
+        const identity = yield* store.findIdentity({ provider, externalId });
+        if (identity === undefined) {
+            return toServerResponse(notFound(requestId, "No member paired this account."));
+        }
+        if (identity.revokedAt !== null) {
+            return toServerResponse(forbidden(requestId, "The account's pairing was revoked."));
+        }
+        const member = yield* store.member(identity.userId);
+        if (member === undefined) {
+            return toServerResponse(forbidden(requestId, "The member is inactive."));
+        }
+        return json(memberForWire(member));
+    });
+}
+/** Runtime-only admission; expected refusals and limits are 200 discriminated results. */
+function resolveChannelIdentity(store) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const decoded = Schema.decodeUnknownResult(ResolveIdentityRequest)(yield* jsonBody(request), {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        const { external_id: externalId, notice_version, notice_sha256, ...input } = decoded.success;
+        const resolution = yield* store.resolveIdentity({
+            ...input,
+            externalId,
+            ...(notice_version === undefined ? {} : { noticeVersion: notice_version }),
+            ...(notice_sha256 === undefined ? {} : { noticeSha256: notice_sha256 }),
+        });
+        switch (resolution.status) {
+            case "existing":
+            case "created":
+                return json({
+                    status: resolution.status,
+                    ...memberForWire(resolution.member),
+                    provisioned: resolution.provisioned,
+                    notice_due: resolution.noticeDue,
+                    on_new_user_pending: resolution.onNewUserPending,
+                });
+            case "limited":
+                return json({
+                    status: resolution.status,
+                    scope: resolution.scope,
+                    retry_after_seconds: resolution.retryAfterSeconds,
+                    notify: resolution.notify,
+                    ...(resolution.notificationId === undefined
+                        ? {}
+                        : { notification_id: resolution.notificationId }),
+                });
+            default:
+                return json(resolution);
+        }
+    });
+}
+/** Notice delivery is acknowledged only after the channel has accepted the fixed message. */
+function recordNotice(store) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const decoded = Schema.decodeUnknownResult(IdentityNoticeRequest)(yield* jsonBody(request), {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        const { provider, external_id: externalId, sha256, version } = decoded.success;
+        yield* store.recordNotice({
+            provider,
+            externalId,
+            sha256,
+            ...(version === undefined ? {} : { version }),
+        });
+        return HttpServerResponse.empty({ status: 204, headers: NO_STORE });
+    });
+}
+function completeLimitNotice(store) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const decoded = Schema.decodeUnknownResult(LimitNoticeRequest)(yield* jsonBody(request), {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        yield* store.completeLimitNotice({
+            notificationId: decoded.success.notification_id,
+            delivered: decoded.success.delivered,
+        });
+        return HttpServerResponse.empty({ status: 204, headers: NO_STORE });
+    });
+}
+/**
+ * `POST /api/ontology/agent/chats/seen` (runtime): the agent saw a message in a group chat. The chat
+ * is recorded, or its title kept current, a paired writer joins its members and a paired member who
+ * left is unlinked from them, or all of them when the agent itself left; the answer says what the
+ * chat is for, so that the agent knows it.
+ */
+function seeChat(store) {
+    return (request) => Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const decoded = Schema.decodeUnknownResult(ChatSeenRequest)(yield* jsonBody(request), {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return invalidBody(requestId, schemaIssues(decoded.failure));
+        }
+        const chat = yield* store.seeChat(decoded.success);
+        yield* Effect.logInfo("ontology.agent.chat_reported").pipe(Effect.annotateLogs({
+            requestId,
+            provider: decoded.success.provider,
+            chatId: decoded.success.externalId,
+        }));
+        return json(chat);
+    });
+}
+/** `GET /api/ontology/agent/identities` (member): the member's own live identities. */
+function listIdentities(store, member) {
+    return Effect.gen(function* () {
+        const identities = yield* store.listIdentities(member.id);
+        return json({ identities: identities.map(identityForWire) });
+    });
+}
+/** `DELETE /api/ontology/agent/identities/:id` (member): revokes one of the member's identities. */
+function revokeIdentity(store, member) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const id = yield* routeParam("id");
+        const revoked = yield* store.revokeIdentity({ id, userId: member.id });
+        if (!revoked) {
+            return toServerResponse(notFound(requestId, "You have no such identity."));
+        }
+        yield* Effect.logInfo("ontology.agent.unpaired").pipe(Effect.annotateLogs({ identityId: id, requestId }));
+        return HttpServerResponse.empty({ status: 204, headers: NO_STORE });
+    });
+}
+/**
+ * The routes that pair channel accounts with members for the app's own agent, and record the group
+ * chats it sees. Runtime routes take
+ * only the deployment's runtime token. Member routes take a member's Neon Auth session or token, and
+ * refuse API keys and the runtime, even acting as a member: only the member pairs or unpairs.
+ * Without the agent tables, it serves nothing.
+ */
+export function agentLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const store = backend.agents;
+        if (store === undefined) {
+            return;
+        }
+        const limiter = fixedWindowLimiter(PAIRING_LIMIT);
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        const bearerOf = (request) => Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+        const asRuntime = (answer) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* bearerOf(request);
+            const token = Redacted.value(bearer);
+            const verified = options.verifyRuntime === undefined || token === ""
+                ? undefined
+                : yield* Effect.promise(() => options.verifyRuntime(token));
+            switch (verified?.status) {
+                case "valid":
+                    // A task acts as its workflow's user, which pairs, resolves and records nothing here.
+                    return agentTaskSecret(request) === undefined
+                        ? yield* answer(request)
+                        : toServerResponse(forbidden(requestId, `This route does not accept ${AGENT_TASK_HEADER}.`));
+                case "invalid":
+                    yield* logRuntimeRejection(verified.reason);
+                    return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
+                case "unavailable":
+                    return toServerResponse(unavailable(requestId));
+                default:
+                    // Any other credential is authenticated as usual, so that it gets the usual 401, and
+                    // then refused: these routes are the agent's.
+                    return yield* withPrincipal(bearer, options.verifyToken, backend, Effect.succeed(toServerResponse(forbidden(requestId, "Only the app's agent calls this route."))));
+            }
+        });
+        const asMember = (answer) => (request) => Effect.gen(function* () {
+            const bearer = yield* bearerOf(request);
+            const decided = Effect.gen(function* () {
+                const requestId = yield* RequestId;
+                const principal = yield* CurrentPrincipal;
+                if (principal.kind !== "member") {
+                    return toServerResponse(forbidden(requestId, "Only a signed-in member can pair the app's agent."));
+                }
+                return yield* answer(request, principal);
+            });
+            return yield* withPrincipal(bearer, options.verifyToken, backend, decided, {
+                session: { request, exchange: options.exchangeSession },
+            });
+        });
+        if (store.confirmations !== undefined) {
+            // @legacy agent.retired-confirmation-ledger
+            yield* router.add("POST", `${AGENT_PATH}/confirmations`, asRuntime(confirmationCommand(store.confirmations)));
+        }
+        yield* router.add("POST", PAIRINGS_PATH, asRuntime(createPairing(store, limiter)));
+        yield* router.add("GET", `${PAIRINGS_PATH}/:code`, asMember(() => describePairing(store)));
+        yield* router.add("POST", `${PAIRINGS_PATH}/:code/approve`, asMember((_, member) => approvePairing(store, member)));
+        yield* router.add("GET", IDENTITIES_PATH, asMember((_, member) => listIdentities(store, member)));
+        yield* router.add("GET", `${IDENTITIES_PATH}/:provider/:external_id`, asRuntime(() => resolveIdentity(store)));
+        yield* router.add("POST", `${IDENTITIES_PATH}/resolve`, asRuntime(resolveChannelIdentity(store)));
+        yield* router.add("POST", `${IDENTITIES_PATH}/notice`, asRuntime(recordNotice(store)));
+        yield* router.add("POST", `${IDENTITIES_PATH}/limit-notice`, asRuntime(completeLimitNotice(store)));
+        for (const blocked of [true, false]) {
+            const operation = blocked ? "block" : "unblock";
+            yield* router.add("POST", `${AGENT_PATH}/members/:id/${operation}`, asRuntime(() => Effect.gen(function* () {
+                const requestId = yield* RequestId;
+                const id = yield* routeParam("id");
+                const updated = yield* store.setMemberBlocked({ id, blocked });
+                return updated
+                    ? HttpServerResponse.empty({ status: 204, headers: NO_STORE })
+                    : toServerResponse(notFound(requestId, "not_found"));
+            })));
+        }
+        yield* router.add("POST", CHATS_SEEN_PATH, asRuntime(seeChat(store)));
+        yield* router.add("DELETE", `${IDENTITIES_PATH}/:id`, asMember((_, member) => revokeIdentity(store, member)));
+    }));
+}

package/dist/service/agent/task-caller.d.ts

@@ -0,0 +1,21 @@
+import { Effect, Redacted } from "effect";
+import type { AgentTaskRecord } from "../../runtime/agent-tasks.js";
+import type { Principal } from "../../runtime.js";
+import { OntologyBackend } from "../runtime-contract.js";
+/** How a principal that a task's secret authenticated says it authenticated. */
+export declare const AGENT_TASK_AUTHENTICATION = "agent_task";
+export type AgentTaskCaller = {
+    readonly status: "live";
+    readonly task: AgentTaskRecord;
+    readonly principal: Principal;
+} | {
+    readonly status: "refused";
+    readonly detail: string;
+};
+/**
+ * The live task a secret names and the user it acts as: its workflow's user, resolved as the
+ * workflow's steps resolve it, with the roles it holds now. Refused when the secret matches no live
+ * task (an unknown secret, a terminal task or one past its deadline) or the workflow user is
+ * missing or inactive. The ontology resolves the identity from the task; the caller never names it.
+ */
+export declare function agentTaskCaller(secret: Redacted.Redacted<string>, workspaceId: string): Effect.Effect<AgentTaskCaller, never, OntologyBackend>;

package/dist/service/agent/task-caller.js

@@ -0,0 +1,35 @@
+import { Effect, Redacted } from "effect";
+import { OntologyBackend } from "../runtime-contract.js";
+import { taskSecretSha256 } from "./task-start.js";
+/** How a principal that a task's secret authenticated says it authenticated. */
+export const AGENT_TASK_AUTHENTICATION = "agent_task";
+/**
+ * The live task a secret names and the user it acts as: its workflow's user, resolved as the
+ * workflow's steps resolve it, with the roles it holds now. Refused when the secret matches no live
+ * task (an unknown secret, a terminal task or one past its deadline) or the workflow user is
+ * missing or inactive. The ontology resolves the identity from the task; the caller never names it.
+ */
+export function agentTaskCaller(secret, workspaceId) {
+    return Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        const task = backend.agentTasks === undefined
+            ? undefined
+            : yield* backend.agentTasks.live(taskSecretSha256(Redacted.value(secret)));
+        if (task === undefined) {
+            return { status: "refused", detail: "The task secret matches no live task." };
+        }
+        const principal = backend.resolveWorkflowUser === undefined
+            ? undefined
+            : yield* backend.resolveWorkflowUser({ workspaceId, workflow: task.workflow });
+        return principal === undefined
+            ? {
+                status: "refused",
+                detail: `The workflow user of ${task.workflow} is missing or inactive.`,
+            }
+            : {
+                status: "live",
+                task,
+                principal: { ...principal, authenticatedVia: AGENT_TASK_AUTHENTICATION },
+            };
+    });
+}