@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/http/contract.js

@@ -0,0 +1,179 @@
+/**
+ * The Agent API over HTTP (docs/SPEC.md §9) as one `effect/http-api` contract: the server answers from it,
+ * `connectAgent` calls through it and `/v1/openapi.json` is generated from it, so none of them can describe another API
+ * than the one served. Built from agent-api.ts's schemas; imports nothing that needs Node, so a client runs wherever
+ * `fetch` does.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, HttpApiSecurity, OpenApi, } from "effect/http-api";
+import { AgentError, AgentErrorData, AgentInfo, CompactOptions, CreateSessionOptions, Entry, EntriesOptions, IdempotencyKey, ListOptions, Message, MessageStreamEvent, SendRequest, Session, SessionChanges, SessionEvent, Usage, Wait, errorData, } from "../agent-api.js";
+export const API_PREFIX = "/v1";
+/** The status a refusal answers with (§7). */
+export function statusOf(error) {
+    const reason = error.details?.reason;
+    switch (error.code) {
+        case "invalid_request":
+            return reason === "too_large" ? 413 : 400;
+        case "unauthorized":
+            return 401;
+        case "not_found":
+            return 404;
+        case "busy":
+            return reason === "queue_full" ? 429 : reason === "capacity" ? 503 : 409;
+        case "missing_model":
+        case "missing_tool":
+            return 409;
+        case "unavailable":
+            return 503;
+        default:
+            return 500;
+    }
+}
+const isAgentError = Schema.declare((u) => u instanceof AgentError);
+/** A refusal's body, `{ error }`, as the `AgentError` it carries: what a client reads at any status. */
+export const Refusal = Schema.Struct({ error: AgentErrorData }).pipe(Schema.decodeTo(isAgentError, SchemaTransformation.transform({
+    decode: ({ error }) => new AgentError(error),
+    encode: (error) => ({ error: errorData(error) }),
+})));
+/**
+ * `{ error }` at `status`. Encoding takes only an error whose status this is, which is how the server's answer gets its
+ * status; decoding takes any code, since a later server may answer with one this client does not know (§7.1).
+ */
+function refusedWith(status) {
+    return Schema.Struct({ error: AgentErrorData }).pipe(Schema.decodeTo(isAgentError, SchemaTransformation.transformEffect({
+        decode: ({ error }) => Effect.succeed(new AgentError(error)),
+        encode: (error) => statusOf(error) === status
+            ? Effect.succeed({ error: errorData(error) })
+            : Effect.fail(new SchemaIssue.Forbidden({ message: `not answered with ${status}` }, error)),
+    })), HttpApiSchema.status(status));
+}
+const Refused = [400, 404, 409, 413, 429, 500, 503].map(refusedWith);
+export class Authorization extends HttpApiMiddleware.Service()("fastagent/Authorization", {
+    security: { bearer: HttpApiSecurity.bearer },
+    error: refusedWith(401),
+}) {
+}
+/** A request the contract cannot read (a path, query, header or body), refused `invalid_request`. */
+export class Malformed extends HttpApiMiddleware.Service()("fastagent/Malformed", {
+    error: refusedWith(400),
+}) {
+}
+const typesOf = (events) => new Set(events.members.map((member) => member.fields.type.literal));
+/** The event types this version defines; a Caller ignores any other (§7.1). */
+export const SESSION_EVENT_TYPES = typesOf(SessionEvent);
+export const MESSAGE_STREAM_EVENT_TYPES = typesOf(MessageStreamEvent);
+/** An event of a type a later server sends and this client does not know: its type, the rest unread. */
+const Unknown = Schema.Struct({ type: Schema.String });
+/**
+ * An event as server-sent: its type as the event's name, the event as its data, and an entry's id as its id, so that
+ * `Last-Event-ID` is the last entry a Caller received (§9.3).
+ */
+function serverSent(events, known) {
+    const json = Schema.fromJsonString(events);
+    return Schema.Struct({ id: Schema.optional(Schema.String), event: Schema.String, data: Schema.String }).pipe(Schema.decodeTo(Schema.Union([Schema.toType(events), Unknown]), SchemaTransformation.transformEffect({
+        decode: ({ event, data }) => known.has(event)
+            ? Schema.decodeUnknownEffect(json)(data).pipe(Effect.mapError((error) => error.issue))
+            : Effect.succeed({ type: event }),
+        encode: (value) => !known.has(value.type)
+            ? Effect.fail(new SchemaIssue.Forbidden({ message: `${value.type} is not an event this API sends` }))
+            : Schema.encodeEffect(json)(value).pipe(Effect.mapError((error) => error.issue), Effect.map((data) => ({
+                event: value.type,
+                data,
+                ...("entry" in value && value.type === "entry" ? { id: value.entry.id } : {}),
+            }))),
+    })));
+}
+export const SessionEventFrame = serverSent(SessionEvent, SESSION_EVENT_TYPES);
+export const MessageStreamEventFrame = serverSent(MessageStreamEvent, MESSAGE_STREAM_EVENT_TYPES);
+const sessionPath = { sessionId: Schema.String };
+const Page = (item) => Schema.Struct({
+    data: Schema.Array(item),
+    next: Schema.optionalKey(Schema.String),
+    prev: Schema.optionalKey(Schema.String),
+});
+const { sessionId: _, ...sendFields } = SendRequest.fields;
+const { idempotencyKey: __, ...sendBody } = sendFields;
+/** `POST …/messages`: the send without its session (the path's) or its key (`Idempotency-Key`). */
+const SendBody = Schema.Struct({
+    ...sendBody,
+    wait: Schema.optional(Wait),
+    /** `messages.stream`: the answer is the message's events. */
+    stream: Schema.optional(Schema.Boolean),
+});
+/**
+ * A key as a header carries it: percent-encoded, as in the `by-key` path, since a header holds only Latin-1 and loses
+ * the spaces around a value, while a key may be any 1 to 256 characters (§9.2).
+ */
+const KeyHeader = Schema.String.pipe(Schema.decodeTo(IdempotencyKey, SchemaTransformation.stringFromUriComponent));
+const WaitQuery = { wait: Schema.optional(Schema.NumberFromString.check(Schema.isGreaterThanOrEqualTo(0))) };
+const AgentGroup = HttpApiGroup.make("agent")
+    .add(HttpApiEndpoint.get("info", "/agent", { success: AgentInfo, error: Refused }), HttpApiEndpoint.get("usage", "/usage", { success: Usage, error: Refused }), HttpApiEndpoint.get("openapi", "/openapi.json", { success: Schema.Json, error: Refused }), HttpApiEndpoint.post("createSession", "/sessions", {
+    // Its options may be left out, as in process (§4): a request without a body is one without them, which the
+    // contract reads as `null` only when a payload schema is `null` itself.
+    payload: [CreateSessionOptions, Schema.Null],
+    success: Session.pipe(HttpApiSchema.status(201)),
+    error: Refused,
+}), HttpApiEndpoint.get("listSessions", "/sessions", {
+    query: ListOptions,
+    success: Page(Session),
+    error: Refused,
+}), HttpApiEndpoint.get("getSession", "/sessions/:sessionId", {
+    params: sessionPath,
+    success: Session,
+    error: Refused,
+}), HttpApiEndpoint.patch("updateSession", "/sessions/:sessionId", {
+    params: sessionPath,
+    payload: SessionChanges,
+    success: Session,
+    error: Refused,
+}), HttpApiEndpoint.get("entries", "/sessions/:sessionId/entries", {
+    params: sessionPath,
+    query: EntriesOptions,
+    success: Page(Entry),
+    error: Refused,
+}), HttpApiEndpoint.get("events", "/sessions/:sessionId/events", {
+    params: sessionPath,
+    query: { after: Schema.optional(Schema.String) },
+    headers: { "last-event-id": Schema.optional(Schema.String) },
+    success: HttpApiSchema.StreamSse({ events: SessionEventFrame }),
+    error: Refused,
+}), HttpApiEndpoint.post("cancel", "/sessions/:sessionId/cancel", {
+    params: sessionPath,
+    success: Schema.Struct({ stopped: Schema.Array(Schema.String) }),
+    error: Refused,
+}), HttpApiEndpoint.post("compact", "/sessions/:sessionId/compact", {
+    params: sessionPath,
+    payload: [CompactOptions, Schema.Null],
+    success: HttpApiSchema.Accepted,
+    error: Refused,
+}), HttpApiEndpoint.get("attachment", "/sessions/:sessionId/attachments/:ref", {
+    params: { ...sessionPath, ref: Schema.String },
+    success: Schema.Uint8Array.pipe(HttpApiSchema.asUint8Array({ contentType: "image/*" })),
+    error: Refused,
+}), HttpApiEndpoint.post("send", "/sessions/:sessionId/messages", {
+    params: sessionPath,
+    headers: { "idempotency-key": Schema.optional(KeyHeader) },
+    payload: SendBody,
+    success: [Message, HttpApiSchema.StreamSse({ events: MessageStreamEventFrame })],
+    error: Refused,
+}), HttpApiEndpoint.get("getMessage", "/sessions/:sessionId/messages/:messageId", {
+    params: { ...sessionPath, messageId: Schema.String },
+    query: WaitQuery,
+    success: Message,
+    error: Refused,
+}), HttpApiEndpoint.get("getMessageByKey", "/sessions/:sessionId/messages/by-key/:idempotencyKey", {
+    params: { ...sessionPath, idempotencyKey: IdempotencyKey },
+    query: WaitQuery,
+    success: Message,
+    error: Refused,
+}))
+    .middleware(Malformed)
+    .middleware(Authorization)
+    .prefix(API_PREFIX);
+export class AgentHttpApi extends HttpApi.make("fastagent")
+    .add(AgentGroup)
+    .annotateMerge(OpenApi.annotations({ title: "FastAgent Agent API", version: "2" })) {
+}

package/dist/http/server.d.ts

@@ -0,0 +1,34 @@
+import { type Agent } from "../agent-api.ts";
+import type { ChannelHandler } from "../channel.ts";
+/** The instance's keys: several, separated by commas, so a key is replaced without a gap (§9.1). */
+export declare const API_KEY_VARIABLE = "FASTAGENT_API_KEY";
+/**
+ * Whether the definition turns the Agent API off (`http.api: false`): the one reading of it, which every serve the CLI
+ * runs and `deploy` make, so a key a host still holds cannot serve an API the definition turned off.
+ */
+export declare function apiTurnedOff(config: {
+    http?: {
+        api?: boolean;
+    };
+}): boolean;
+export declare const API_TURNED_OFF = "fastagent.config.ts says http.api: false";
+export declare function apiKeysFrom(value: string | undefined): string[];
+export interface ApiHandler {
+    fetch: ChannelHandler;
+    /**
+     * Ends every open event stream with a `stream_error`, and answers once they have ended, so that the server's close
+     * does not wait on a Caller still watching: at most {@link STREAMS_END_MS}, past which one whose Caller stopped reading
+     * is left to the server's own grace.
+     */
+    endStreams(): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface ApiOptions {
+    keys: readonly string[];
+    /** For tests: the longest a request waits, and how often a quiet stream says it is open. */
+    waitCapSeconds?: number;
+    keepAliveMs?: number;
+}
+export declare function apiHandler(agent: Agent, options: ApiOptions): ApiHandler;
+/** Whether `path` is the Agent API's, which a channel's route may not take. */
+export declare function isApiPath(path: string): boolean;

package/dist/http/server.js

@@ -0,0 +1,194 @@
+/**
+ * The Agent API served over HTTP (SPEC.md §9): the contract's routes answered by an in-process Agent, behind the
+ * instance's keys. A Fetch handler, so it mounts beside the channels' routes on whatever server serves them.
+ */
+import * as ByteSize from "effect/ByteSize";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as Sse from "effect/encoding/Sse";
+import { HttpIncomingMessage, HttpRouter, HttpServer, HttpServerError, HttpServerResponse } from "effect/http";
+import { HttpApiBuilder, HttpApiError, OpenApi } from "effect/http-api";
+import { AgentError, LIMITS, agentError, errorData } from "../agent-api.js";
+import { secretEquals } from "../channels/secret.js";
+import { PortFailure, port, portAbort } from "../effect-port.js";
+import { log } from "../log.js";
+import { API_PREFIX, AgentHttpApi, Authorization, Malformed, MessageStreamEventFrame, SessionEventFrame, } from "./contract.js";
+/** The instance's keys: several, separated by commas, so a key is replaced without a gap (§9.1). */
+export const API_KEY_VARIABLE = "FASTAGENT_API_KEY";
+/**
+ * Whether the definition turns the Agent API off (`http.api: false`): the one reading of it, which every serve the CLI
+ * runs and `deploy` make, so a key a host still holds cannot serve an API the definition turned off.
+ */
+export function apiTurnedOff(config) {
+    return config.http?.api === false;
+}
+export const API_TURNED_OFF = "fastagent.config.ts says http.api: false";
+export function apiKeysFrom(value) {
+    return (value ?? "")
+        .split(",")
+        .map((key) => key.trim())
+        .filter((key) => key !== "");
+}
+const MAX_BODY = ByteSize.mebibytes(32);
+/** Proxies close a connection that says nothing for a minute or so; a comment keeps an event stream open (§9.3). */
+const KEEP_ALIVE_MS = 15_000;
+/** A stream told to end does in a millisecond; this bounds the wait for one whose Caller stopped reading. */
+const STREAMS_END_MS = 100;
+/** How soon a refused Caller may try again; the same for every refusal that says so (§9.4). */
+const RETRY_AFTER_SECONDS = "1";
+/** An operation's failure as the Agent API answers it: an `AgentError` as it is, anything else `internal`, logged. */
+function refusal(operation) {
+    return (failure) => {
+        const error = failure.cause;
+        if (error instanceof AgentError)
+            return error;
+        log.error(`[api] ${operation} failed: ${String(error)}`);
+        return agentError("internal", `${operation} failed: ${error instanceof Error ? error.message : String(error)}`);
+    };
+}
+/** An Agent operation, told to let go if its request does (a Caller that left). */
+function call(operation, run) {
+    return Effect.suspend(() => {
+        const controller = new AbortController();
+        return portAbort(operation, () => run(controller.signal), () => controller.abort());
+    }).pipe(Effect.mapError(refusal(operation)));
+}
+const json = (status, error) => HttpServerResponse.jsonUnsafe({ error: errorData(error) }, { status });
+/**
+ * What the contract cannot say itself: a body over the limit, a body that is not JSON (which the contract answers 415
+ * with a line of text) and a route it does not have, answered as refusals like any other, and `Retry-After` on every
+ * refusal a Caller may send again later.
+ */
+const Edges = HttpRouter.middleware((app) => app.pipe(Effect.catchCause((cause) => {
+    const error = Cause.squash(cause);
+    if (HttpServerError.isHttpServerError(error)) {
+        if (error.reason._tag === "RouteNotFound") {
+            return Effect.succeed(json(404, agentError("not_found", "the Agent API has no such route")));
+        }
+        if (error.reason._tag === "RequestParseError" && error.reason.reason === "BodyTooLarge") {
+            return Effect.succeed(json(413, agentError("invalid_request", "the request body is over 32 MiB", { reason: "too_large" })));
+        }
+    }
+    return Effect.failCause(cause);
+}), Effect.map((response) => {
+    if (response.status === 415) {
+        return json(400, agentError("invalid_request", "a request body is JSON: send Content-Type: application/json"));
+    }
+    return response.status === 429 || response.status === 503
+        ? HttpServerResponse.setHeader(response, "retry-after", RETRY_AFTER_SECONDS)
+        : response;
+})), { global: true });
+export function apiHandler(agent, options) {
+    // An empty key matches nothing (secretEquals), so serving with one would refuse every Caller without a word.
+    if (options.keys.length === 0 || options.keys.some((key) => key.trim() === "")) {
+        throw new Error("the Agent API needs at least one key, and no key may be empty");
+    }
+    const keys = [...options.keys];
+    const waitCap = options.waitCapSeconds ?? LIMITS.httpWaitSeconds;
+    const keepAlive = options.keepAliveMs ?? KEEP_ALIVE_MS;
+    const capped = (wait) => (wait === undefined ? undefined : Math.min(wait, waitCap));
+    const closing = new AbortController();
+    /** The event streams being written, each until it has ended. */
+    const streaming = new Set();
+    const closed = Effect.callback((resume) => {
+        if (closing.signal.aborted)
+            return resume(Effect.void);
+        const onAbort = () => resume(Effect.void);
+        closing.signal.addEventListener("abort", onAbort, { once: true });
+        return Effect.sync(() => closing.signal.removeEventListener("abort", onAbort));
+    });
+    /**
+     * An event stream: refused on its first read with that read's error and status, as `sessions.events` and
+     * `messages.stream` are; then its events as server-sent, with a comment while it is quiet. A service that closes
+     * ends it with `stream_error`.
+     */
+    const serverSent = (operation, frame, open) => Effect.gen(function* () {
+        const iterator = open()[Symbol.asyncIterator]();
+        const first = yield* port(() => iterator.next()).pipe(Effect.onInterrupt(() => Effect.promise(async () => iterator.return?.())), Effect.mapError(refusal(operation)));
+        const rest = Stream.fromAsyncIterable({ [Symbol.asyncIterator]: () => iterator }, (error) => error);
+        const written = (event) => Schema.encodeEffect(frame)(event).pipe(Effect.map(({ id, event, data }) => Sse.encoder.write({ _tag: "Event", id, event, data })));
+        const endedWith = (error) => Stream.fromEffect(Effect.orDie(written({ type: "stream_error", error: errorData(error) })));
+        const events = (first.done ? Stream.empty : Stream.concat(Stream.make(first.value), rest)).pipe(
+        // Written before a failure is caught, so an event the API cannot send ends the stream as what it is.
+        Stream.mapEffect(written), Stream.catchCause((cause) => endedWith(refusal(operation)(new PortFailure(Cause.squash(cause))))), Stream.interruptWhen(closed), Stream.concat(Stream.suspend(() => closing.signal.aborted ? endedWith(agentError("unavailable", "the service is closing")) : Stream.empty)));
+        let ended;
+        const done = new Promise((resolve) => {
+            ended = resolve;
+        });
+        const body = Stream.merge(events, Stream.tick(`${keepAlive} millis`).pipe(Stream.map(() => ": open\n\n")), {
+            haltStrategy: "left",
+        }).pipe(Stream.encodeText, Stream.onStart(Effect.sync(() => streaming.add(done))), Stream.ensuring(Effect.sync(() => {
+            streaming.delete(done);
+            ended();
+        })));
+        return HttpServerResponse.stream(body, {
+            contentType: "text/event-stream",
+            headers: { "cache-control": "no-store" },
+        });
+    });
+    const openapi = OpenApi.fromApi(AgentHttpApi);
+    const handlers = HttpApiBuilder.group(AgentHttpApi, "agent", (handlers) => handlers
+        .handle("info", () => call("info", () => agent.info()))
+        .handle("usage", () => call("usage", () => agent.usage()))
+        .handle("openapi", () => Effect.succeed(HttpServerResponse.jsonUnsafe(openapi)))
+        .handle("createSession", ({ payload }) => call("sessions.create", () => agent.sessions.create(payload ?? undefined)))
+        .handle("listSessions", ({ query }) => call("sessions.list", () => agent.sessions.list(query)))
+        .handle("getSession", ({ params }) => call("sessions.get", () => agent.sessions.get(params.sessionId)))
+        .handle("updateSession", ({ params, payload }) => call("sessions.update", () => agent.sessions.update(params.sessionId, payload)))
+        .handle("entries", ({ params, query }) => call("sessions.entries", () => agent.sessions.entries(params.sessionId, query)))
+        .handle("events", ({ params, query, headers }) => serverSent("sessions.events", SessionEventFrame, () => 
+    // An EventSource reconnects to the URL it opened and says where it got to in this header (§9.3).
+    agent.sessions.events(params.sessionId, { after: headers["last-event-id"] ?? query.after })))
+        .handle("cancel", ({ params }) => call("sessions.cancel", () => agent.sessions.cancel(params.sessionId)))
+        .handle("compact", ({ params, payload }) => call("sessions.compact", () => agent.sessions.compact(params.sessionId, payload ?? undefined)))
+        .handle("attachment", ({ params }) => call("sessions.attachment", () => agent.sessions.attachment(params.sessionId, params.ref)).pipe(Effect.map(({ mimeType, data }) => HttpServerResponse.uint8Array(data, { contentType: mimeType }))))
+        .handle("send", ({ params, headers, payload }) => {
+        const { wait, stream, ...message } = payload;
+        const request = { ...message, sessionId: params.sessionId, idempotencyKey: headers["idempotency-key"] };
+        if (!stream) {
+            return call("messages.send", (signal) => agent.messages.send(request, { wait: capped(wait), signal }));
+        }
+        if (wait !== undefined) {
+            return Effect.fail(agentError("invalid_request", "a streamed message is watched, not waited for: drop wait"));
+        }
+        return serverSent("messages.stream", MessageStreamEventFrame, () => agent.messages.stream(request));
+    })
+        .handle("getMessage", ({ params, query }) => call("messages.get", (signal) => agent.messages.get(params, { wait: capped(query.wait), signal })))
+        .handle("getMessageByKey", ({ params, query }) => call("messages.get", (signal) => agent.messages.get(params, { wait: capped(query.wait), signal }))));
+    const authorization = Layer.succeed(Authorization)({
+        bearer: (effect, { credential }) => {
+            const given = Redacted.value(credential);
+            return keys.some((key) => secretEquals(given, key))
+                ? effect
+                : Effect.fail(agentError("unauthorized", "the request has no key this instance holds"));
+        },
+    });
+    // The middleware wraps the whole handler, so it also sees the answer failing to encode: the server's fault, not the
+    // Caller's, said in the log and answered `internal`, as Effect itself tells the two apart.
+    const malformed = Layer.succeed(Malformed)((effect) => Effect.catchIf(effect, HttpApiError.HttpApiSchemaError.is, (error) => {
+        // The middleware's own error type hides what it is; the guard above said.
+        const { kind, cause } = error;
+        if (kind !== "Body" && kind !== "ResponseHeaders") {
+            return Effect.fail(agentError("invalid_request", `${kind}: ${cause.message}`));
+        }
+        log.error(`[api] an answer did not match the Agent API: ${cause.message}`);
+        return Effect.fail(agentError("internal", `the agent's answer did not match the Agent API: ${cause.message}`));
+    }));
+    const { handler, dispose } = HttpRouter.toWebHandler(Layer.mergeAll(HttpApiBuilder.layer(AgentHttpApi), Edges).pipe(Layer.provide(handlers), Layer.provide([authorization, malformed]), Layer.provide(HttpServer.layerServices), Layer.provide(Layer.succeed(HttpIncomingMessage.MaxBodySize)(MAX_BODY))), { disableLogger: true });
+    return {
+        fetch: (request) => handler(request),
+        endStreams: async () => {
+            closing.abort();
+            await Promise.race([Promise.all(streaming), new Promise((resolve) => setTimeout(resolve, STREAMS_END_MS))]);
+        },
+        dispose,
+    };
+}
+/** Whether `path` is the Agent API's, which a channel's route may not take. */
+export function isApiPath(path) {
+    return path === API_PREFIX || path.startsWith(`${API_PREFIX}/`);
+}

package/dist/index.d.ts

@@ -1,4 +1,17 @@
-export * from "./core.ts";
-export * from "./node.ts";
-export * from "./session.ts";
-export * from "./pi.ts";
+/**
+ * The package's one entry (SPEC.md §8), besides each first-party channel's: the Agent API, opening an agent
+ * directory and serving it, and what an author writes.
+ */
+export type { Agent, AgentErrorData, AgentInfo, CompactOptions, ContentPart, CreateSessionOptions, EntriesOptions, Entry, ErrorCode, Json, ListOptions, Message, MessageKey, MessageStatus, MessageStreamEvent, ModelRef, Page, SendRequest, Session, SessionChanges, SessionEvent, SessionSettings, SessionStatus, ThinkingLevel, Tokens, Usage, WaitOptions, } from "./agent-api.ts";
+export { AgentError, LIMITS, hasEnded } from "./agent-api.ts";
+export { openAgent, type LocalAgent, type OpenAgentOptions, type ServeAgentOptions, } from "./harnesses/pi-durable/serve.ts";
+export type { Service } from "./service.ts";
+/** What `openAgent`'s `credentials` takes: where provider credentials are kept, pi-ai's. */
+export type { CredentialStore } from "@earendil-works/pi-ai";
+export { defineAgent, defineSchedule, needs, type AgentConfig, type Needs, type SecretSpec, type SecretValues, } from "./harnesses/pi-durable/define.ts";
+export type { ScheduleConfig } from "./schedule/schedule.ts";
+export { defineChannel, type ChannelContext, type ChannelHandler, type ChannelModule, type ForkSource, type LongConnection, type LongConnectionChannelModule, type Routes, } from "./channel.ts";
+export { readBodyCapped } from "./channels/body.ts";
+export { text } from "./channels/respond.ts";
+export { secretEquals } from "./channels/secret.ts";
+export { sessionIdOf } from "./harnesses/pi-durable/ids.ts";

package/dist/index.js

@@ -1,5 +1,10 @@
-// Convenience entry: the engine-neutral core plus the pi reference implementation.
-export * from "./core.js";
-export * from "./node.js";
-export * from "./session.js";
-export * from "./pi.js";
+export { AgentError, LIMITS, hasEnded } from "./agent-api.js";
+export { openAgent, } from "./harnesses/pi-durable/serve.js";
+export { defineAgent, defineSchedule, needs, } from "./harnesses/pi-durable/define.js";
+export { defineChannel, } from "./channel.js";
+// What a channel reads a request with, answers with, and compares its platform's secret with (constant time).
+export { readBodyCapped } from "./channels/body.js";
+export { text } from "./channels/respond.js";
+export { secretEquals } from "./channels/secret.js";
+// The session a tool runs in, as the Agent hands it out: what a channel's thread-reading tool asks with.
+export { sessionIdOf } from "./harnesses/pi-durable/ids.js";

package/dist/lark.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical Feishu engine. */
-export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkWebSocketChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";
-export { larkTransport, type FeishuTransport as LarkTransport } from "./channels/feishu/shared-api.ts";
+export { larkChannel, larkIngress, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkWebSocketChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";
+export { larkThreads, larkTransport, type FeishuTransport as LarkTransport } from "./channels/feishu/shared-api.ts";

package/dist/lark.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical Feishu engine. */
-export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";
-export { larkTransport } from "./channels/feishu/shared-api.js";
+export { larkChannel, larkIngress, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";
+export { larkThreads, larkTransport } from "./channels/feishu/shared-api.js";

package/dist/locked-file.d.ts

@@ -0,0 +1,17 @@
+export interface LockResult<T> {
+    result: T;
+    /** New file content to persist under the lock; undefined = no write. */
+    next?: string;
+}
+/** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
+export declare function withLockedFile<T>(path: string, fn: (current: string | undefined) => Promise<LockResult<T>>, 
+/**
+ * `mode`: the replaced file's permissions; default {@link SECRET_FILE_MODE}, for the credential and catalog files.
+ * `create: false` locks a file that may not exist without creating it (the lock is `<file>.lock` either way), for a
+ * lock that guards more than the file it is named after.
+ */
+options?: {
+    signal?: AbortSignal;
+    mode?: number;
+    create?: boolean;
+}): Promise<T>;

package/dist/{engines/pi/locked-file.js → locked-file.js}

@@ -1,15 +1,15 @@
 /**
- * The one cross-process read-modify-write for a JSON file several processes share: fastagent's credentials file and a
- * model catalog. It takes the lock pi takes for the same files (pi-coding-agent's `FileAuthStorageBackend`), so a
- * fastagent writer and a pi writer queue behind each other, and it REPLACES the file rather than rewriting it in
- * place, which is what lets every reader of these files read without the lock: a reader sees the old file or the new
- * one, never one cut short.
+ * The one cross-process read-modify-write for a file several processes share: fastagent's credentials file, and
+ * `context.json` when an agent's content or environment is edited (`fastagent content` and `fastagent env` at once). It
+ * takes the lock pi takes for the same files (pi-coding-agent's `FileAuthStorageBackend`), so a fastagent writer and a
+ * pi writer queue behind each other, and it REPLACES the file rather than rewriting it in place, which is what lets
+ * every reader of these files read without the lock: a reader sees the old file or the new one, never one cut short.
  */
 import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import lockfile from "proper-lockfile";
-import { writeFileAtomic } from "../../atomic-write.js";
-import { SECRET_FILE_MODE } from "../../paths.js";
+import { writeFileAtomic } from "./atomic-write.js";
+import { SECRET_FILE_MODE } from "./paths.js";
 const WRITE_OPTIONS = { encoding: "utf8", mode: SECRET_FILE_MODE };
 /**
  * The file a write must land IN, which is not always the path it is addressed BY. pi writes these files in place,
@@ -27,9 +27,15 @@ function writeTarget(path) {
     return link?.isSymbolicLink() ? resolve(dirname(path), readlinkSync(path)) : path;
 }
 /** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
-export async function withLockedFile(path, fn, options = {}) {
+export async function withLockedFile(path, fn, 
+/**
+ * `mode`: the replaced file's permissions; default {@link SECRET_FILE_MODE}, for the credential and catalog files.
+ * `create: false` locks a file that may not exist without creating it (the lock is `<file>.lock` either way), for a
+ * lock that guards more than the file it is named after.
+ */
+options = {}) {
     mkdirSync(dirname(path), { recursive: true });
-    if (!existsSync(path)) {
+    if (options.create !== false && !existsSync(path)) {
         try {
             // `wx` makes this an exclusive CREATE, which is the one case `writeFileSync` honours `mode` in — so no chmod
             // after it (unlike writeFileAtomic, whose temp may already exist from a crashed writer).
@@ -73,7 +79,7 @@ export async function withLockedFile(path, fn, options = {}) {
         // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only spelling that applies
         // the mode before the content is reachable.
         if (out.next !== undefined) {
-            writeFileAtomic(writeTarget(path), out.next, SECRET_FILE_MODE);
+            writeFileAtomic(writeTarget(path), out.next, options.mode ?? SECRET_FILE_MODE);
         }
         throwIfCompromised();
         result = out.result;

package/dist/once.d.ts

@@ -0,0 +1,6 @@
+import * as Effect from "effect/Effect";
+/**
+ * The first call runs `work` to the end, uninterruptibly; every call, the first included, then reads its one outcome.
+ * A call made while the work is running, including one the work itself causes, waits for it.
+ */
+export declare function once<A, E, R>(work: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;

package/dist/once.js

@@ -0,0 +1,23 @@
+/**
+ * Work that runs at most once per process, whose outcome every caller shares, success or failure.
+ *
+ * `Effect.cached` is not that in effect 4.0.x: it interrupts a run once every caller has left it, and a run that
+ * finishes anyway (uninterruptible) is not cached, so the next caller starts the work a second time; and a call made
+ * while its run is still starting joins a fiber that is not assigned yet and dies.
+ */
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+/**
+ * The first call runs `work` to the end, uninterruptibly; every call, the first included, then reads its one outcome.
+ * A call made while the work is running, including one the work itself causes, waits for it.
+ */
+export function once(work) {
+    const outcome = Deferred.makeUnsafe();
+    let started = false;
+    return Effect.suspend(() => {
+        if (started)
+            return Deferred.await(outcome);
+        started = true;
+        return work.pipe(Effect.exit, Effect.flatMap((exit) => Deferred.done(outcome, exit)), Effect.uninterruptible, Effect.andThen(Deferred.await(outcome)));
+    });
+}