@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/action.d.ts

@@ -0,0 +1,193 @@
+import type { ActionConfirmation, ConfirmContext } from "./confirmation.js";
+import type { ActionRuntime } from "./runtime-source.js";
+import type { Files, FileTarget } from "./files.js";
+import { Effect, Schema } from "effect";
+import type { AnyConnectionHandle, Connection, ConnectionError, ConnectionsOf } from "./connection.js";
+import type { AnyEntity } from "./entity.js";
+import type { ActionError } from "./errors.js";
+import type { OntologyReads, OntologyRuntime, Principal } from "./runtime.js";
+export declare const ActionTypeId: unique symbol;
+/** What `prepare` runs with. */
+export interface PrepareContext<Input> {
+    /** The input, already decoded with the action's input schema. */
+    readonly input: Input;
+    readonly principal: Principal;
+    /** Verified runtime provenance, absent for ordinary member, OAuth and API-key callers. */
+    readonly runtime?: ActionRuntime;
+    /** The id of the request, for logs. Never derive a provider idempotency key from it. */
+    readonly requestId: string;
+}
+/** A live channel account of the member invoking the action. */
+export declare const ActionIdentity: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly subject: Schema.String;
+    readonly username: Schema.optionalKey<Schema.String>;
+    readonly verified: Schema.Literal<true>;
+}>;
+export type ActionIdentity = typeof ActionIdentity.Type;
+export interface ActionContext<Input, Prepared = undefined> extends PrepareContext<Input> {
+    /** Current live channel identities, loaded for the handler without changing Principal. */
+    readonly principal: Principal & {
+        readonly identities: ReadonlyArray<ActionIdentity>;
+        readonly createdVia: string;
+        readonly authenticatedVia: string;
+    };
+    /** What `prepare` returned; `undefined` for an action without `prepare`. */
+    readonly prepared: Prepared;
+}
+/** What `prepare` may fail with: the action errors, and connection calls that failed. */
+export type PrepareError = ActionError | ConnectionError;
+/**
+ * How an action behaves. Agents confirm destructive, irreversible or external actions before
+ * preparation. Actions with connections are external even when both safety hints are false,
+ * except for enforced read-only prepare actions declared with `readOnly: true`.
+ * Permitted, routine reversible actions can run without confirmation.
+ * Custom actions without safety labels require confirmation for backwards compatibility.
+ * Idempotence does not decide whether confirmation is needed.
+ */
+export interface ActionHints {
+    /**
+     * A prepare-only action that reads without changing records or providers. Requires `prepare`
+     * without a handler. Its connection clients enforce GET/HEAD/OPTIONS without method overrides.
+     */
+    readonly readOnly?: boolean;
+    /** Enforce GET/HEAD/OPTIONS for every preparation connection, while allowing local handler writes. */
+    readonly connectionsReadOnly?: boolean;
+    /** 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;
+}
+/** A described, typed, permissioned Effect function: the only way to change records. */
+export interface Action<Input extends Schema.Top = Schema.Top, Result = unknown> {
+    readonly [ActionTypeId]: typeof ActionTypeId;
+    readonly description: string;
+    readonly input: Input;
+    /**
+     * The permission a principal needs to run the action, as `action({ permission })` set it. When it
+     * is not set, the action requires `<entity>:<action name>`, for example `lead:changeStatus`.
+     */
+    readonly permission: string | undefined;
+    /** How the action behaves, as `action({ hints })` set it; see {@link ActionHints}. */
+    readonly hints: ActionHints | undefined;
+    /** See `action({ retryOnDeadlock })`. Absent or false means the handler runs at most once. */
+    readonly retryOnDeadlock?: boolean;
+    /** See `action({ writes })`. Absent means the handler may write any entity. */
+    readonly writes?: ReadonlyArray<ActionWriteTarget>;
+    /** The connections `prepare` may call; empty for an action without `prepare`. */
+    readonly connections: ReadonlyArray<AnyConnectionHandle>;
+    /** File targets preparation may stage, declared with uploads.target. Absent on older actions. */
+    readonly files?: ReadonlyArray<FileTarget>;
+    /** Describes what a person confirms before an agent runs the action; see `action({ confirm })`. */
+    confirm?(context: ConfirmContext<Input["Type"]>): Effect.Effect<ActionConfirmation, ActionError, OntologyReads>;
+    /**
+     * Runs before the transaction, with reads, declared connections and file access; see
+     * {@link ActionConfigWithConnections}.
+     */
+    prepare?(context: PrepareContext<Input["Type"]>): Effect.Effect<unknown, PrepareError, OntologyReads | Connection<string> | Files>;
+    /**
+     * Runs in the transaction. An action declared with `prepare` and no handler gets one that returns
+     * what `prepare` returned, and `transactional: false`.
+     */
+    handler(context: ActionContext<Input["Type"], unknown>): Effect.Effect<Result, ActionError, OntologyRuntime>;
+    /** Whether the runtime opens a transaction for the handler; false for a `prepare`-only action. */
+    readonly transactional: boolean;
+}
+/** Any action, whatever its input and result. */
+export type AnyAction = Action<any, any>;
+/** An entity's authored actions by name, as `.actions(…)` returns them. */
+export type Actions = {
+    readonly [name: string]: AnyAction;
+};
+/** The input of an action as its handler receives it: the decoded form of its input schema. */
+export type ActionInput<A> = A extends Action<infer Input extends Schema.Top, unknown> ? Input["Type"] : never;
+/** The input of an action as a caller sends it: the encoded form of its input schema. */
+export type ActionEncodedInput<A> = A extends Action<infer Input extends Schema.Top, unknown> ? Input["Encoded"] : never;
+/** What an action's handler succeeds with: the `result` of an action response. */
+export type ActionResult<A> = A extends Action<Schema.Top, infer Result> ? Result : never;
+interface ActionOptions<Input extends Schema.Top> {
+    readonly description: string;
+    /** Usually a `Schema.Struct` of property schemas, entity references and other schemas. */
+    readonly input: Input;
+    /**
+     * The permission a principal needs to run the action. It defaults to `<entity>:<action name>`;
+     * set it only to share one permission between actions, for example two actions behind `lead:edit`.
+     * Roles grant it in their `permissions`.
+     */
+    readonly permission?: string;
+    /**
+     * How the action behaves, for the agents that run it over MCP. Set `destructive: false` for an
+     * 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;
+    /**
+     * Opt in to at most two retries after a PostgreSQL deadlock and completed rollback. The handler,
+     * including its wrappers, must have only transactional database effects, keep input and prepared
+     * values immutable, and recreate all attempt-local state on each call. Trigger functions must
+     * also be pure. Preparation runs once; its result is reused. After-commit effects run once.
+     * This is independent of `hints.idempotent`. Defaults to false.
+     */
+    readonly retryOnDeadlock?: boolean;
+    /**
+     * The entities the handler writes, such as `[self, Note]`; a thunk (`() => Note`) names an entity
+     * a circular import has not defined yet. The runtime refuses any other write of the handler, the
+     * manifest lists them, and agents read them in the action's description, so "what changes what"
+     * is declared. `[]` declares an action that writes nothing. Absent, the handler may write any
+     * entity, as before.
+     */
+    readonly writes?: ReadonlyArray<ActionWriteTarget>;
+    /**
+     * What a person confirms before an agent runs the action for them: the card the agent shows,
+     * with its title, the facts to check and secondary detail, in `locale`, the chat's language.
+     * It runs after the permission check, with reads only, and writes nothing. Fail with
+     * `ActionRejected` when the action would refuse this input: the agent then tells the person why
+     * instead of asking. Without it, agents show the action's fields.
+     */
+    readonly confirm?: (context: ConfirmContext<Input["Type"]>) => Effect.Effect<ActionConfirmation, ActionError, OntologyReads>;
+}
+/** An entity an action writes: its handle, or a thunk for a circular import. */
+export type ActionWriteTarget = AnyEntity | (() => AnyEntity);
+export interface ActionConfig<Input extends Schema.Top, Result> extends ActionOptions<Input> {
+    /**
+     * Runs inside the action's transaction. It reads and writes through entity handles (`Lead.get`,
+     * `Lead.update`, …), which require {@link OntologyRuntime}, and fails only with the action errors.
+     */
+    readonly handler: (context: ActionContext<Input["Type"]>) => Effect.Effect<Result, ActionError, OntologyRuntime>;
+    /** Set only with `prepare`; see {@link ActionConfigWithConnections}. */
+    readonly connections?: undefined;
+    readonly prepare?: undefined;
+    readonly files?: undefined;
+}
+/**
+ * An action that calls connections. `prepare` runs after the permission check and before the
+ * transaction, with reads and the declared connections but no writes, so a provider's latency never
+ * holds a database connection or a lock. `handler` then runs in the transaction with what `prepare`
+ * returned, and cannot call connections.
+ *
+ * `prepare` sees committed data without locks: a handler whose write depends on what `prepare` read
+ * re-reads it with `forUpdate` and checks it again. A provider write in `prepare` happens even when
+ * the transaction later fails, so derive its idempotency key from the record, never from the request.
+ */
+export interface ActionConfigWithConnections<Input extends Schema.Top, C extends ReadonlyArray<AnyConnectionHandle>, Prepared, Result> extends ActionOptions<Input> {
+    /** The connection handles `prepare` calls; each is listed in `defineOntology({ connections })`. */
+    readonly connections: C;
+    readonly files?: ReadonlyArray<FileTarget>;
+    readonly prepare: (context: PrepareContext<Input["Type"]>) => Effect.Effect<Prepared, PrepareError, OntologyReads | ConnectionsOf<C> | Files>;
+    /**
+     * Runs in the transaction with `prepared`, as an action without connections does. Omit it when
+     * the action writes nothing: its result is then what `prepare` returned, and no transaction opens.
+     */
+    readonly handler?: (context: ActionContext<Input["Type"], Prepared>) => Effect.Effect<Result, ActionError, OntologyRuntime>;
+}
+export declare function action<Input extends Schema.Top, Result>(config: ActionConfig<Input, Result>): Action<Input, Result>;
+export declare function action<Input extends Schema.Top, const C extends ReadonlyArray<AnyConnectionHandle>, Prepared>(config: ActionConfigWithConnections<Input, C, Prepared, never> & {
+    readonly handler?: undefined;
+}): Action<Input, Prepared>;
+export declare function action<Input extends Schema.Top, const C extends ReadonlyArray<AnyConnectionHandle>, Prepared, Result>(config: ActionConfigWithConnections<Input, C, Prepared, Result>): Action<Input, Result>;
+/** Whether a value was declared with `action(…)`; an entity handle's callable actions are too. */
+export declare function isAction(value: unknown): value is Action;
+export {};

package/dist/action.js

@@ -0,0 +1,41 @@
+import { Effect, Schema } from "effect";
+export const ActionTypeId = Symbol.for("@segmentstream/ontology/Action");
+/** A live channel account of the member invoking the action. */
+export const ActionIdentity = Schema.Struct({
+    provider: Schema.String,
+    subject: Schema.String,
+    username: Schema.optionalKey(Schema.String),
+    verified: Schema.Literal(true),
+});
+// @legacy ontology.removed-allow-option
+/** Options removed from earlier releases, kept on the action so that `check` can explain them. */
+function removedOptions(config) {
+    return "allow" in config ? { allow: config.allow } : {};
+}
+export function action(config) {
+    return {
+        ...removedOptions(config),
+        [ActionTypeId]: ActionTypeId,
+        description: config.description,
+        input: config.input,
+        permission: config.permission,
+        hints: config.hints,
+        ...(config.retryOnDeadlock === undefined ? {} : { retryOnDeadlock: config.retryOnDeadlock }),
+        ...(config.writes === undefined ? {} : { writes: config.writes }),
+        ...(config.confirm === undefined ? {} : { confirm: config.confirm }),
+        connections: config.connections ?? [],
+        ...(config.files === undefined ? {} : { files: config.files }),
+        ...(config.prepare === undefined ? {} : { prepare: config.prepare }),
+        // A prepare-only action answers with what prepare returned; it writes nothing.
+        handler: config.handler === undefined && config.prepare !== undefined
+            ? ({ prepared }) => Effect.succeed(prepared)
+            : config.handler,
+        transactional: config.handler !== undefined || config.prepare === undefined,
+    };
+}
+/** Whether a value was declared with `action(…)`; an entity handle's callable actions are too. */
+export function isAction(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        ActionTypeId in value);
+}

package/dist/agent-chat.d.ts

@@ -0,0 +1,44 @@
+export declare const TELEGRAM = "telegram";
+/** Existing chat registry and membership storage; delivery lives in the ontology service. */
+export declare const AgentChat: import("./entity.js").Entity<"agent_chat", {
+    readonly provider: import("./property.js").Property<string, false, false>;
+    readonly externalId: import("./property.js").Property<string, false, false>;
+    readonly title: import("./property.js").Property<string, false, false>;
+    readonly lastMessageAt: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly purpose: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly whenToUse: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+}, {
+    readonly members: import("./relationship.js").ManyRelationship;
+}, import("./entity.js").InvocableActions<{
+    readonly previewMessage: import("./action.js").Action<import("effect/Schema").Struct<{
+        readonly chat: import("effect/Schema").String;
+        readonly text: import("effect/Schema").String;
+        readonly replyTo: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+        readonly idempotencyKey: import("effect/Schema").String;
+    }>, import("./chat.js").ChatPreview>;
+    readonly postMessage: import("./action.js").Action<import("effect/Schema").Struct<{
+        readonly chat: import("effect/Schema").String;
+        readonly text: import("effect/Schema").String;
+        readonly replyTo: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+        readonly idempotencyKey: import("effect/Schema").String;
+    }>, {
+        readonly status: "sent" | "uncertain";
+        readonly message_id: string | null;
+        readonly url: string | null;
+        readonly duplicate: boolean;
+        readonly history_recorded: boolean;
+    }>;
+}, "agent_chat", {
+    readonly id: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
+    readonly provider: string;
+    readonly externalId: string;
+    readonly title: string;
+    readonly lastMessageAt: string | null;
+    readonly purpose: string | null;
+    readonly whenToUse: string | null;
+}>, Readonly<Record<never, never>>, "generated">;
+export type AgentChat = typeof AgentChat.Type;

package/dist/agent-chat.js

@@ -0,0 +1,91 @@
+import { Effect, Option } from "effect";
+import { action } from "./action.js";
+import { entity } from "./entity.js";
+import { ActionRejected } from "./errors.js";
+import { ChatDelivery, ChatPostInput } from "./chat.js";
+import { p } from "./property.js";
+import { rel } from "./relationship.js";
+export const TELEGRAM = "telegram";
+/** Existing chat registry and membership storage; delivery lives in the ontology service. */
+export const AgentChat = entity("agent_chat", {
+    id: "ent_agent_chat",
+    label: "Agent chat",
+    plural: "Agent chats",
+    title: "title",
+    description: "A group chat the workspace's agent is in. The agent records each chat it sees; " +
+        "members say what the chat is for, so that agents know where to write.",
+    properties: {
+        provider: p.text({ managed: true, description: "The channel, for example telegram." }),
+        externalId: p.text({ managed: true, description: "The chat's id at the provider." }),
+        title: p.text({
+            managed: true,
+            description: "The chat's name at the provider, kept current by the agent.",
+        }),
+        lastMessageAt: p.timestamp({
+            optional: true,
+            managed: true,
+            label: "Last message",
+            description: "When the agent last saw a message in the chat, recorded at most every 15 minutes.",
+        }),
+        purpose: p.text({
+            optional: true,
+            maxLength: 64,
+            description: "A short key that code and agents look the chat up by, such as accounting.",
+        }),
+        whenToUse: p.text({
+            optional: true,
+            maxLength: 1000,
+            display: "multiline",
+            label: "When to use",
+            description: "For agents: what the chat is for and when to write there, such as " +
+                '"Invoices and payments; Yulia answers on weekdays."',
+        }),
+    },
+    relationships: {
+        // By name, so that an ontology rebuilt with the deployed `user` still resolves it.
+        members: rel.many("user", {
+            inverse: "agentChats",
+            phrase: ["includes", "is in"],
+            description: "Workspace members the agent has seen writing in the chat.",
+        }),
+    },
+    indexes: [{ properties: ["provider", "externalId"], unique: true }],
+}).actions(() => ({
+    previewMessage: action({
+        description: "Render an exact chat message with its verified destination and sender attribution, without reserving a key, " +
+            "writing history or sending. Requires the same explicit post permission as delivery. " +
+            "A preview is not authorization to send.",
+        permission: "agent_chat:post_message",
+        input: ChatPostInput,
+        connections: [],
+        hints: { readOnly: true, destructive: false, irreversible: false, idempotent: true },
+        prepare: ({ input }) => Effect.gen(function* () {
+            const delivery = yield* Effect.serviceOption(ChatDelivery);
+            if (Option.isNone(delivery)) {
+                return yield* new ActionRejected({
+                    message: "Chat preview requires the authenticated ontology service.",
+                });
+            }
+            return yield* delivery.value.preview(input);
+        }),
+    }),
+    postMessage: action({
+        description: "Post to an eligible chat ID or exact title. text is Markdown (bold, italic, code, lists, " +
+            "[text](url)); each channel renders it natively and degrades constructs it can't show. " +
+            "The exact Markdown source is posted; the platform adds the sender attribution. " +
+            "Ambiguous titles require an explicit ID. Confirm the full final text, attribution and destination " +
+            "before calling. Reuse the same idempotency key on replay; an uncertain operation is never resent.",
+        input: ChatPostInput,
+        hints: { destructive: false, irreversible: true, idempotent: true },
+        connections: [],
+        prepare: ({ input }) => Effect.gen(function* () {
+            const delivery = yield* Effect.serviceOption(ChatDelivery);
+            if (Option.isNone(delivery)) {
+                return yield* new ActionRejected({
+                    message: "Chat delivery requires the authenticated ontology service.",
+                });
+            }
+            return yield* delivery.value.post(input);
+        }),
+    }),
+}));

package/dist/agent-task-contract.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What `agentTask` and the ontology service share: its limits and the values its steps exchange.
+ * This module holds no workflow or step function, so the package's root entry, which the platform's
+ * backend bundles with another Workflow SDK major, may import it without bundling a step.
+ */
+/** The most tasks a workspace has live at once; one more is refused as `busy`. */
+export declare const MAX_LIVE_AGENT_TASKS = 10;
+/** The longest prompt, in characters. */
+export declare const MAX_AGENT_TASK_PROMPT_LENGTH = 32768;
+/** The longest text the agent reports; it cuts longer text and sets `truncated`. */
+export declare const MAX_AGENT_TASK_TEXT_LENGTH = 65536;
+/** How long a task may run, by default and at most: 15 minutes, 1 minute and 1 hour. */
+export declare const DEFAULT_AGENT_TASK_TIMEOUT_MS = 900000;
+export declare const MIN_AGENT_TASK_TIMEOUT_MS = 60000;
+export declare const MAX_AGENT_TASK_TIMEOUT_MS = 3600000;
+export interface AgentTaskOptions {
+    /** 1 to 32,768 characters, all of it the workspace's. */
+    readonly prompt: string;
+    /** Default 900,000 (15 minutes); at least 60,000 and at most 3,600,000. */
+    readonly timeoutMs?: number;
+}
+export type AgentTaskFailure = 
+/** The deployment has no agent, its agent predates tasks, or the call ran outside production. */
+"agent_unavailable"
+/** The workspace already has 10 live tasks; the agent was not called. */
+ | "busy"
+/** The agent accepted the task and its turn failed, including its per-session cost cap. */
+ | "agent_failed";
+export type AgentTaskResult = {
+    readonly status: "completed";
+    readonly text: string;
+    readonly truncated: boolean;
+}
+/** The agent asked a person something; `text` is its question. */
+ | {
+    readonly status: "needs_input";
+    readonly text: string;
+    readonly truncated: boolean;
+} | {
+    readonly status: "failed";
+    readonly reason: AgentTaskFailure;
+} | {
+    readonly status: "timed_out";
+};
+/** What the start step hands the service: the hook to resume, the prompt and the timeout. */
+export interface AgentTaskStart {
+    readonly hookToken: string;
+    readonly prompt: string;
+    readonly timeoutMs: number;
+}
+/**
+ * What the start step answers: the task the workflow now waits for, or the outcome it already has
+ * (the agent was not called, refused, or the task ended before a retried step found it).
+ */
+export type AgentTaskStarted = 
+/** `remainingMs` runs to the task's deadline, which its row fixed when the start created it. */
+{
+    readonly status: "waiting";
+    readonly taskId: string;
+    readonly remainingMs: number;
+} | {
+    readonly status: "decided";
+    readonly result: AgentTaskResult;
+};

package/dist/agent-task-contract.js

@@ -0,0 +1,15 @@
+/**
+ * What `agentTask` and the ontology service share: its limits and the values its steps exchange.
+ * This module holds no workflow or step function, so the package's root entry, which the platform's
+ * backend bundles with another Workflow SDK major, may import it without bundling a step.
+ */
+/** The most tasks a workspace has live at once; one more is refused as `busy`. */
+export const MAX_LIVE_AGENT_TASKS = 10;
+/** The longest prompt, in characters. */
+export const MAX_AGENT_TASK_PROMPT_LENGTH = 32_768;
+/** The longest text the agent reports; it cuts longer text and sets `truncated`. */
+export const MAX_AGENT_TASK_TEXT_LENGTH = 65_536;
+/** How long a task may run, by default and at most: 15 minutes, 1 minute and 1 hour. */
+export const DEFAULT_AGENT_TASK_TIMEOUT_MS = 900_000;
+export const MIN_AGENT_TASK_TIMEOUT_MS = 60_000;
+export const MAX_AGENT_TASK_TIMEOUT_MS = 3_600_000;

package/dist/agent-task.d.ts

@@ -0,0 +1,39 @@
+import { type AgentTaskOptions, type AgentTaskResult } from "./agent-task-contract.js";
+export { DEFAULT_AGENT_TASK_TIMEOUT_MS, MAX_AGENT_TASK_PROMPT_LENGTH, MAX_AGENT_TASK_TEXT_LENGTH, MAX_AGENT_TASK_TIMEOUT_MS, MAX_LIVE_AGENT_TASKS, MIN_AGENT_TASK_TIMEOUT_MS, } from "./agent-task-contract.js";
+export type { AgentTaskFailure, AgentTaskOptions, AgentTaskResult, AgentTaskStart, AgentTaskStarted, } from "./agent-task-contract.js";
+/**
+ * `agentTask`: a workflow hands the workspace's agent a prompt and waits, durably, for its answer.
+ * The agent acts as the workflow's own user. This module is part of the `workflows` entry, which the
+ * Workflow SDK bundles for a runtime without Node built-ins: it imports none, and none of the SDK.
+ * Its two steps only call the ontology service through the process's workflow binding, so the
+ * Workflow SDK compiles them into the workspace's bundle without the service's code. Only the
+ * `workflows` entry may import this module: the service imports `agent-task-contract.ts`.
+ */
+/** `agentTask`'s options are invalid. Marked fatal, so that the Workflow SDK does not retry it. */
+export declare class AgentTaskOptionsInvalid extends Error {
+    readonly fatal = true;
+    constructor(option: string, problem: string);
+}
+/** `agentTask` was called outside a `"use workflow"` body. Marked fatal, as above. */
+export declare class AgentTaskWorkflowRequired extends Error {
+    readonly fatal = true;
+    constructor();
+}
+/** The options with the default timeout filled in; throws {@link AgentTaskOptionsInvalid}. */
+export declare function agentTaskOptions(options: AgentTaskOptions): Required<AgentTaskOptions>;
+/**
+ * Hands the workspace's agent a prompt, in a `"use workflow"` body, and waits for its final answer
+ * without holding compute. The agent runs as in chats, with the same instructions, models, tools and
+ * sandbox, acting as this workflow's user: it sees and does exactly what the workflow's role allows,
+ * and ontology actions run without confirmation. It resolves with:
+ *
+ * - `completed` and the agent's final text;
+ * - `needs_input` and its question, when it would need a person;
+ * - `failed` with `agent_unavailable` (no agent, an agent without tasks, or outside production),
+ *   `busy` (10 tasks are live) or `agent_failed` (its turn failed);
+ * - `timed_out` when `timeoutMs`, counted from the call, passes first.
+ *
+ * Invalid options, and a call outside a workflow body, fail the workflow. A retried start may hand
+ * the agent the same prompt again, so prompts and later steps tolerate a repeat.
+ */
+export declare function agentTask(options: AgentTaskOptions): Promise<AgentTaskResult>;

package/dist/agent-task.js

@@ -0,0 +1,112 @@
+import { DEFAULT_AGENT_TASK_TIMEOUT_MS, MAX_AGENT_TASK_PROMPT_LENGTH, MAX_AGENT_TASK_TIMEOUT_MS, MIN_AGENT_TASK_TIMEOUT_MS, } from "./agent-task-contract.js";
+import { boundStep } from "./workflow-runtime.js";
+export { DEFAULT_AGENT_TASK_TIMEOUT_MS, MAX_AGENT_TASK_PROMPT_LENGTH, MAX_AGENT_TASK_TEXT_LENGTH, MAX_AGENT_TASK_TIMEOUT_MS, MAX_LIVE_AGENT_TASKS, MIN_AGENT_TASK_TIMEOUT_MS, } from "./agent-task-contract.js";
+/**
+ * `agentTask`: a workflow hands the workspace's agent a prompt and waits, durably, for its answer.
+ * The agent acts as the workflow's own user. This module is part of the `workflows` entry, which the
+ * Workflow SDK bundles for a runtime without Node built-ins: it imports none, and none of the SDK.
+ * Its two steps only call the ontology service through the process's workflow binding, so the
+ * Workflow SDK compiles them into the workspace's bundle without the service's code. Only the
+ * `workflows` entry may import this module: the service imports `agent-task-contract.ts`.
+ */
+/** `agentTask`'s options are invalid. Marked fatal, so that the Workflow SDK does not retry it. */
+export class AgentTaskOptionsInvalid extends Error {
+    fatal = true;
+    constructor(option, problem) {
+        super(`agentTask: ${option} ${problem}`);
+        this.name = "AgentTaskOptionsInvalid";
+    }
+}
+/** `agentTask` was called outside a `"use workflow"` body. Marked fatal, as above. */
+export class AgentTaskWorkflowRequired extends Error {
+    fatal = true;
+    constructor() {
+        super('agentTask runs only in the "use workflow" body of a declared workflow: not inside a ' +
+            '"use step" function, and not outside a workflow.');
+        this.name = "AgentTaskWorkflowRequired";
+    }
+}
+/** The options with the default timeout filled in; throws {@link AgentTaskOptionsInvalid}. */
+export function agentTaskOptions(options) {
+    if (options === null || typeof options !== "object") {
+        throw new AgentTaskOptionsInvalid("options", "must be an object with a prompt.");
+    }
+    const { prompt, timeoutMs = DEFAULT_AGENT_TASK_TIMEOUT_MS } = options;
+    if (typeof prompt !== "string") {
+        throw new AgentTaskOptionsInvalid("prompt", "must be a string.");
+    }
+    if (prompt.length < 1 || prompt.length > MAX_AGENT_TASK_PROMPT_LENGTH) {
+        throw new AgentTaskOptionsInvalid("prompt", `must be 1 to ${MAX_AGENT_TASK_PROMPT_LENGTH} characters; it has ${prompt.length}.`);
+    }
+    if (typeof timeoutMs !== "number" ||
+        !Number.isInteger(timeoutMs) ||
+        timeoutMs < MIN_AGENT_TASK_TIMEOUT_MS ||
+        timeoutMs > MAX_AGENT_TASK_TIMEOUT_MS) {
+        throw new AgentTaskOptionsInvalid("timeoutMs", `must be a whole number of milliseconds from ${MIN_AGENT_TASK_TIMEOUT_MS} to ` +
+            `${MAX_AGENT_TASK_TIMEOUT_MS}; it is ${String(timeoutMs)}.`);
+    }
+    return { prompt, timeoutMs };
+}
+/**
+ * The Workflow SDK's `createHook` and `sleep` inside a `"use workflow"` body. The SDK's own
+ * exports read the same functions from these `globalThis` symbols, which its workflow sandbox sets
+ * and nothing else does; reading them here keeps the SDK out of this entry, which customer workflow
+ * files import at their top level. `undefined` in a step and outside a workflow.
+ */
+function workflowPrimitives() {
+    const globals = globalThis;
+    const createHook = globals[Symbol.for("WORKFLOW_CREATE_HOOK")];
+    const sleep = globals[Symbol.for("WORKFLOW_SLEEP")];
+    return typeof createHook === "function" && typeof sleep === "function"
+        ? { createHook: createHook, sleep: sleep }
+        : undefined;
+}
+/**
+ * Refuses when 10 tasks are live, records the task under the hook's token, and hands it to the
+ * agent. The task's secret never leaves the service: the step returns the task id only.
+ */
+async function startAgentTask(input) {
+    "use step";
+    const { binding, step } = boundStep();
+    return binding.startAgentTask(step, input);
+}
+/** The sleep won: the task times out unless it already ended, and its terminal outcome is returned. */
+async function expireAgentTask(taskId) {
+    "use step";
+    const { binding, step } = boundStep();
+    return binding.expireAgentTask(step, taskId);
+}
+/**
+ * Hands the workspace's agent a prompt, in a `"use workflow"` body, and waits for its final answer
+ * without holding compute. The agent runs as in chats, with the same instructions, models, tools and
+ * sandbox, acting as this workflow's user: it sees and does exactly what the workflow's role allows,
+ * and ontology actions run without confirmation. It resolves with:
+ *
+ * - `completed` and the agent's final text;
+ * - `needs_input` and its question, when it would need a person;
+ * - `failed` with `agent_unavailable` (no agent, an agent without tasks, or outside production),
+ *   `busy` (10 tasks are live) or `agent_failed` (its turn failed);
+ * - `timed_out` when `timeoutMs`, counted from the call, passes first.
+ *
+ * Invalid options, and a call outside a workflow body, fail the workflow. A retried start may hand
+ * the agent the same prompt again, so prompts and later steps tolerate a repeat.
+ */
+export async function agentTask(options) {
+    const { prompt, timeoutMs } = agentTaskOptions(options);
+    const primitives = workflowPrimitives();
+    if (primitives === undefined) {
+        throw new AgentTaskWorkflowRequired();
+    }
+    const hook = primitives.createHook();
+    const started = await startAgentTask({ hookToken: hook.token, prompt, timeoutMs });
+    if (started.status === "decided") {
+        return started.result;
+    }
+    // Sleep until the row's deadline, not `timeoutMs` from now: a report the ontology accepted
+    // before the deadline then always wins, and start-step retries count against the timeout.
+    const reported = await Promise.race([
+        hook,
+        primitives.sleep(Math.max(started.remainingMs, 1)).then(() => undefined),
+    ]);
+    return reported ?? (await expireAgentTask(started.taskId));
+}