@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/content/resolve.d.ts

@@ -0,0 +1,52 @@
+import { type BoundContent, type ContentDeclaration, type DeclaredContent } from "./declare.ts";
+import { type CloneOutcome } from "./git.ts";
+/** A content entry, resolved for this instance. */
+export type ResolvedContent = {
+    /** Unique within the agent, ignoring case; one path segment. */
+    name: string;
+    /** The agent knows it and does not write it. */
+    readonly: boolean;
+    /** What the declaration tells the agent about it. */
+    description?: string;
+    /** Where the agent reaches it on this instance, absolute. */
+    location: string;
+    /** What to tell the user about how it resolved: a checkout off its `ref`, a clone not made yet. */
+    notices: string[];
+} & ({
+    /** A directory only this machine has, bound in `context.local.json`. */
+    kind: "local";
+} | {
+    kind: "github";
+    /** `owner/repo`. */
+    repo: string;
+    ref?: string;
+    /**
+     * A clone fastagent makes at `content/<name>` and brings up to date at each start while it holds nothing of the
+     * agent's. False when this machine binds its own checkout, which is never touched.
+     */
+    clone: boolean;
+});
+/** Resolve the agent's content for this instance. Refuses, naming the entry, what cannot be. */
+export declare function resolveContent(agentDir: string, { declared, bound }: ContentDeclaration): ResolvedContent[];
+/**
+ * The bindings of a directory only this machine has that point at nothing here: the directory was moved or removed.
+ * Not an error, since the binding is this machine's alone; the agent is not told of it, and whoever opens the agent
+ * says so.
+ */
+export declare function contentAbsentHere({ bound }: ContentDeclaration): BoundContent[];
+/** What is said of a binding {@link contentAbsentHere} returns, after the word "content". */
+export declare function absentNotice(binding: BoundContent): string;
+/**
+ * Whether the content `name` can be bound to the directory `target` of this machine: a directory, apart from the agent
+ * directory, and for a declared repository the root of a checkout of it. Returns what to tell the user (a checkout off
+ * its `ref`); refuses, naming the entry, what cannot be.
+ */
+export declare function checkBinding(agentDir: string, name: string, target: string, repository?: Pick<DeclaredContent, "repo" | "ref">): string[];
+/**
+ * Make a clone real, or bring it up to date at its `ref` in place, by git's rules, which never overwrite what the
+ * agent did in it (git.ts `refreshClone`): what git refuses, or a remote that cannot be reached, keeps it as it is,
+ * with the reason. Only a process that runs the agent calls this. A checkout this machine binds is never cloned over.
+ */
+export declare function cloneContent(entry: Extract<ResolvedContent, {
+    kind: "github";
+}>): Promise<CloneOutcome>;

package/dist/content/resolve.js

@@ -0,0 +1,151 @@
+/**
+ * WHERE each content entry is, for THIS instance: the one answer the prompt, the coding tools, authored tools, `info`
+ * and `deploy` all read (docs/design/core.md §2). A repository `context.json` declares is fastagent's clone at
+ * `content/<name>`, or this machine's own checkout of it where `context.local.json` binds one; a directory only this
+ * machine has is where its binding says. Reads the disk (git included); never the network, never a write. Making a
+ * clone real is `cloneContent`'s, and only a process that runs the agent asks for it.
+ */
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { LOCAL_CONTEXT_FILE, contentEntryPath } from "../paths.js";
+import { nestingError } from "./declare.js";
+import { checkoutProblem, refNotice, refreshClone } from "./git.js";
+import { ensureContentDir } from "./mount.js";
+/** Resolve the agent's content for this instance. Refuses, naming the entry, what cannot be. */
+export function resolveContent(agentDir, { declared, bound }) {
+    const shared = declared.map((entry) => resolveRepository(agentDir, entry, bound.find((binding) => binding.kind === "checkout" && binding.name === entry.name)));
+    const local = bound
+        .filter((binding) => binding.kind === "local" && statOrMissing(binding.path) !== undefined)
+        .map((binding) => resolveLocal(agentDir, binding));
+    return [...shared, ...local];
+}
+/**
+ * The bindings of a directory only this machine has that point at nothing here: the directory was moved or removed.
+ * Not an error, since the binding is this machine's alone; the agent is not told of it, and whoever opens the agent
+ * says so.
+ */
+export function contentAbsentHere({ bound }) {
+    return bound.filter((binding) => binding.kind === "local" && statOrMissing(binding.path) === undefined);
+}
+/** What is said of a binding {@link contentAbsentHere} returns, after the word "content". */
+export function absentNotice(binding) {
+    return (`${binding.name}: bound in ${LOCAL_CONTEXT_FILE} to ${binding.path}, which does not exist here: the agent is ` +
+        `not told of it`);
+}
+function resolveRepository(agentDir, entry, checkout) {
+    const { name, readonly, description } = entry;
+    const repository = {
+        name,
+        readonly,
+        ...(description !== undefined ? { description } : {}),
+        kind: "github",
+        repo: entry.repo,
+        ...(entry.ref !== undefined ? { ref: entry.ref } : {}),
+    };
+    if (checkout !== undefined && statOrMissing(checkout.path) !== undefined) {
+        const location = realpathSync(checkout.path);
+        const notices = checkBinding(agentDir, name, location, entry);
+        return { ...repository, location, notices, clone: false };
+    }
+    const location = contentEntryPath(agentDir, name);
+    const found = lstatOrMissing(location);
+    if (found?.isSymbolicLink()) {
+        throw new Error(`content "${name}": content/${name} is a link, and content/ holds only the clones fastagent makes — remove ` +
+            `the link, and bind a checkout of your own in ${LOCAL_CONTEXT_FILE} instead (fastagent content add <dir>)`);
+    }
+    if (found && !found.isDirectory())
+        throw new Error(`content "${name}": ${location} is not a directory`);
+    const notices = found ? [] : ["not cloned yet: it is cloned when the agent starts"];
+    if (checkout !== undefined) {
+        notices.unshift(`bound in ${LOCAL_CONTEXT_FILE} to ${checkout.path}, which does not exist here: the clone is used`);
+    }
+    return { ...repository, location, notices, clone: true };
+}
+function resolveLocal(agentDir, binding) {
+    const { name, readonly, description } = binding;
+    const location = realpathSync(binding.path);
+    checkBinding(agentDir, name, location);
+    return {
+        name,
+        readonly,
+        ...(description !== undefined ? { description } : {}),
+        location,
+        notices: [],
+        kind: "local",
+    };
+}
+/**
+ * Whether the content `name` can be bound to the directory `target` of this machine: a directory, apart from the agent
+ * directory, and for a declared repository the root of a checkout of it. Returns what to tell the user (a checkout off
+ * its `ref`); refuses, naming the entry, what cannot be.
+ */
+export function checkBinding(agentDir, name, target, repository) {
+    const stat = statOrMissing(target);
+    if (!stat)
+        throw new Error(`content "${name}": ${target} does not exist`);
+    if (!stat.isDirectory())
+        throw new Error(`content "${name}": ${target} is not a directory`);
+    // A symlink can still put one inside the other, so ask of the real paths — including for an agent directory `init`
+    // is about to create, which a symlinked ancestor still places.
+    const nested = nestingError(realPathOf(agentDir), realpathSync(target), name);
+    if (nested)
+        throw new Error(nested);
+    if (repository === undefined)
+        return [];
+    const problem = checkoutProblem(target, repository.repo);
+    if (problem)
+        throw new Error(`content "${name}": ${target} ${problem}`);
+    const offRef = repository.ref === undefined ? undefined : refNotice(target, repository.ref);
+    return offRef ? [offRef] : [];
+}
+/**
+ * Make a clone real, or bring it up to date at its `ref` in place, by git's rules, which never overwrite what the
+ * agent did in it (git.ts `refreshClone`): what git refuses, or a remote that cannot be reached, keeps it as it is,
+ * with the reason. Only a process that runs the agent calls this. A checkout this machine binds is never cloned over.
+ */
+export async function cloneContent(entry) {
+    if (!entry.clone)
+        throw new Error(`content "${entry.name}" is bound to the checkout ${entry.location}, not a clone`);
+    ensureContentDir(dirname(entry.location));
+    return refreshClone(entry.repo, entry.ref, entry.location).catch((error) => {
+        throw new Error(`content "${entry.name}": ${error.message}`);
+    });
+}
+/**
+ * Where `path` really is, whether or not it exists yet: its nearest existing ancestor resolved, and the segments below
+ * it appended as written. A directory that does not exist yet links nowhere itself, but an ancestor can.
+ */
+function realPathOf(path) {
+    const below = [];
+    for (let current = path;; current = dirname(current)) {
+        try {
+            return join(realpathSync(current), ...below.reverse());
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || dirname(current) === current)
+                throw error;
+            below.push(basename(current));
+        }
+    }
+}
+function lstatOrMissing(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function statOrMissing(path) {
+    try {
+        return statSync(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return undefined;
+        throw error;
+    }
+}

package/dist/content/source.d.ts

@@ -0,0 +1,27 @@
+import { type ContentBinding, type ContentEntry } from "./declare.ts";
+export interface SourceOptions {
+    readonly?: boolean;
+    name?: string;
+    /** A github entry's branch, tag or commit. */
+    ref?: string;
+    description?: string;
+}
+/**
+ * A content entry to add, by name: the repository `context.json` declares for every instance, this machine's binding
+ * in `context.local.json`, or both (a checkout of the declared repository). At least one.
+ */
+export interface ContentAddition {
+    name: string;
+    entry?: ContentEntry;
+    binding?: ContentBinding;
+}
+/**
+ * The addition `source` asks for, with what to tell the user about how it was read. `github:owner/repo` is a
+ * repository fastagent clones. The root of a checkout whose `origin` is on GitHub is that repository, declared for
+ * every instance and bound to this checkout here. Any other directory, a subdirectory of such a checkout included, is
+ * bound on this machine alone. The name defaults to the repository's or the directory's.
+ */
+export declare function readContentSource(source: string, cwd: string, options?: SourceOptions): {
+    addition: ContentAddition;
+    notes: string[];
+};

package/dist/content/source.js

@@ -0,0 +1,53 @@
+/**
+ * What a command's `<source>` adds (`init --content`, `fastagent content add`; docs/design/agent-cli.md §3), read the
+ * same way by both: `github:owner/repo`, the root of a GitHub checkout, or any other directory.
+ */
+import { realpathSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { isGithubRepo } from "./declare.js";
+import { checkoutOf, githubRepoOf } from "./git.js";
+/**
+ * The addition `source` asks for, with what to tell the user about how it was read. `github:owner/repo` is a
+ * repository fastagent clones. The root of a checkout whose `origin` is on GitHub is that repository, declared for
+ * every instance and bound to this checkout here. Any other directory, a subdirectory of such a checkout included, is
+ * bound on this machine alone. The name defaults to the repository's or the directory's.
+ */
+export function readContentSource(source, cwd, options = {}) {
+    const treated = {
+        ...(options.readonly ? { readonly: true } : {}),
+        ...(options.description !== undefined ? { description: options.description } : {}),
+    };
+    const ref = options.ref !== undefined ? { ref: options.ref } : {};
+    const repoName = (repo) => repo.slice(repo.indexOf("/") + 1);
+    if (source.startsWith("github:")) {
+        const repo = source.slice("github:".length);
+        if (!isGithubRepo(repo))
+            throw new Error(`${source} names no repository: write github:owner/repo`);
+        return {
+            addition: { name: options.name ?? repoName(repo), entry: { github: repo, ...ref, ...treated } },
+            notes: [],
+        };
+    }
+    const dir = resolve(cwd, source);
+    const checkout = checkoutOf(dir);
+    const repo = checkout?.origin === undefined ? undefined : githubRepoOf(checkout.origin);
+    const atRoot = checkout !== undefined && realpathSync(dir) === realpathSync(checkout.root);
+    if (repo !== undefined && atRoot) {
+        const root = checkout.root;
+        return {
+            addition: {
+                name: options.name ?? repoName(repo),
+                entry: { github: repo, ...ref, ...treated },
+                binding: { path: root },
+            },
+            notes: [],
+        };
+    }
+    if (options.ref !== undefined) {
+        throw new Error(`--ref applies to a repository, and ${dir} is bound as a directory of this machine`);
+    }
+    const notes = repo !== undefined && !atRoot
+        ? [`${dir} is in a checkout of github ${repo}: add github:${repo} for the whole repository`]
+        : [];
+    return { addition: { name: options.name ?? basename(dir), binding: { path: dir, ...treated } }, notes };
+}

package/dist/conversation-sessions.d.ts

@@ -0,0 +1,26 @@
+import { type Agent, type CreateSessionOptions } from "./agent-api.ts";
+/** What the map asks of the Agent: whether a recorded session is still there, and a new one when it is not. */
+type SessionsAgent = {
+    sessions: Pick<Agent["sessions"], "get" | "create">;
+};
+/** A new, empty session: what a conversation the agent has not talked in starts with. */
+export declare function newSession(agent: SessionsAgent): Promise<string>;
+/** A new session forked from `from`, or an empty one when there is nothing to fork. */
+export declare function forkedSession(agent: SessionsAgent, from: CreateSessionOptions["forkFrom"]): Promise<string>;
+export interface ConversationSessions {
+    /** The session `conversation` was recorded with, when it has one, as recorded. */
+    get(conversation: string): string | undefined;
+    /**
+     * The session `conversation` talks in: the one it has, or the one `create` makes (an empty one by default), recorded
+     * before it is returned. A recorded session the Agent no longer holds (its storage was reset, or restored from an
+     * older copy) is replaced the same way, and said so, rather than failing every message after it.
+     */
+    of(conversation: string, agent: SessionsAgent, create?: () => Promise<string>): Promise<string>;
+}
+/**
+ * The map kept in `file`, read once and kept in memory: one process owns an instance's state, so nothing else writes
+ * it while this process runs, and a turn costs no read of a file that grows with every conversation. Written whole,
+ * synchronously, when a conversation gets a session.
+ */
+export declare function conversationSessions(file: string): ConversationSessions;
+export {};

package/dist/conversation-sessions.js

@@ -0,0 +1,99 @@
+/**
+ * Which Agent session each of a Caller's conversations talks in: a channel's chats and threads (its `sessionFor`), a
+ * schedule's runs. The Agent names sessions, so a Caller keeps this map, in its own state (a channel's
+ * `<stateDir>/sessions.json`, the schedules' `schedule/sessions.json`), and creates a conversation's session in one
+ * order (architecture.md §2): the session, then the record, then the message. The map takes one conversation's calls
+ * one at a time, so two messages for one new conversation meet it one after the other and get one session. A crash
+ * between the session and the record leaves a session nothing refers to, which the retry does not reuse; no message is
+ * answered twice, since a message is sent only once its session is recorded.
+ */
+import { dirname } from "node:path";
+import { AgentError } from "./agent-api.js";
+import { log } from "./log.js";
+import { ensureStateHome, loadStateFile, saveStateFile } from "./state-file.js";
+/** A new, empty session: what a conversation the agent has not talked in starts with. */
+export async function newSession(agent) {
+    const created = await agent.sessions.create().catch((error) => {
+        if (!(error instanceof AgentError))
+            throw error;
+        throw new AgentError({ ...error, message: `creating a session failed: ${error.message}` });
+    });
+    return created.id;
+}
+/** A new session forked from `from`, or an empty one when there is nothing to fork. */
+export async function forkedSession(agent, from) {
+    if (from === undefined)
+        return newSession(agent);
+    const created = await agent.sessions.create({ forkFrom: from }).catch((error) => {
+        if (!(error instanceof AgentError))
+            throw error;
+        throw new AgentError({
+            ...error,
+            message: `starting a session forked from ${from.sessionId} failed: ${error.message}`,
+        });
+    });
+    return created.id;
+}
+/**
+ * The map kept in `file`, read once and kept in memory: one process owns an instance's state, so nothing else writes
+ * it while this process runs, and a turn costs no read of a file that grows with every conversation. Written whole,
+ * synchronously, when a conversation gets a session.
+ */
+export function conversationSessions(file) {
+    let recorded;
+    const map = () => {
+        if (recorded === undefined) {
+            const stored = loadStateFile(file);
+            recorded = new Map(stored !== null && typeof stored === "object" ? Object.entries(stored) : []);
+        }
+        return recorded;
+    };
+    // A session asked about once is the Agent's for as long as this process runs: sessions are never deleted.
+    const confirmed = new Set();
+    const held = async (agent, sessionId) => {
+        if (confirmed.has(sessionId))
+            return true;
+        const held = await agent.sessions.get(sessionId).then(() => true, (error) => {
+            if (error instanceof AgentError && error.code === "not_found")
+                return false;
+            throw error;
+        });
+        if (held)
+            confirmed.add(sessionId);
+        return held;
+    };
+    const resolve = async (conversation, agent, create) => {
+        const known = map().get(conversation);
+        if (known !== undefined && (await held(agent, known)))
+            return known;
+        if (known !== undefined) {
+            log.warn(`[fastagent] ${conversation}: its session ${known} is not in the agent's storage (reset, or restored from ` +
+                `an older copy) — starting it a new one, recorded in ${file}`);
+        }
+        const sessionId = await create();
+        map().set(conversation, sessionId);
+        ensureStateHome(dirname(file));
+        saveStateFile(file, Object.fromEntries(map()));
+        confirmed.add(sessionId);
+        return sessionId;
+    };
+    /** Each conversation's last call: the next one waits for it, whatever it ended with. */
+    const calls = new Map();
+    return {
+        get: (conversation) => map().get(conversation),
+        of(conversation, agent, create = () => newSession(agent)) {
+            const previous = calls.get(conversation);
+            // Without one before it, the call starts now, as an unqueued one would: its Caller reads no turn of the loop.
+            const call = previous === undefined
+                ? resolve(conversation, agent, create)
+                : previous.then(() => resolve(conversation, agent, create), () => resolve(conversation, agent, create));
+            calls.set(conversation, call);
+            const forget = () => {
+                if (calls.get(conversation) === call)
+                    calls.delete(conversation);
+            };
+            call.then(forget, forget);
+            return call;
+        },
+    };
+}

package/dist/declared-secrets.d.ts

@@ -1,55 +1,37 @@
 /**
- * WHICH ENV VARS THIS AGENT'S CODE NEEDS, in ONE shape, wherever it was declared: `defineTool`, `defineChannel` and
- * `defineRoutine({ secrets })`, each next to the code that reads the value.
+ * WHICH ENV VARS THIS AGENT NEEDS, in ONE shape, wherever it was declared: `needs(...)`, next to the code that reads
+ * the value, and the `variables` of `context.json`, for the commands the agent runs.
  *
  * One list, two consequences:
- *  - a serving path ASSERTS the values before it runs, so a missing one is a startup failure naming the file, not a
- *    401 three days later;
+ *  - opening the agent ASSERTS the values first, so a missing one is a startup failure naming the file, not a 401
+ *    three days later;
  *  - `deploy --run` refuses a value file that does not supply one.
  *
- * Agent code does not read `process.env`: each authoring surface hands back exactly the values it declared, so the
- * declaration cannot drift from the read, and a typo is a type error. The values still travel through the process env
- * (a provider SDK reads its own variable), and `deploy` carries the whole value file (deploy/secrets.ts) — a
- * declaration makes a value REQUIRED, it does not decide what travels.
+ * Agent code does not read `process.env`: `needs` hands back exactly the values it declared, so the declaration cannot
+ * drift from the read, and a typo is a type error. A command the agent runs (`gh`) reads its own variable from the
+ * process env, so a `context.json` declaration hands nothing back. The values travel through the process env, and
+ * `deploy` carries the whole value file (deploy/secrets.ts) — a declaration makes a value REQUIRED, it does not decide
+ * what travels.
  */
 /** One env var some part of the definition declared, and where that declaration is. */
 export interface DeclaredSecret {
     /** The env-var name. */
     name: string;
-    /** Where it was declared: "tools/x-post.ts", "routines/daily-digest.ts", "config.tools" — printed in
+    /** Where it was declared: "src/tools/x-post.ts", "fastagent.config.ts providers[0]", "context.json" — printed in
      *  runbooks and failures, so it must name a place the author can open. */
     source: string;
+    /** What it is for, when the declaration says (`context.json`'s variables do): printed beside it in runbooks. */
+    description?: string;
+    /** The code runs without it: no start is refused for its absence. */
+    optional?: boolean;
 }
-/**
- * THE READ: what a code-input module declared, attributed to its file — the one implementation for
- * `tools/`, `routines/` and `channels/`.
- *
- * One function, so every code input gets the same shape check: a `secrets: "FOO"` is that file's load
- * failure, wherever it is. What a caller DOES with a bad declaration differs (push a failure and skip, or throw
- * inside its own per-file try), so the verdict travels back as data rather than as an exception.
- */
-export declare function readSecretDeclaration(moduleDefault: unknown, label: string): {
-    secrets: DeclaredSecret[];
-    error?: undefined;
-} | {
-    secrets?: undefined;
-    error: string;
-};
-/** Every owner's declarations as one list — what a path that runs ALL of them (a serve, a deploy)
- *  asserts or carries. A path that runs ONE reads that owner's entry instead. */
-export declare function allSecrets(byOwner: ReadonlyMap<string, readonly DeclaredSecret[]>): DeclaredSecret[];
+/** Whether `name` has the shape of an env-var name ({@link ENV_NAME}). */
+export declare function isEnvName(name: string): boolean;
 /** Declared names as a stable list, first declaration winning — the form a carrier iterates. */
 export declare function dedupeSecrets(declared: readonly DeclaredSecret[]): DeclaredSecret[];
-/**
- * The values for a declared list, as the authoring surfaces hand them to author code. A name with no
- * value reads as `""` rather than throwing: the deploy pre-flight IMPORTS these modules on a machine
- * that legitimately holds no secrets, and a throwing accessor would make the channel whose secrets we
- * came to collect unloadable. Presence is guaranteed by the gate (src/secrets-gate.ts) on the paths
- * that run the code, which is the one place that can tell "not set" from "not needed here".
- */
-export declare function secretValues<const S extends readonly string[]>(names: S | undefined, env?: NodeJS.ProcessEnv): Record<S[number], string>;
-/** Declared names with no value in `env` — empty string counts as missing (an unset `.env` line). */
+/** Required names with no value in `env` — empty string counts as missing (an unset `.env` line). A name some
+ *  declaration requires is required, whatever another says. */
 export declare function missingSecrets(declared: readonly DeclaredSecret[], env?: NodeJS.ProcessEnv): DeclaredSecret[];
-/** "X_API_KEY, X_API_SECRET (tools/x-post.ts); SLACK_TOKEN (routines/digest.ts)" — grouped by the
+/** "X_API_KEY, X_API_SECRET (src/tools/x-post.ts); SLACK_TOKEN (src/channels/slack.ts)" — grouped by the
  *  file to open, since that is the unit the author fixes. */
 export declare function describeSecrets(declared: readonly DeclaredSecret[]): string;

package/dist/declared-secrets.js

@@ -1,16 +1,17 @@
 /**
- * WHICH ENV VARS THIS AGENT'S CODE NEEDS, in ONE shape, wherever it was declared: `defineTool`, `defineChannel` and
- * `defineRoutine({ secrets })`, each next to the code that reads the value.
+ * WHICH ENV VARS THIS AGENT NEEDS, in ONE shape, wherever it was declared: `needs(...)`, next to the code that reads
+ * the value, and the `variables` of `context.json`, for the commands the agent runs.
  *
  * One list, two consequences:
- *  - a serving path ASSERTS the values before it runs, so a missing one is a startup failure naming the file, not a
- *    401 three days later;
+ *  - opening the agent ASSERTS the values first, so a missing one is a startup failure naming the file, not a 401
+ *    three days later;
  *  - `deploy --run` refuses a value file that does not supply one.
  *
- * Agent code does not read `process.env`: each authoring surface hands back exactly the values it declared, so the
- * declaration cannot drift from the read, and a typo is a type error. The values still travel through the process env
- * (a provider SDK reads its own variable), and `deploy` carries the whole value file (deploy/secrets.ts) — a
- * declaration makes a value REQUIRED, it does not decide what travels.
+ * Agent code does not read `process.env`: `needs` hands back exactly the values it declared, so the declaration cannot
+ * drift from the read, and a typo is a type error. A command the agent runs (`gh`) reads its own variable from the
+ * process env, so a `context.json` declaration hands nothing back. The values travel through the process env, and
+ * `deploy` carries the whole value file (deploy/secrets.ts) — a declaration makes a value REQUIRED, it does not decide
+ * what travels.
  */
 /**
  * What an env-var NAME may look like. Checked at the declaration, not left to the host: these names
@@ -20,64 +21,21 @@
  * a real variable — only the shape a shell and every artifact format agree on.
  */
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
-/** Why an authored `secrets:` is unusable, or undefined when it is fine. A `.js` tool or a wrong type
- *  never met TypeScript, and a malformed declaration must fail as a load error rather than be
- *  silently dropped — the whole value of the field is that its absence is meaningful. */
-function secretNamesProblem(value) {
-    if (value === undefined)
-        return undefined;
-    if (!Array.isArray(value))
-        return "secrets must be an array of env-var names";
-    for (const name of value) {
-        if (typeof name !== "string" || !ENV_NAME.test(name)) {
-            return `secrets must be an array of env-var names — ${JSON.stringify(name)} is not one`;
-        }
-    }
-    return undefined;
-}
-/**
- * THE READ: what a code-input module declared, attributed to its file — the one implementation for
- * `tools/`, `routines/` and `channels/`.
- *
- * One function, so every code input gets the same shape check: a `secrets: "FOO"` is that file's load
- * failure, wherever it is. What a caller DOES with a bad declaration differs (push a failure and skip, or throw
- * inside its own per-file try), so the verdict travels back as data rather than as an exception.
- */
-export function readSecretDeclaration(moduleDefault, label) {
-    const declared = moduleDefault?.secrets;
-    const problem = secretNamesProblem(declared);
-    if (problem !== undefined)
-        return { error: `${label}: ${problem}` };
-    return { secrets: (declared ?? []).map((name) => ({ name, source: label })) };
-}
-/** Every owner's declarations as one list — what a path that runs ALL of them (a serve, a deploy)
- *  asserts or carries. A path that runs ONE reads that owner's entry instead. */
-export function allSecrets(byOwner) {
-    return [...byOwner.values()].flat();
+/** Whether `name` has the shape of an env-var name ({@link ENV_NAME}). */
+export function isEnvName(name) {
+    return ENV_NAME.test(name);
 }
 /** Declared names as a stable list, first declaration winning — the form a carrier iterates. */
 export function dedupeSecrets(declared) {
     const seen = new Set();
     return declared.filter((s) => !seen.has(s.name) && seen.add(s.name));
 }
-/**
- * The values for a declared list, as the authoring surfaces hand them to author code. A name with no
- * value reads as `""` rather than throwing: the deploy pre-flight IMPORTS these modules on a machine
- * that legitimately holds no secrets, and a throwing accessor would make the channel whose secrets we
- * came to collect unloadable. Presence is guaranteed by the gate (src/secrets-gate.ts) on the paths
- * that run the code, which is the one place that can tell "not set" from "not needed here".
- */
-export function secretValues(names, env = process.env) {
-    const values = {};
-    for (const name of names ?? [])
-        values[name] = env[name] ?? "";
-    return values;
-}
-/** Declared names with no value in `env` — empty string counts as missing (an unset `.env` line). */
+/** Required names with no value in `env` — empty string counts as missing (an unset `.env` line). A name some
+ *  declaration requires is required, whatever another says. */
 export function missingSecrets(declared, env = process.env) {
-    return dedupeSecrets(declared).filter((s) => !env[s.name]);
+    return dedupeSecrets(declared.filter((s) => s.optional !== true)).filter((s) => !env[s.name]);
 }
-/** "X_API_KEY, X_API_SECRET (tools/x-post.ts); SLACK_TOKEN (routines/digest.ts)" — grouped by the
+/** "X_API_KEY, X_API_SECRET (src/tools/x-post.ts); SLACK_TOKEN (src/channels/slack.ts)" — grouped by the
  *  file to open, since that is the unit the author fixes. */
 export function describeSecrets(declared) {
     const bySource = new Map();

package/dist/deploy/agentcore/destroy.d.ts

@@ -8,9 +8,9 @@
  *   the runtime's image from them), so they cannot be stack resources;
  * - the forwarder's log group is created by AWS on the Lambda's first WRITE, so no template ever mentions it —
  *   and the deploy put a 14-day retention on it, i.e. it holds data;
- * - a wake alarm is minted at RUNTIME by the container. `ActionAfterCompletion: DELETE` only runs once one
- *   FIRES, so anything stopped between the wake call and the fire leaves a schedule that retries into a deleted
- *   Lambda for weeks.
+ * - the EventBridge schedules are minted at RUNTIME by the container: a recurring one per `schedules/` file, which
+ *   nothing ever deletes but the container's next sync, and a one-shot per pending wake-up, whose
+ *   `ActionAfterCompletion: DELETE` only runs once it FIRES. Either left behind retries into a deleted Lambda.
  *
  * This file is the RESOURCE LIST, the order the dependencies demand, and one policy decision per resource for
  * what to do when AWS cannot answer. What an AWS answer MEANS — there, gone, or unreadable — belongs to