@fastagent-sh/fastagent 0.25.0 → 0.26.0

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/tunnel.js

@@ -8,7 +8,8 @@ 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, webhookKinds } from "./deploy/channel-ingress.js";
-import { dotEnvPath, loadDotEnv } from "./env.js";
+import { loadDotEnv } from "./env.js";
+import { dotEnvPath } from "./value-file.js";
 import { installProxyFetch } from "./proxy.js";
 import { AGENT_ENVIRONMENT_ENV, resolveStateRoot } from "./paths.js";
 import { log } from "./log.js";

package/dist/value-file.d.ts

@@ -1,3 +1,22 @@
+/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
+export declare function parseEnvContent(content: string): Map<string, string>;
+/**
+ * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
+ * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
+ * file declares, and merging it into the running process would put the two environments in one bag. A missing file
+ * is no values, which is normal.
+ */
+export declare function loadEnvValues(file: string): Map<string, string>;
+/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+export declare function dotEnvPath(agentDir: string, env?: NodeJS.ProcessEnv): string;
+/** The committable template: `<agentDir>/.secrets/.env.example`. */
+export declare function envExamplePath(agentDir: string): string;
+/**
+ * What the agent's value file ({@link dotEnvPath}) adds to this process's environment, read and not entered: each
+ * variable the process does not hold, as entering the file would set it. An agent opened in a process that runs
+ * others too reads its own values through this; one that a command entered (`dev`, `start`) adds nothing here.
+ */
+export declare function agentValues(agentDir: string): Record<string, string>;
 /** One variable to write: with a `value`, an active line; without one, a placeholder under its `hint`. */
 export interface ValueEntry {
     name: string;

package/dist/value-file.js

@@ -1,13 +1,69 @@
 /**
- * Writing the selected environment's value file (`.secrets/.env`, or `.secrets/production/.env` for a deployment):
- * what a command generates (a channel's secret, the Agent API's key) goes in as an active `NAME=value` line, a value
- * already set stays, and the secrets directory fastagent made carries its own `.gitignore`.
+ * The selected environment's value file (`.secrets/.env`, or `.secrets/production/.env` for a deployment), read and
+ * written; entering it into `process.env` is env.ts's. Read as data: what it declares, and what it adds to an agent's
+ * environment. Written: what a command generates (a channel's secret, the Agent API's key) goes in as an active
+ * `NAME=value` line, a value already set stays, and the secrets directory fastagent made carries its own `.gitignore`.
  */
+import { readFileSync } from "node:fs";
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { dotEnvPath, parseEnvContent } from "./env.js";
-import { SECRETS_DIRNAME, SECRET_FILE_MODE, exists } from "./paths.js";
+import { SECRETS_DIRNAME, SECRET_FILE_MODE, exists, resolveSecretsDir } from "./paths.js";
 import { baseTemplate } from "./scaffold/templates.js";
+/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
+export function parseEnvContent(content) {
+    const parsed = new Map();
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq < 1)
+            continue; // no `=`, or an empty key
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.at(-1) === quote)
+            value = value.slice(1, -1);
+        parsed.set(key, value); // in-file: last occurrence wins (Map overwrite)
+    }
+    return parsed;
+}
+/**
+ * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
+ * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
+ * file declares, and merging it into the running process would put the two environments in one bag. A missing file
+ * is no values, which is normal.
+ */
+export function loadEnvValues(file) {
+    try {
+        return parseEnvContent(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return new Map();
+        throw error;
+    }
+}
+/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+export function dotEnvPath(agentDir, env = process.env) {
+    return join(resolveSecretsDir(agentDir, env), ".env");
+}
+/** The committable template: `<agentDir>/.secrets/.env.example`. */
+export function envExamplePath(agentDir) {
+    return join(agentDir, SECRETS_DIRNAME, ".env.example");
+}
+/**
+ * What the agent's value file ({@link dotEnvPath}) adds to this process's environment, read and not entered: each
+ * variable the process does not hold, as entering the file would set it. An agent opened in a process that runs
+ * others too reads its own values through this; one that a command entered (`dev`, `start`) adds nothing here.
+ */
+export function agentValues(agentDir) {
+    const values = {};
+    for (const [key, value] of loadEnvValues(dotEnvPath(agentDir)))
+        if (!(key in process.env))
+            values[key] = value;
+    return values;
+}
 /** What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track. */
 export function unprotectedSecretsNote(dir) {
     return (`${dir} (FASTAGENT_SECRETS_DIR) now holds a secret and has no .gitignore — that directory is yours, so ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on Telegram, Slack, Feishu, or behind any channel.",
   "keywords": [
     "agent",