@segmentstream/ontology 0.0.0-stage → 0.92.1

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

@@ -0,0 +1,53 @@
+import { Effect, Schema } from "effect";
+import { type AgentTaskResult, type AgentTaskStart, type AgentTaskStarted } from "../../agent-task-contract.js";
+import type { AgentTaskStore } from "../../runtime/agent-tasks.js";
+/**
+ * The agent's task route. The deployment routes `/eve/*` to the app's agent, and eve reserves
+ * `/eve/v1/*`, so the route sits beside it.
+ */
+export declare const AGENT_TASK_ROUTE = "/eve/segmentstream/v1/tasks";
+/** A new task secret: 32 random bytes, base64url. */
+export declare function newTaskSecret(): string;
+/** The SHA-256 of a task secret, as `_agent_tasks` stores it and its header is looked up by. */
+export declare function taskSecretSha256(secret: string): string;
+/** How the start step reaches the app's agent: `fetch` by default. */
+export type AgentTransport = (request: Request) => Promise<Response>;
+declare const AgentTaskUnanswered_base: Schema.Class<AgentTaskUnanswered, Schema.TaggedStruct<"AgentTaskUnanswered", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/** The agent did not take the task: no answer, a server error, or a refusal while pending. Retried. */
+export declare class AgentTaskUnanswered extends AgentTaskUnanswered_base {
+}
+declare const AgentTaskRefused_base: Schema.Class<AgentTaskRefused, Schema.TaggedStruct<"AgentTaskRefused", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The agent refused the task in a way a retry repeats, such as a rejected token. Not retried. */
+export declare class AgentTaskRefused extends AgentTaskRefused_base {
+}
+export interface AgentTaskStartContext {
+    readonly store: AgentTaskStore;
+    /** The deployment's production origin; `undefined` outside production. */
+    readonly origin: string | undefined;
+    /** The service's own Vercel OIDC token; `undefined` outside a Vercel function. */
+    readonly identityToken: string | undefined;
+    /** Whether the service verifies the agent's runtime token, without which no task authenticates. */
+    readonly runtimeIdentity: boolean;
+    readonly transport: AgentTransport;
+    /** The workflow's wire name, whose user the task acts as. */
+    readonly workflow: string;
+    readonly runId: string;
+}
+/**
+ * `agentTask`'s start step: refuses as `busy` when 10 tasks are live, records the task under its
+ * hook token, mints its secret and hands it to the agent, which answers `202` once its session has
+ * accepted the prompt. A retried step finds the task: started or terminal, it is not handed again;
+ * still pending, it gets a new secret and is handed again. `404` means the deployment has no agent
+ * that takes tasks; no answer, `5xx` and a `409` while the task is still pending are retried.
+ * Outside production, or without the tokens a task needs, the agent is not called. The secret is
+ * sent to the agent only: it is never returned, logged or stored.
+ */
+export declare function startAgentTask(context: AgentTaskStartContext, input: AgentTaskStart): Effect.Effect<AgentTaskStarted, AgentTaskUnanswered | AgentTaskRefused>;
+/** Times a task out unless it already ended; its terminal outcome, which the workflow returns. */
+export declare function expireAgentTask(store: AgentTaskStore, taskId: string): Effect.Effect<AgentTaskResult>;
+export {};

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

@@ -0,0 +1,161 @@
+import { createHash, randomBytes } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { MAX_LIVE_AGENT_TASKS, } from "../../agent-task-contract.js";
+/**
+ * The agent's task route. The deployment routes `/eve/*` to the app's agent, and eve reserves
+ * `/eve/v1/*`, so the route sits beside it.
+ */
+export const AGENT_TASK_ROUTE = "/eve/segmentstream/v1/tasks";
+/** How long the agent has to accept a task before the attempt counts as unanswered. */
+const AGENT_TIMEOUT_MS = 30_000;
+/** A new task secret: 32 random bytes, base64url. */
+export function newTaskSecret() {
+    return randomBytes(32).toString("base64url");
+}
+/** The SHA-256 of a task secret, as `_agent_tasks` stores it and its header is looked up by. */
+export function taskSecretSha256(secret) {
+    return createHash("sha256").update(secret).digest("hex");
+}
+/** The agent did not take the task: no answer, a server error, or a refusal while pending. Retried. */
+export class AgentTaskUnanswered extends Schema.TaggedError()("AgentTaskUnanswered", { message: Schema.String, cause: Schema.optionalKey(Schema.Unknown) }) {
+}
+/** The agent refused the task in a way a retry repeats, such as a rejected token. Not retried. */
+export class AgentTaskRefused extends Schema.TaggedError()("AgentTaskRefused", {
+    message: Schema.String,
+}) {
+}
+const decided = (result) => ({ status: "decided", result });
+const unavailable = decided({ status: "failed", reason: "agent_unavailable" });
+/** The workflow waits for the task until the deadline its row fixed. */
+function waiting(task) {
+    return {
+        status: "waiting",
+        taskId: task.id,
+        remainingMs: Math.max(0, task.deadlineAt.getTime() - Date.now()),
+    };
+}
+/** What a task the start step did not hand the agent now means for the workflow. */
+function settled(task) {
+    if (task === undefined) {
+        return decided({ status: "timed_out" });
+    }
+    if (task.result !== undefined) {
+        return decided(task.result);
+    }
+    return task.status === "started" ? waiting(task) : undefined;
+}
+/**
+ * `agentTask`'s start step: refuses as `busy` when 10 tasks are live, records the task under its
+ * hook token, mints its secret and hands it to the agent, which answers `202` once its session has
+ * accepted the prompt. A retried step finds the task: started or terminal, it is not handed again;
+ * still pending, it gets a new secret and is handed again. `404` means the deployment has no agent
+ * that takes tasks; no answer, `5xx` and a `409` while the task is still pending are retried.
+ * Outside production, or without the tokens a task needs, the agent is not called. The secret is
+ * sent to the agent only: it is never returned, logged or stored.
+ */
+export function startAgentTask(context, input) {
+    return Effect.gen(function* () {
+        const { store, origin, identityToken } = context;
+        if (origin === undefined || identityToken === undefined || !context.runtimeIdentity) {
+            return unavailable;
+        }
+        let secret = newTaskSecret();
+        const created = yield* store.create({
+            hookToken: input.hookToken,
+            workflow: context.workflow,
+            runId: context.runId,
+            prompt: input.prompt,
+            timeoutMs: input.timeoutMs,
+            secretSha256: taskSecretSha256(secret),
+            limit: MAX_LIVE_AGENT_TASKS,
+        });
+        if (created.status === "busy") {
+            return decided({ status: "failed", reason: "busy" });
+        }
+        const { task } = created;
+        if (created.status === "existing") {
+            const known = settled(task);
+            if (known !== undefined) {
+                return known;
+            }
+            if (task.deadlineAt.getTime() <= Date.now()) {
+                return yield* expired(store, task.id);
+            }
+            secret = newTaskSecret();
+            if (!(yield* store.rekey(task.id, taskSecretSha256(secret)))) {
+                return settled(yield* store.byHook(input.hookToken)) ?? unavailable;
+            }
+        }
+        const status = yield* handOver(context, origin, identityToken, task.id, secret);
+        yield* Effect.logInfo("ontology.agent_task.handed_over").pipe(Effect.annotateLogs({
+            taskId: task.id,
+            workflow: context.workflow,
+            workflowRunId: context.runId,
+            status,
+        }));
+        if (status === 202) {
+            return (yield* store.markStarted(task.id))
+                ? waiting(task)
+                : (settled(yield* store.byHook(input.hookToken)) ?? waiting(task));
+        }
+        if (status === 404) {
+            const { task: after } = yield* store.finish(task.id, {
+                status: "failed",
+                reason: "agent_unavailable",
+            });
+            return settled(after) ?? unavailable;
+        }
+        if (status === 409) {
+            // The agent found the task not live: it ended, timed out, or another attempt rekeyed it.
+            const current = yield* store.byHook(input.hookToken);
+            const known = settled(current);
+            if (known !== undefined) {
+                return known;
+            }
+            if (current !== undefined && current.deadlineAt.getTime() <= Date.now()) {
+                return yield* expired(store, current.id);
+            }
+        }
+        if (status === 409 || status >= 500) {
+            return yield* new AgentTaskUnanswered({
+                message: `The app's agent answered the task with HTTP ${status}; the step retries.`,
+            });
+        }
+        // The workflow fails, so the task ends now rather than holding a live slot until its deadline.
+        yield* store.finish(task.id, { status: "failed", reason: "agent_unavailable" });
+        return yield* new AgentTaskRefused({
+            message: `The app's agent refused the task with HTTP ${status}.`,
+        });
+    });
+}
+/** Times a task out unless it already ended; its terminal outcome, which the workflow returns. */
+export function expireAgentTask(store, taskId) {
+    return store
+        .finish(taskId, { status: "timed_out" })
+        .pipe(Effect.map(({ task }) => task?.result ?? { status: "timed_out" }));
+}
+function expired(store, taskId) {
+    return Effect.map(expireAgentTask(store, taskId), decided);
+}
+/** `POST <origin>/eve/segmentstream/v1/tasks` as the deployment: the agent's status code. */
+function handOver(context, origin, identityToken, taskId, secret) {
+    return Effect.tryPromise({
+        try: async () => {
+            const response = await context.transport(new Request(new URL(AGENT_TASK_ROUTE, origin), {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${identityToken}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({ task_id: taskId, secret }),
+                signal: AbortSignal.timeout(AGENT_TIMEOUT_MS),
+            }));
+            await response.body?.cancel().catch(() => undefined);
+            return response.status;
+        },
+        catch: (cause) => new AgentTaskUnanswered({
+            message: "The app's agent did not answer the task; the step retries.",
+            cause,
+        }),
+    });
+}

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

@@ -0,0 +1,40 @@
+import { Layer, Schema } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { 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 { WorkflowEngine } from "../workflows.js";
+/** The task the agent runs, as its secret names it. */
+export declare const AGENT_TASK_PATH = "/api/ontology/agent/tasks/current";
+/** Where the agent reports the task's outcome. */
+export declare const AGENT_TASK_RESULT_PATH = "/api/ontology/agent/tasks/current/result";
+/** `POST …/tasks/current/result`: the outcome of the task's turn, as the agent reports it. */
+export declare const AgentTaskReport: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"completed">;
+    readonly text: Schema.String;
+    readonly truncated: Schema.Boolean;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"needs_input">;
+    readonly text: Schema.String;
+    readonly truncated: Schema.Boolean;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"failed">;
+    readonly reason: Schema.Literal<"agent_failed">;
+}>]>;
+export interface AgentTaskRoutesOptions {
+    readonly verifyToken: TokenVerifier;
+    /** The deployment's runtime tokens; `undefined` while runtime authentication is disabled. */
+    readonly verifyRuntime: RuntimeTokenVerifier | undefined;
+    /** The workspace whose workflow users the tasks act as. */
+    readonly workspaceId: string;
+    /** Resumes the workflow waiting on a task. */
+    readonly engine: WorkflowEngine;
+}
+/**
+ * The routes of the tasks workflows hand the app's agent with `agentTask`. Both take only the
+ * deployment's runtime token with a live task's secret in `X-SegmentStream-Agent-Task`, and never
+ * a member named in `X-SegmentStream-Act-As`: `403` when the secret names no live task or its
+ * workflow user is inactive. Without the task table, it serves nothing.
+ */
+export declare function agentTasksLayer(options: AgentTaskRoutesOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;

package/dist/service/agent/tasks.js

@@ -0,0 +1,155 @@
+import { Effect, Layer, Redacted, Result, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiSecurity } from "effect/unstable/httpapi";
+import { MAX_AGENT_TASK_TEXT_LENGTH } from "../../agent-task-contract.js";
+import { MEMBER_ROLE } from "../../names.js";
+import { schemaIssues } from "../../runtime/validation.js";
+import { BASE_PATH } from "../api.js";
+import { withPrincipal } from "../authentication.js";
+import { RequestId, errorBodyForWire, forbidden, internalError, toServerResponse, unauthorized, unavailable, } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+import { ACT_AS_HEADER, AGENT_TASK_HEADER, agentTaskSecret, logRuntimeRejection, } from "../runtime-identity.js";
+import { agentTaskCaller } from "./task-caller.js";
+/** The task the agent runs, as its secret names it. */
+export const AGENT_TASK_PATH = `${BASE_PATH}/agent/tasks/current`;
+/** Where the agent reports the task's outcome. */
+export const AGENT_TASK_RESULT_PATH = `${AGENT_TASK_PATH}/result`;
+const NO_STORE = { "cache-control": "no-store" };
+const Text = Schema.String.check(Schema.isMaxLength(MAX_AGENT_TASK_TEXT_LENGTH)).annotate({
+    description: "The agent's final text, or its question; longer text is cut and marked truncated.",
+});
+/** `POST …/tasks/current/result`: the outcome of the task's turn, as the agent reports it. */
+export const AgentTaskReport = Schema.Union([
+    Schema.Struct({ status: Schema.Literal("completed"), text: Text, truncated: Schema.Boolean }),
+    Schema.Struct({ status: Schema.Literal("needs_input"), text: Text, truncated: Schema.Boolean }),
+    Schema.Struct({ status: Schema.Literal("failed"), reason: Schema.Literal("agent_failed") }),
+]);
+function json(body, status = 200) {
+    return HttpServerResponse.jsonUnsafe(body, { status, headers: NO_STORE });
+}
+/**
+ * `GET /api/ontology/agent/tasks/current`: the task, its prompt and deadline, and the user it acts
+ * as, from the ontology's records, never from the agent's request.
+ */
+function currentTask(backend, { task, principal }) {
+    return Effect.gen(function* () {
+        const user = yield* backend
+            .get({ entity: "user", id: principal.id })
+            .pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+        return json({
+            id: task.id,
+            workflow: task.workflow,
+            prompt: task.prompt,
+            deadline_at: task.deadlineAt.toISOString(),
+            principal: {
+                id: principal.id,
+                name: typeof user?.name === "string" ? user.name : task.workflow,
+                roles: [...new Set([...principal.roles, MEMBER_ROLE])],
+            },
+        });
+    });
+}
+/**
+ * `POST /api/ontology/agent/tasks/current/result`: the task ends with the agent's outcome, and the
+ * workflow waiting on it resumes. The first outcome wins: a later report answers `409`. A workflow
+ * that no longer waits still answers `200`; one the engine could not resume reads the outcome at the
+ * task's deadline.
+ */
+function reportResult(store, engine, request, { task }) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const text = yield* Effect.orDie(request.text);
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            body = undefined;
+        }
+        const decoded = Schema.decodeUnknownResult(AgentTaskReport)(body, {
+            errors: "all",
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+                error: "invalid_request",
+                detail: "The request body is invalid.",
+                requestId,
+                issues: schemaIssues(decoded.failure),
+            }), { status: 400 });
+        }
+        const result = decoded.success;
+        const { finished } = yield* store.finish(task.id, result);
+        const annotations = {
+            requestId,
+            taskId: task.id,
+            workflow: task.workflow,
+            outcome: result.status,
+        };
+        if (!finished) {
+            return HttpServerResponse.jsonUnsafe(errorBodyForWire({
+                error: "conflict",
+                detail: "The task already ended; the first report wins.",
+                requestId,
+            }), { status: 409 });
+        }
+        yield* Effect.logInfo("ontology.agent_task.reported").pipe(Effect.annotateLogs(annotations));
+        const resumed = yield* Effect.tryPromise(() => engine.resumeHook?.(task.hookToken, result) ?? Promise.resolve("not_found")).pipe(Effect.result);
+        if (Result.isFailure(resumed)) {
+            yield* Effect.logError("ontology.agent_task.resume_failed", resumed.failure).pipe(Effect.annotateLogs(annotations));
+            return toServerResponse(internalError(requestId));
+        }
+        return json({ accepted: true });
+    });
+}
+/**
+ * The routes of the tasks workflows hand the app's agent with `agentTask`. Both take only the
+ * deployment's runtime token with a live task's secret in `X-SegmentStream-Agent-Task`, and never
+ * a member named in `X-SegmentStream-Act-As`: `403` when the secret names no live task or its
+ * workflow user is inactive. Without the task table, it serves nothing.
+ */
+export function agentTasksLayer(options) {
+    return Layer.effectDiscard(Effect.gen(function* () {
+        const router = yield* HttpRouter.HttpRouter;
+        const backend = yield* OntologyBackend;
+        const store = backend.agentTasks;
+        if (store === undefined) {
+            return;
+        }
+        const credential = HttpApiBuilder.securityDecode(HttpApiSecurity.bearer);
+        const asTask = (answer) => (request) => Effect.gen(function* () {
+            const requestId = yield* RequestId;
+            const bearer = yield* Effect.provideService(credential, HttpServerRequest.HttpServerRequest, request);
+            const token = Redacted.value(bearer);
+            const verified = options.verifyRuntime === undefined || token === ""
+                ? undefined
+                : yield* Effect.promise(() => options.verifyRuntime(token));
+            const refused = (detail) => toServerResponse(forbidden(requestId, detail));
+            switch (verified?.status) {
+                case "valid":
+                    break;
+                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, for the usual 401, then refused.
+                    return yield* withPrincipal(bearer, options.verifyToken, backend, Effect.succeed(refused("Only the app's agent calls this route.")));
+            }
+            const secret = agentTaskSecret(request);
+            if (secret === undefined) {
+                return refused(`The app's agent presents the task's secret in ${AGENT_TASK_HEADER}.`);
+            }
+            if ((request.headers[ACT_AS_HEADER]?.trim() ?? "") !== "") {
+                return refused(`A request names a member in ${ACT_AS_HEADER} or a task in ${AGENT_TASK_HEADER}, not both.`);
+            }
+            const caller = yield* agentTaskCaller(secret, options.workspaceId).pipe(Effect.provideService(OntologyBackend, backend));
+            return caller.status === "refused"
+                ? refused(caller.detail)
+                : yield* answer(request, caller);
+        });
+        yield* router.add("GET", AGENT_TASK_PATH, asTask((_, live) => currentTask(backend, live)));
+        yield* router.add("POST", AGENT_TASK_RESULT_PATH, asTask((request, live) => reportResult(store, options.engine, request, live)));
+    }));
+}

package/dist/service/api.d.ts

@@ -0,0 +1,50 @@
+import { Layer, Schema } from "effect";
+import { HttpApi, HttpApiGroup, HttpApiMiddleware } from "effect/unstable/httpapi";
+import type { Ontology } from "../ontology.js";
+import { RequestId } from "./errors.js";
+import { type ApiPlan, type PlannedEntity } from "./plan.js";
+import type { GeneratedActionsProvider } from "./runtime-contract.js";
+import { type EntitySchemas } from "./schemas.js";
+/** The path every ontology route lives under. */
+export declare const BASE_PATH = "/api/ontology";
+/** The group of the global routes. Entity names are snake_case, so it cannot clash with one. */
+export declare const SERVICE_GROUP = "Ontology";
+/** The API of one ontology: its groups are the entities' names and {@link SERVICE_GROUP}. */
+export type OntologyApi = HttpApi.HttpApi<"ontology", HttpApiGroup.Top>;
+declare const ErrorResponses_base: HttpApiMiddleware.ServiceClass<ErrorResponses, "@segmentstream/ontology/ErrorResponses", {
+    requires: RequestId;
+    provides: never;
+    error: readonly [Schema.Top, Schema.Top];
+    clientError: never;
+    requiredForClient: false;
+    security: never;
+}, HttpApiMiddleware.HttpApiMiddleware<never, readonly [Schema.Top, Schema.Top], RequestId>>;
+/**
+ * Maps every failure of a route, including input that fails its schema, to the service's error
+ * responses. It runs inside {@link Authentication}, so unauthenticated requests never reach it.
+ */
+export declare class ErrorResponses extends ErrorResponses_base {
+}
+export declare const ErrorResponsesLive: Layer.Layer<ErrorResponses, never, never>;
+/** Whether an entity declares metrics, and so has `POST /api/ontology/<entity>/query_metrics`. */
+export declare function hasMetrics(planned: PlannedEntity): boolean;
+/** The name of the metric query endpoints at their current paths, in the service and entity groups. */
+export declare const QUERY_METRICS_ENDPOINT = "queryMetrics";
+export interface BuiltApi {
+    readonly plan: ApiPlan;
+    readonly api: OntologyApi;
+    readonly schemas: ReadonlyMap<string, EntitySchemas>;
+}
+export declare function buildApi(plan: ApiPlan): BuiltApi;
+export interface DeriveApiOptions {
+    /** The generated actions, whose routes sit beside the authored ones: the runtime's by default. */
+    readonly generatedActions?: GeneratedActionsProvider;
+}
+/**
+ * The HttpApi of an ontology: per entity `find`, `query`, `get`, `history`, a traversal per
+ * relationship and inverse, and a route per generated and authored action; and the catalog, graph,
+ * OpenAPI, status, caller (`me`), sign-in check, prose and metric query routes. There is no PUT, PATCH
+ * or DELETE: every change is an action.
+ */
+export declare function deriveApi(ontology: Ontology, options?: DeriveApiOptions): OntologyApi;
+export {};