@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/service.js

@@ -1,20 +1,19 @@
-/** The product, as one call: an agent directory becomes a live service. */
+/** The product, as one call: an opened agent becomes a live service, its channels, schedules and wake-ups. */
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
 import * as Scope from "effect/Scope";
-import { createControlPlane } from "./channels/control.js";
-import { createInvokeHandler } from "./channels/http.js";
+import { mountChannels } from "./channels/discover.js";
 import { text } from "./channels/respond.js";
-import { assertCorsOrigins, parseRouteKey, pathUnderPrefix, router } from "./channels/serve.js";
-import { loadChannels } from "./channels/discover.js";
-import { loadRoutines } from "./schedule/discover.js";
-import { createRoutineListHandler, createRunHandler } from "./schedule/run.js";
-import { createScheduler } from "./schedule/scheduler.js";
+import { parseRouteKey, router } from "./channels/router.js";
+import { serveHandler, totalFetch } from "./channels/serve.js";
+import { portCleanup } from "./effect-port.js";
+import { API_PREFIX } from "./http/contract.js";
+import { apiHandler, isApiPath } from "./http/server.js";
 import { log } from "./log.js";
-import { refuseBrokenDeclarations } from "./loader.js";
-import { gateSecrets } from "./secrets-gate.js";
+import { once } from "./once.js";
+import { createScheduler } from "./schedule/scheduler.js";
 /** Default wait for a channel's `closed` before reporting it stuck. */
 const CLOSE_DEADLINE_MS = 5_000;
 /** One deadline for all connections; a failed close must not hide a sibling that is still running. */
@@ -42,98 +41,23 @@ function closeWithin(runs, names, deadlineMs) {
 }
 /** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
 export const DEFAULT_HTTP_PORT = 8787;
-/**
- * Does this surface serve `POST /run`, given a routine to run? It FOLLOWS `invoke` unless `run` says otherwise (see
- * {@link HttpSurface.run}). ONE function because the assembly mounts the route and `preflightDeploy` names it; a
- * default spelled twice is a default that moves once.
- */
-export function shouldServeRun(http) {
-    return http?.run ?? http?.invoke !== false;
-}
-/**
- * What an anonymous caller of a port can do, worst first — the ONE wording the startup report and deploy's pre-flight
- * both print, each from its own facts (what mounted vs what will mount).
- */
-export function describeAnonymousSurface(open) {
-    return [
-        ...(open.invoke ? ["POST /invoke (run a turn with this agent's tools)"] : []),
-        ...(open.run ? ["POST /run (run any routine this agent declares; GET /routines lists them)"] : []),
-        ...(open.controlPrefix ? [`${open.controlPrefix}/* (read, steer or delete any session)`] : []),
-    ];
-}
-/**
- * The surface this deployment serves: the DATA plane (`POST /invoke`), `GET /health`, and the discovered channels.
- *
- * `/invoke` is the framework's interface, so it is served whatever channels a definition declares (unless
- * `http.invoke: false`). It is RESERVED for the same reason `/control/*` is: a channel taking that path would silently replace the one route every client,
- * every doc and the startup line all name. `/health` stays overridable — a probe is the deployment's to shape.
- */
-export async function routesFor(agentDir, agent, stateRoot, control, 
-/**
- * `http.invoke: false` withholds the data plane. Two callers, two reasons: the AgentCore adapter serves the
- * Runtime's `/invocations` contract instead, and an author sets it to leave the channels' signature checks as the
- * only way into a public port.
- *
- * `routines` mounts `POST /run` and `GET /routines` (per {@link shouldServeRun}). Passed in rather than loaded here
- * so the routes and the resident clock cannot disagree about which routines exist (`loadServingRoutines`).
- */
-options = {}) {
-    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
-        agent,
-        stateRoot,
-        control,
-    });
-    for (const c of collisions) {
-        log.warn(`[fastagent] channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
-    }
-    refuseBrokenDeclarations(failures);
-    if (collisions.length > 0) {
-        throw new Error(`${collisions.length} channel route collision(s) — two channels cannot serve one route`);
+/** Mount the channels and the health check. */
+export function routesFor(agent, stateRoot, channels) {
+    const { routes, longConnections, routeChannels } = mountChannels(channels, agent, stateRoot);
+    for (const key of Object.keys(routes)) {
+        if (isApiPath(parseRouteKey(key).path)) {
+            throw new Error(`route "${key}" is under ${API_PREFIX}, which the Agent API serves — move it`);
+        }
     }
-    /**
-     * Which channel key already serves this path for the method a built-in would answer — the CHANNEL's spelling, not
-     * ours. A channel may write the method-less `"/invoke"`, and an error naming `"POST /invoke"` sends its author
-     * grepping their own file for a string that is not in it.
-     */
-    const covered = (path, method) => Object.keys(routes).find((key) => {
-        const entry = parseRouteKey(key);
-        return entry.path === path && (entry.method === undefined || entry.method === method);
-    });
     let ready = longConnections.length === 0;
     const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
-    // AgentCore serves the data plane through the Runtime's own `/invocations` contract, so the adapter opts out — and
-    // with no `/invoke` of ours on that surface there is nothing to reserve, which is why the refusal is in here.
-    const unverified = { ...(covered("/health", "GET") ? {} : { "GET /health": health }) };
-    if (options.http?.invoke !== false)
-        unverified["POST /invoke"] = createInvokeHandler(agent);
-    // `POST /run` exists only where there is something to run, and `GET /routines` exactly where that route does:
-    // it is the catalogue OF that route, so listing names nobody can use would be a catalogue of nothing. Both ride
-    // this table for the reason the table exists: they authenticate nobody, so they inherit the JSON body gate, the
-    // cross-origin policy, the reserved path and the startup report's account of what is open.
-    if (shouldServeRun(options.http)) {
-        const routines = options.routines ?? [];
-        const run = createRunHandler({ agent, routines });
-        if (run)
-            unverified["POST /run"] = run;
-        const list = createRoutineListHandler({ routines });
-        if (list)
-            unverified["GET /routines"] = list;
-    }
-    // ONE rule over the whole table, so the next route we add is reserved by existing here rather than by someone
-    // remembering to write a second check for it. `/health` is exempt by construction: it is only in `ours` when no
-    // channel already serves it, because a probe is the deployment's to shape.
-    const taken = Object.keys(unverified).flatMap((key) => {
+    const probed = Object.keys(routes).some((key) => {
         const entry = parseRouteKey(key);
-        const channelKey = covered(entry.path, entry.method ?? "");
-        return channelKey === undefined ? [] : [{ channelKey, key }];
+        return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
     });
-    if (taken.length > 0) {
-        throw new Error(`channel route(s) ${taken.map((t) => `"${t.channelKey}"`).join(", ")} take a path this serve answers on ` +
-            `itself (${taken.map((t) => `"${t.key}"`).join(", ")}) — rename the channel route`);
-    }
     return {
-        unverified,
-        selfVerifying: routes,
+        // A probe is the deployment's to shape, so a channel may serve `/health` itself.
+        routes: probed ? routes : { ...routes, "GET /health": health },
         longConnections,
         routeChannels,
         setReady(value) {
@@ -141,78 +65,71 @@ options = {}) {
         },
     };
 }
-/** Refuse channel routes the control plane would swallow. */
-export function assertNoControlPlaneCollision(channelRoutes, plane) {
-    const collisions = Object.keys(channelRoutes).filter((key) => pathUnderPrefix(parseRouteKey(key).path, plane.prefix));
-    if (collisions.length > 0) {
-        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the session control plane — ` +
-            `rename the channel route or disable sessionControl in fastagent.config`);
-    }
-}
-export function mountSessionControl(routes, control) {
-    if (!control)
-        return { routes, mounts: [] };
-    const plane = createControlPlane(control);
-    assertNoControlPlaneCollision(routes, plane);
-    return { routes, mounts: [plane], controlPrefix: plane.prefix };
-}
-/**
- * Load the agent's `routines/`, gated.
- *
- * Separate from {@link startSchedules} because two things need the SAME list and one of them runs first: the
- * `POST /run` route is built with the routes (so a channel cannot take that path unnoticed), and the resident
- * clock starts later, inside the service's scope. Loading twice would let them disagree about which routines exist.
- */
-export async function loadServingRoutines(agentDir) {
-    // Thrown, not exited on: this runs inside an embedder's app as well as the CLI, and a library that calls
-    // process.exit takes a decision (degrade? retry? stop?) that belongs to its host.
-    const { routines, secrets, failures } = await loadRoutines(agentDir);
-    // The routines' half of the serving-path gate (the opener does the tools', loadChannels the
-    // channels'): a routine reads its env at IMPORT time, so an unset declared value has already
-    // produced a broken prompt — refusing here is the last point where that is a startup failure.
-    gateSecrets({ declared: secrets, failures });
-    refuseBrokenDeclarations(failures);
-    return routines;
-}
-/**
- * Start the clock over routines {@link loadServingRoutines} already gated — on every serve, routines or not: the
- * agent's own wake-ups are a default capability, and this is what fires them.
- */
-export function startSchedules(agent, stateRoot, routines, options = {}) {
-    const scheduler = Effect.runSync(createScheduler({ agent, stateRoot, routines, externalClock: options.externalClock }));
+/** Start the clock: the definition's schedules, and the wake-ups the agent sets for itself, on every serve. */
+export function startSchedules(agent, stateRoot, schedules, options = {}) {
+    const scheduler = Effect.runSync(createScheduler({
+        agent,
+        stateRoot,
+        schedules,
+        ...(options.localClock === false ? { localClock: false } : {}),
+    }));
     scheduler.start();
-    if (routines.length > 0) {
-        log.info(`[fastagent] routines: ${routines.map((r) => r.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
-    }
-    return { routines, stop: () => scheduler.stop() };
+    if (schedules.length > 0)
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
+    return scheduler;
 }
 /**
- * The assembly itself, over an already-opened directory: channels, the control plane, routines and long connections,
- * composed into one handler.
+ * A Service over `handler`: answered in process, or served on a server of its own. `endStreams` ends what would hold
+ * the server's close open (a Caller watching events), and `shutdown` stops the rest once the server has.
  */
-export async function mountAgentService(opened, options = {}) {
-    const { agentDir, workspace, stateRoot, sessionControl } = opened;
-    // Wrapped BEFORE anything consumes it: routes, the control plane and routines must all drive the same agent, so
-    // this is a hook rather than something a caller applies afterwards.
-    const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
+export function serviceOver(handler, ready, shutdown, endStreams = async () => { }) {
+    let listener;
+    let closing;
+    const fetch = totalFetch(handler);
+    return {
+        fetch,
+        listen(port, host) {
+            if (closing !== undefined)
+                return Promise.reject(new Error("the service is closed"));
+            if (listener !== undefined)
+                return Promise.reject(new Error("the service is already listening"));
+            const current = serveHandler(handler, { port, ...(host === undefined ? {} : { host }) });
+            listener = current;
+            return current.listening.catch(async (error) => {
+                // A bind that failed holds nothing once its scope is closed, so the service may listen again, elsewhere.
+                if (listener === current)
+                    listener = undefined;
+                await current.close();
+                throw error;
+            });
+        },
+        ready,
+        close() {
+            closing ??= (async () => {
+                // The server first, so nothing new reaches what stops after it; each step runs, and every failure is said.
+                const failures = [];
+                for (const step of [endStreams, () => listener?.close(), shutdown]) {
+                    await Promise.resolve()
+                        .then(step)
+                        .catch((error) => failures.push(error));
+                }
+                if (failures.length > 0) {
+                    throw failures.length === 1 ? failures[0] : new AggregateError(failures, "the service did not close cleanly");
+                }
+            })();
+            return closing;
+        },
+    };
+}
+/** The assembly itself: channels, schedules and long connections, composed into one handler. */
+export async function serveAgent(opened, options = {}) {
+    const { agent, agentDir, stateRoot, schedules } = opened;
     const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_DEADLINE_MS;
-    // The embedder's way in, checked like the config file's: `allowedOrigin` compares exact strings, so a stray
-    // trailing slash would refuse the front end with nothing naming the rule.
-    const corsOrigins = opened.http?.cors;
-    if (corsOrigins)
-        assertCorsOrigins(corsOrigins, "mountAgentService: http.cors");
-    // Loaded BEFORE the routes, because `POST /run` is one of them and the resident clock below must run over the
-    // same list — two loads would be two answers to "which routines exist".
-    const routines = await loadServingRoutines(agentDir);
-    const routed = await routesFor(agentDir, agent, stateRoot, sessionControl, { http: opened.http, routines });
-    const withControl = mountSessionControl(routed.selfVerifying, opened.publishControl ? sessionControl : undefined);
+    const routed = routesFor(agent, stateRoot, opened.channels);
     // Composed BEFORE anything starts.
-    const handler = router({
-        unverified: routed.unverified,
-        selfVerifying: withControl.routes,
-        mounts: withControl.mounts,
-        ...(corsOrigins ? { corsOrigins } : {}),
-    });
+    const channels = router(routed.routes);
+    const api = options.apiKeys?.length ? apiHandler(agent, { keys: options.apiKeys }) : undefined;
+    const handler = api === undefined ? channels : (req) => (isApiPath(new URL(req.url).pathname) ? api.fetch(req) : channels(req));
     return Effect.runPromise(Effect.gen(function* () {
         const lifetime = yield* Scope.make();
         const abort = new AbortController();
@@ -229,21 +146,21 @@ export async function mountAgentService(opened, options = {}) {
             routed.setReady(false);
             onClosed(name, error);
         };
-        // Scope.close alone does not join concurrent closes or retain their failure.
-        const shutdown = yield* Effect.cached(Effect.gen(function* () {
+        // Scope.close alone does not join concurrent closes or retain their failure. Every later call, the rollback a
+        // close itself triggers included, awaits the first one's outcome.
+        const shutdown = once(Effect.gen(function* () {
             abort.abort();
             yield* Scope.close(lifetime, Exit.void);
         }));
         const close = () => Effect.runPromise(shutdown);
         const rollback = shutdown.pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`[fastagent] cleanup after a failed start also failed: ${String(Cause.squash(cause))}`))));
-        const onAbort = () => {
-            void close().catch((error) => log.error(`[fastagent] service close failed: ${String(error)}`));
-        };
         return yield* Effect.gen(function* () {
+            if (api !== undefined)
+                yield* Effect.addFinalizer(() => portCleanup("closing the Agent API", api.dispose));
             // Registered first, so subscriptions and schedule timers stop before waiting for transports.
             yield* Effect.addFinalizer(() => closeWithin(runs, names, closeTimeoutMs).pipe(Effect.orDie));
-            const scheduled = yield* Effect.acquireRelease(Effect.try({
-                try: () => startSchedules(agent, stateRoot, routines),
+            yield* Effect.acquireRelease(Effect.try({
+                try: () => startSchedules(agent, stateRoot, schedules),
                 catch: (error) => error,
             }), (scheduled) => Effect.sync(scheduled.stop));
             const readiness = yield* Effect.forEach(routed.longConnections, (connection) => Effect.gen(function* () {
@@ -269,10 +186,6 @@ export async function mountAgentService(opened, options = {}) {
                         log.info(`[fastagent] long connection ready: ${connection.name}`);
                 })), Effect.forkScoped({ startImmediately: true }));
             }));
-            if (options.signal?.aborted)
-                yield* shutdown;
-            else
-                yield* Effect.acquireRelease(Effect.sync(() => options.signal?.addEventListener("abort", onAbort, { once: true })), () => Effect.sync(() => options.signal?.removeEventListener("abort", onAbort)));
             // The public readiness waiter lives outside the scope it may roll back.
             const ready = Effect.runPromise(Effect.gen(function* () {
                 yield* Effect.forEach(readiness, Fiber.join, { concurrency: "unbounded", discard: true });
@@ -287,21 +200,12 @@ export async function mountAgentService(opened, options = {}) {
             // The rejection is still delivered to callers that await ready.
             ready.catch(() => { });
             return {
-                handler,
-                agent,
-                routes: { ...routed.unverified, ...withControl.routes },
+                ...serviceOver(handler, ready, close, async () => api?.endStreams()),
+                routes: routed.routes,
                 agentDir,
-                workspace,
-                channels: {
-                    routes: routed.routeChannels,
-                    longConnections: names,
-                },
-                unverifiedRoutes: Object.keys(routed.unverified),
-                ...(corsOrigins ? { corsOrigins } : {}),
-                routines: scheduled.routines,
-                ready,
-                ...(withControl.controlPrefix ? { controlPrefix: withControl.controlPrefix } : {}),
-                close,
+                channels: { routes: routed.routeChannels, longConnections: names },
+                schedules,
+                api: api !== undefined,
             };
         }).pipe(Scope.provide(lifetime), Effect.onError(() => rollback));
     }));

package/dist/serving-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Which command serves this process: `dev` marks it, and everything else (`start`, a deployed box, an embedder) is
+ * the default. A channel file reads it at import through the agent's OWN installed copy of this package, which shares
+ * nothing with the CLI's copy but the process environment, so the mark lives there.
+ */
+export declare const DEV_SERVE_ENV = "FASTAGENT_DEV";
+export declare function markDevServe(env?: NodeJS.ProcessEnv): void;
+/** For a command that is never `dev` (`start`, `deploy`), run from a shell or a tool that a `dev` process spawned. */
+export declare function unmarkDevServe(env?: NodeJS.ProcessEnv): void;
+export declare function servedByDev(env?: NodeJS.ProcessEnv): boolean;

package/dist/serving-command.js

@@ -0,0 +1,16 @@
+/**
+ * Which command serves this process: `dev` marks it, and everything else (`start`, a deployed box, an embedder) is
+ * the default. A channel file reads it at import through the agent's OWN installed copy of this package, which shares
+ * nothing with the CLI's copy but the process environment, so the mark lives there.
+ */
+export const DEV_SERVE_ENV = "FASTAGENT_DEV";
+export function markDevServe(env = process.env) {
+    env[DEV_SERVE_ENV] = "1";
+}
+/** For a command that is never `dev` (`start`, `deploy`), run from a shell or a tool that a `dev` process spawned. */
+export function unmarkDevServe(env = process.env) {
+    delete env[DEV_SERVE_ENV];
+}
+export function servedByDev(env = process.env) {
+    return env[DEV_SERVE_ENV] === "1";
+}

package/dist/sign-in-api.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Model credentials and provider sign-in as an embedding host sees them: FastAgent's own types, so a host keeps the
+ * credentials where it chooses and runs a sign-in in its own UI without knowing the harness. Imports nothing; the
+ * functions over these types are in harnesses/models/host.ts.
+ */
+/** One provider's credential, kept by a {@link CredentialStore} whole, as it is given. */
+export type Credential = {
+    type: "api_key";
+    key?: string;
+    env?: Record<string, string>;
+} | {
+    type: "oauth";
+    access: string;
+    refresh: string;
+    expires: number;
+    [field: string]: unknown;
+};
+/**
+ * Where model credentials are kept, one per provider. `modify` is the only write, and it runs one at a time per
+ * provider (across processes, where the store can): an OAuth refresh happens inside it, and a rotated refresh token
+ * must never be used twice. A store it cannot read rejects; answering it as empty would let the next write replace
+ * every provider's credential.
+ */
+export interface CredentialStore {
+    /** The stored credential, possibly expired; undefined when the provider has none. */
+    read(provider: string): Promise<Credential | undefined>;
+    /** Which providers have a credential, and of what kind; never the secrets. */
+    list(): Promise<readonly {
+        provider: string;
+        type: Credential["type"];
+    }[]>;
+    /** `change` returns the new credential, or undefined to leave it as it is. Resolves with what is stored after. */
+    modify(provider: string, change: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
+    delete(provider: string): Promise<void>;
+}
+export type SignInMethod = Credential["type"];
+/** One way to sign in to one provider, with what authenticates the provider now. */
+export interface SignInOption {
+    provider: string;
+    /** The provider's name: "OpenAI", "OpenAI Codex (legacy)". */
+    name: string;
+    method: SignInMethod;
+    /** What signing in this way is called: the provider's own label ("Sign in with ChatGPT"), else a generic one. */
+    label: string;
+    /** An account sign-in backed by a provider subscription. */
+    subscription: boolean;
+    /** Its key comes from the environment only: there is no sign-in to run. */
+    external: boolean;
+    /**
+     * What authenticates the provider now: a stored credential (`OAuth`, `stored credential`), else the environment
+     * (a variable such as `OPENAI_API_KEY`). One credential is stored per provider, so signing in with the other method
+     * replaces a stored one.
+     */
+    status?: {
+        type: SignInMethod;
+        source: string;
+    };
+    /** What in the environment authenticates the provider with nothing stored: what still answers after a sign-out. */
+    environment?: string;
+    /**
+     * Why checking the environment for the provider failed: `environment` is then unknown, and so is `status` when
+     * nothing is stored.
+     */
+    problem?: string;
+}
+/** A question a sign-in asks. `manual_code`: the address the browser ended on after signing in, or the code its page showed. */
+export type SignInPrompt = {
+    signal?: AbortSignal;
+} & ({
+    type: "text" | "secret" | "manual_code";
+    message: string;
+    placeholder?: string;
+} | {
+    type: "select";
+    message: string;
+    options: readonly {
+        id: string;
+        label: string;
+        description?: string;
+    }[];
+});
+/** What a sign-in tells the person: a page to open, a code to enter there, progress. */
+export type SignInEvent = {
+    type: "info";
+    message: string;
+    links?: readonly {
+        url: string;
+        label?: string;
+    }[];
+} | {
+    type: "progress";
+    message: string;
+} | {
+    type: "auth_url";
+    url: string;
+    instructions?: string;
+} | {
+    type: "device_code";
+    userCode: string;
+    verificationUri: string;
+    intervalSeconds?: number;
+    expiresInSeconds?: number;
+};
+/**
+ * How a sign-in reaches the person. `prompt` resolves with the answer (a select's option `id`); it rejects with
+ * {@link SignInCancelled} when the person backs out, which ends the sign-in with that error, and with any other error
+ * when asking failed, which fails the sign-in with it. A prompt's `signal` aborts when the sign-in no longer needs the
+ * answer, such as a `manual_code` question a browser callback answered first.
+ */
+export interface SignInInteraction {
+    signal?: AbortSignal;
+    prompt(prompt: SignInPrompt): Promise<string>;
+    notify(event: SignInEvent): void;
+}
+export interface SignInRequest {
+    credentials: CredentialStore;
+    provider: string;
+    method: SignInMethod;
+    interaction: SignInInteraction;
+    /**
+     * A stable id of this installation, which Sign in with ChatGPT requires. `credentialFile` keeps one beside its
+     * file; a store of the host's own passes it here.
+     */
+    deviceId?: string;
+}
+export interface SignInResult {
+    provider: string;
+    method: SignInMethod;
+    /** An API key is checked with one request before it is stored: accepted, or not decidable (stored). */
+    verified: "ok" | "unknown" | "n/a";
+}
+/** What a request to a provider authenticates with. */
+export interface ProviderAuth {
+    type: SignInMethod;
+    /** Where it comes from: `OAuth`, `stored credential`, an environment variable's name. */
+    source?: string;
+    /** The key or access token a request sends. */
+    apiKey?: string;
+    /** Headers a request sends, where the provider authenticates by them (an `Authorization` of its own). */
+    headers?: Record<string, string>;
+    /** Where the request goes, where the credential decides it (an enterprise endpoint). */
+    baseUrl?: string;
+}
+/** The person backed out of a sign-in, or its signal aborted: a decision, not a failure. Nothing was stored. */
+export declare class SignInCancelled extends Error {
+    name: string;
+}

package/dist/sign-in-api.js

@@ -0,0 +1,9 @@
+/**
+ * Model credentials and provider sign-in as an embedding host sees them: FastAgent's own types, so a host keeps the
+ * credentials where it chooses and runs a sign-in in its own UI without knowing the harness. Imports nothing; the
+ * functions over these types are in harnesses/models/host.ts.
+ */
+/** The person backed out of a sign-in, or its signal aborted: a decision, not a failure. Nothing was stored. */
+export class SignInCancelled extends Error {
+    name = "SignInCancelled";
+}

package/dist/slack.d.ts

@@ -1,4 +1,4 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
 export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";
-export { slackTransport, type SlackTransport } from "./channels/slack/shared-api.ts";
+export { slackThreads, slackTransport, type SlackTransport } from "./channels/slack/shared-api.ts";
 export type { SentSlackMessage, SlackTarget, UploadedSlackFile } from "./channels/slack/slack-api.ts";

package/dist/slack.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
 export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";
-export { slackTransport } from "./channels/slack/shared-api.js";
+export { slackThreads, slackTransport } from "./channels/slack/shared-api.js";

package/dist/{channels/kit/state.js → state-file.js}

@@ -1,12 +1,12 @@
 /**
- * Durable channel state, with no cross-instance locking: every file here is keyed by CHANNEL KIND
- * (`<stateRoot>/channels/<kind>/`), so what must not happen is two processes serving the SAME channel — which also
- * means one ingress credential in two places, and no local guard can see that. Two processes serving different
- * channels of one agent never touch the same file (docs/design/core.md, "the shipped file-backed implementations").
+ * A Caller's durable state under the state root, with no cross-instance locking: a channel's files are in its own
+ * directory (`<stateRoot>/channels/<the channel file's name>/`) and the schedules' in `schedule/`, so what must not
+ * happen is two processes serving the SAME channel — which also means one ingress credential in two places, and no
+ * local guard can see that (docs/design/core.md §9).
  */
 import { mkdirSync, readFileSync } from "node:fs";
-import { writeFileAtomic } from "../../atomic-write.js";
-import { log } from "../../log.js";
+import { writeFileAtomic } from "./atomic-write.js";
+import { log } from "./log.js";
 /** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export function ensureStateHome(dir) {
     mkdirSync(dir, { recursive: true });

package/dist/telegram.d.ts

@@ -1,2 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
 export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, type TelegramChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";
+export { telegramTransport, type TelegramSendTarget, type TelegramSent, type TelegramTransport, } from "./channels/telegram/shared-api.ts";

package/dist/telegram.js

@@ -1,2 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
 export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, } from "./channels/telegram/telegram.js";
+export { telegramTransport, } from "./channels/telegram/shared-api.js";

package/dist/tunnel.d.ts

@@ -27,6 +27,9 @@ export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloud
 export declare function announceWebhooks(dir: string, baseUrl: string, channels: readonly DeclaredChannel[], opts?: {
     openUrl?: (url: string) => void;
     stateRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    /** {@link Registrars.leave}. */
+    leave?: (step: string) => void;
 }): Promise<{
     kind: string;
     outcome: RegistrationOutcome;

package/dist/tunnel.js

@@ -7,10 +7,11 @@ import { spawn } from "node:child_process";
 import { registerFeishuWebhook } from "./channels/feishu/register-webhook.js";
 import { registerSlackWebhook } from "./channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
-import { pointChannelsAt } from "./deploy/channel-ingress.js";
-import { dotEnvPath, loadDotEnv } from "./env.js";
+import { pointChannelsAt, webhookKinds } from "./deploy/channel-ingress.js";
+import { loadDotEnv } from "./env.js";
+import { dotEnvPath } from "./value-file.js";
 import { installProxyFetch } from "./proxy.js";
-import { resolveStateRoot } from "./paths.js";
+import { AGENT_ENVIRONMENT_ENV, resolveStateRoot } from "./paths.js";
 import { log } from "./log.js";
 // `(?!api\.)`: cloudflared's ERROR lines mention its request endpoint (`https://api.trycloudflare.com/tunnel`, e.g.
 // "failed to request quick Tunnel: Post ... timeout" under a flaky proxy) — without the exclusion a transient error
@@ -130,7 +131,8 @@ function lastErrorLine(tail) {
 export async function announceWebhooks(dir, baseUrl, channels, opts = {}) {
     log.info(`[fastagent] public URL: ${baseUrl}`);
     try {
-        loadDotEnv(dir); // webhook registrars read channel credentials from .env
+        if (!opts.env)
+            loadDotEnv(dir);
     }
     catch (error) {
         // best-effort boundary: an unreadable .env (a MISSING one is already tolerated) still leaves registrars that can
@@ -141,16 +143,23 @@ export async function announceWebhooks(dir, baseUrl, channels, opts = {}) {
     // Readiness is the registrar's job: a fresh quick tunnel returns Cloudflare 530 for ~20-30s before its origin
     // connects, and each registrar absorbs that by retrying the platform call whose own URL verification reports it.
     const feishuOptions = {
+        env: opts.env,
         onManualRegistration: ({ consoleUrl }) => opts.openUrl?.(consoleUrl),
     };
+    const moving = webhookKinds(channels);
+    if (moving.length > 0) {
+        log.info(`[fastagent] pointing the selected ${moving.join(", ")} app at ${baseUrl}; only this app's Request URL changes`);
+    }
     return pointChannelsAt({
         baseUrl,
         channels,
         log: (message) => log.info(`[fastagent] ${message}`),
         registrars: {
-            telegram: (url) => registerTelegramWebhook(url),
+            ...(opts.leave === undefined ? {} : { leave: opts.leave }),
+            telegram: (url) => registerTelegramWebhook(url, { env: opts.env }),
             slack: (url) => registerSlackWebhook(url, {
                 stateRoot: opts.stateRoot ?? resolveStateRoot(dir),
+                environment: process.env[AGENT_ENVIRONMENT_ENV] === "production" ? "production" : "dev",
                 log: (message) => log.info(message),
             }),
             feishu: (url, kind) => registerFeishuWebhook(url, kind, feishuOptions),