@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/harnesses/pi-durable/serve.d.ts

@@ -3,13 +3,44 @@ import { type Harness } from "@earendil-works/pi-durable";
 import type { CredentialSourceOptions } from "../models/credentials.ts";
 import { type ModelEnvironment } from "../models/environment.ts";
 import type { CredentialStore } from "../../sign-in-api.ts";
+import type { McpOptions } from "../../mcp-api.ts";
+import { type RunsAs } from "../../serving-command.ts";
 import { type ResolvedContent } from "../../content/resolve.ts";
 import type { Agent } from "../../agent-api.ts";
 import { type Service } from "../../service.ts";
 import type { DurableAgent, Unfinished } from "./agent.ts";
-import { type AgentDefinition, type BuiltDefinition } from "./open.ts";
+import { type EffectiveConfig, type InstanceConfig, type InstanceConfigSource } from "./config.ts";
+import { type AgentDefinition } from "./definition.ts";
+import { type BuiltDefinition } from "./open.ts";
 import { type StorageLocking } from "./storage.ts";
 export interface OpenServingOptions extends CredentialSourceOptions {
+    mcp?: McpOptions;
+    /** The instance's name, over the configuration's. Default: the configuration's, else the definition's as one segment. */
+    name?: string;
+    /**
+     * The values the instance's code, its MCP servers and its model's authentication read by name (`needs`, `${VAR}`,
+     * a provider's variable): the one source of them, never this process's environment. A caller that wants its own
+     * passes it (`process.env`).
+     */
+    secrets: Readonly<Record<string, string | undefined>>;
+    /**
+     * The base environment of the processes the agent starts (`baseEnv(process.env)` is the CLI's): the commands of
+     * its declared packages come ahead on its `PATH`, and the declared secrets are added to it. Nothing else of this
+     * process's reaches them.
+     */
+    env: Readonly<Record<string, string>>;
+    /**
+     * The environment FastAgent's own work for the instance runs in: installing the declared packages, cloning content,
+     * finding `git` and `mise`, and where a CLI instance's files are. The CLI gives this process's; an app, its `env`.
+     * The instance's secrets are added to it.
+     */
+    ownEnv: Readonly<Record<string, string | undefined>>;
+    /** Who runs the instance: what decides how a channel that names no way receives, and whether its prompt describes a deployment. */
+    runsAs: RunsAs;
+    /** Whether the model lists are refreshed without the network. Default: `ownEnv`'s `FASTAGENT_OFFLINE` is `1`. */
+    offline?: boolean;
+    /** What the instance sets over the program's defaults (`fastagent.json`, or an object); none runs on the defaults. */
+    config?: InstanceConfigSource;
     /** What a deployment sets over the definition's defaults (a flag, `FASTAGENT_MODEL`). */
     model?: string;
     thinkingLevel?: ModelThinkingLevel;
@@ -23,8 +54,26 @@ export interface OpenServingOptions extends CredentialSourceOptions {
     storage?: ServingStorage;
     /** What becomes of the messages an earlier process left unfinished in the storage. Default `"resume"`. */
     unfinished?: Unfinished;
-    /** The instance's state root, over `FASTAGENT_STATE_DIR` and the directory's own. */
+    /**
+     * The instance's directory: its working directory, where its content is cloned, its secrets and, by default, its
+     * state are. Default: the definition's own, which is how a source project runs. A built package is read-only and is
+     * opened with a directory of its own.
+     */
+    workdir?: string;
+    /**
+     * The directory whose `.secrets/` (values, model credentials, MCP grants) and default state
+     * root the instance reads. Default: the working directory. Temporary: secrets and content become inputs of their own.
+     */
+    projectDir?: string;
+    /** The instance's state root, over `FASTAGENT_STATE_DIR` and the project directory's own. */
     stateRoot?: string;
+    /**
+     * Where the instance keeps its model credentials and MCP grants when it is given no store: `"secrets"`, the project's
+     * `.secrets/` over the machine's own credentials and as `FASTAGENT_AUTH_PATH` and `FASTAGENT_SECRETS_DIR` place them
+     * (the CLI's), or `"state"`, `auth.json` and `mcp-auth.json` in the state root and nothing else (an app's).
+     * Default `"secrets"`.
+     */
+    keeps?: "secrets" | "state";
     /** Whether a clock fires the instance's wake-ups now (`assembleAgent`'s `wakeTicking`). Default always. */
     wakeTicking?: () => boolean;
 }
@@ -37,11 +86,20 @@ type ServingStorage = {
 export interface OpenedServing {
     agent: DurableAgent;
     definition: AgentDefinition;
+    /** The instance's name: what `info().name` reports. */
+    name: string;
     code: BuiltDefinition;
+    /** The configuration this instance opened with: the program's defaults and the instance's over them. */
+    config: EffectiveConfig;
+    /** The secrets it was given that hold a value: what its code was built with, and its webhooks are pointed with. */
+    secrets: Readonly<Record<string, string>>;
     models: ModelEnvironment;
     /** What the agent works on, resolved for this instance. */
     content: readonly ResolvedContent[];
+    /** The project directory: whose `.secrets/` the instance reads. */
     agentDir: string;
+    /** The agent's working directory. */
+    workdir: string;
     /** Where the instance's state is: its storage, its channels' and schedules' state, its wake-ups. */
     stateRoot: string;
     /** The definition's channels and schedules, as `serveAgent` serves them: `serveAgent(opened)`. */
@@ -53,7 +111,7 @@ export interface OpenedServing {
  * instance's state outside a serve without losing a write to a serve's own.
  */
 export declare function holdingInstance<T>(stateRoot: string, work: () => T): Promise<T>;
-export declare function openServing(directory: string, options?: OpenServingOptions): Promise<OpenedServing>;
+export declare function openServing(definition: AgentDefinition, options: OpenServingOptions): Promise<OpenedServing>;
 /** An agent opened in this process (SPEC.md §8): the Agent API, and how it is served and operated. */
 export interface LocalAgent extends Agent {
     /**
@@ -70,21 +128,43 @@ export interface ServeAgentOptions {
     /** The keys a Caller of the Agent API may present (SPEC.md §9.1). */
     apiKeys?: readonly string[];
 }
-export interface OpenAgentOptions {
+/** The instance root, the agent's working directory with its state in `.state/`; or the two apart (SPEC.md §8). */
+export type InstanceLocation = {
+    root: string;
+} | {
+    stateDir: string;
+    workdir: string;
+};
+export type OpenAgentOptions<Settings = unknown> = InstanceLocation & {
+    /** The instance configuration, over the program's defaults: an object, or the absolute path of a `fastagent.json`. */
+    config?: InstanceConfig<Settings> | string;
+    /** The instance's name, over `config`'s: one path segment. Default: `config`'s, else the definition's as one. */
+    name?: string;
+    /**
+     * The values the agent's code (`needs`), its MCP servers (`${VAR}`) and its model's authentication read by name. The
+     * only source of them: nothing is read from the process's environment or from a file, so pass what the agent needs
+     * (`process.env` is a choice an app can make).
+     */
+    secrets?: Readonly<Record<string, string | undefined>>;
+    /**
+     * The base environment of the processes the agent starts (its commands, stdio MCP servers, skill scripts). Default:
+     * empty; `baseEnv(process.env)` is an app's own. The commands of the agent's declared packages come ahead on its
+     * `PATH`, and the secrets the definition declares are added; nothing else of the host's reaches them.
+     */
+    env?: Readonly<Record<string, string>>;
+    /** Per-instance MCP grants and interpolation values; no global credential discovery. */
+    mcp?: McpOptions;
     /** `"provider/modelId"`, over the definition's: what a session that names none answers with. */
     model?: string;
-    /** Where provider credentials are kept, instead of the agent's own `.secrets/auth.json` over the machine's. */
+    /** Where provider credentials are kept, instead of the state directory's `auth.json`. */
     credentials?: CredentialStore;
-    /**
-     * Where this instance keeps its sessions, its channels' and schedules' state and its model lists, instead of
-     * `FASTAGENT_STATE_DIR` or the agent's `.state/`: a host's own instance of an agent beside `fastagent dev`'s.
-     */
-    stateDir?: string;
-}
+    /** Refresh the model lists without the network: each is the one last kept, or pi-ai's own. Default: false. */
+    offline?: boolean;
+};
 /**
- * Open the agent directory `dir` the way `dev` and `start` do before they serve: its definition, its code built with
- * the secrets it declares, its environment, its content and the instance's storage, which one process holds at a time.
- * Nothing reaches the agent until `serve`.
+ * Open one instance of `definition`, the default export of an agent's package, the way `dev` and `start` do before they
+ * serve: its code built with the secrets it declares, its environment, its content and the instance's storage, which
+ * one process holds at a time. Nothing reaches the agent until `serve`.
  */
-export declare function openAgent(dir: string, options?: OpenAgentOptions): Promise<LocalAgent>;
+export declare function openAgent<Settings = unknown>(definition: AgentDefinition<Settings>, options: OpenAgentOptions<Settings>): Promise<LocalAgent>;
 export {};

package/dist/harnesses/pi-durable/serve.js

@@ -1,23 +1,33 @@
 /**
- * An agent package opened: its definition prepared (the registry generated, the secrets manifest written), its code
- * built with its secrets, its model environment, its storage, and the Agent over them. `openAgent` is how an app opens
- * one (SPEC.md §8); `dev`, `start`, AgentCore, `invoke` and `schedules run` open it through `openServing`, which
- * also takes where the Agent keeps its sessions and what becomes of an earlier process's messages.
+ * A definition opened: its code built with its secrets, its model environment, its storage, and the Agent over them.
+ * `openAgent` is how an app opens one (SPEC.md §8); `dev`, `start`, AgentCore, `invoke` and `schedules run` open it
+ * through `openServing`, which also takes where the Agent keeps its sessions and what becomes of an earlier process's
+ * messages.
  */
-import { join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { MemoryStorage } from "@earendil-works/pi-durable";
 import { modelEnvironment } from "../models/environment.js";
 import { piCredentials } from "../models/host.js";
+import { openMcpClients } from "../../mcp/client.js";
+import { declareMcp, resolveMcpServers } from "../../mcp/config.js";
+import { mcpAuthorization, mcpAuthorizationInState } from "../../mcp/host.js";
+import { NOT_HOSTED } from "../../serving-command.js";
+import { mcpTools } from "./mcp.js";
 import { loadContent } from "../../content/file.js";
-import { absentNotice, cloneContent, contentAbsentHere, resolveContent, } from "../../content/resolve.js";
-import { agentValues } from "../../value-file.js";
+import { cloneContent, resolveContent } from "../../content/resolve.js";
+import { processEnvironment } from "../../child-env.js";
+import { definedValues } from "../../declared-secrets.js";
 import { prepareEnvironment } from "../../environment/mise.js";
 import { log } from "../../log.js";
-import { resolveOverridePath, resolveStateRoot } from "../../paths.js";
+import { STATE_DIRNAME, resolveStateRoot } from "../../paths.js";
 import { serveAgent } from "../../service.js";
-import { buildDefinition, assembleAgent, prepareDefinition, } from "./open.js";
+import { readInstanceConfigFile, resolveConfig, } from "./config.js";
+import { assertDefinition } from "./definition.js";
+import { assembleAgent, buildDefinition } from "./open.js";
 import { openLockedStorage } from "./storage.js";
+import { openText } from "./text.js";
+import { instanceName } from "../../instance-name.js";
 /** Who opens the instance's storage, for the refusal of a second opener. */
 const INSTANCE_HOLDERS = "another `fastagent dev`, `start` or `schedules` command of this agent (or of another agent with the same state root)";
 /**
@@ -26,10 +36,11 @@ const INSTANCE_HOLDERS = "another `fastagent dev`, `start` or `schedules` comman
  * up to date in place where git can do so without touching the agent's work, first; then resolved again as what is now
  * on disk.
  */
-async function contentForThisRun(dir, env) {
-    const declaration = loadContent(dir);
-    for (const entry of resolveContent(dir, declaration)) {
-        if (entry.kind !== "github" || !entry.clone)
+async function contentForThisRun(dir, instance, workdir, env) {
+    const declared = loadContent(dir, instance);
+    const places = { dir, workdir };
+    for (const entry of resolveContent(declared, places)) {
+        if (entry.kind !== "github")
             continue;
         const done = await cloneContent(entry, env);
         if (done.outcome === "kept") {
@@ -40,9 +51,7 @@ async function contentForThisRun(dir, env) {
             log.info(`[fastagent] github ${entry.repo}${entry.ref ? ` at ${entry.ref}` : ""}: ${said} in ${entry.location}`);
         }
     }
-    for (const absent of contentAbsentHere(declaration))
-        log.warn(`[fastagent] content ${absentNotice(absent)}`);
-    return resolveContent(dir, declaration);
+    return resolveContent(declared, places);
 }
 /** The instance's database, under its state root. */
 const instanceStorageFile = (stateRoot) => join(stateRoot, "agent.sqlite");
@@ -53,7 +62,7 @@ const instanceStorageFile = (stateRoot) => join(stateRoot, "agent.sqlite");
 export async function holdingInstance(stateRoot, work) {
     const storage = await openLockedStorage(instanceStorageFile(stateRoot), "posix", INSTANCE_HOLDERS);
     try {
-        return work();
+        return await work();
     }
     finally {
         await storage.close(BACKGROUND_CONTEXT);
@@ -66,73 +75,156 @@ function openStorage(stateRoot, storage) {
         return openLockedStorage(storage.file, "posix", storage.holders);
     return openLockedStorage(instanceStorageFile(stateRoot), storage.instance, INSTANCE_HOLDERS);
 }
-export async function openServing(directory, options = {}) {
-    const definition = await prepareDefinition(directory);
+export async function openServing(definition, options) {
     const { dir } = definition;
-    // The agent's environment is ONE value every reader below is given, and this process's is never written: a process
+    const workdir = options.workdir ?? dir;
+    const projectDir = options.projectDir ?? workdir;
+    const config = resolveConfig(definition, options.config);
+    const name = instanceName(definition.name, options.name ?? config.name);
+    const text = openText(dir, options.config);
+    const mcpServers = declareMcp(dir, options.config);
+    // The instance's values are ONE input every reader below is given, and this process's is never written: a process
     // may run several agents, each with its own values and packages.
-    const values = agentValues(dir);
-    const code = buildDefinition(definition, { ...process.env, ...values });
-    // The commands the agent runs, as `context.json`'s environment declares them, before anything can run one.
-    const environment = { ...values, ...(await prepareEnvironment(dir, { ...process.env, ...values })) };
-    const env = { ...process.env, ...environment };
-    const content = await contentForThisRun(dir, env);
-    const stateRoot = options.stateRoot ?? resolveStateRoot(dir, env);
-    const models = await modelEnvironment(dir, {
-        ...(options.authPath === undefined ? {} : { authPath: options.authPath }),
+    const secrets = definedValues(options.secrets);
+    const code = buildDefinition(definition, secrets, { ...config, dev: options.runsAs.dev });
+    // FastAgent's own work for the instance (installing packages, cloning content, finding its files) runs in this
+    // process's environment and the instance's secrets. What the AGENT starts gets an environment assembled from inputs.
+    const env = { ...options.ownEnv, ...secrets };
+    const packages = await prepareEnvironment(dir, env, { ...env, PATH: options.env.PATH });
+    const processEnv = processEnvironment({
+        base: options.env,
+        secrets,
+        declared: definition.inputs.secrets.map(({ name }) => name),
+        packages,
+        workdir,
+    }, dirname(workdir));
+    const content = await contentForThisRun(dir, options.config, workdir, env);
+    const stateRoot = options.stateRoot ?? resolveStateRoot(projectDir, env);
+    const authPath = options.authPath ??
+        (options.keeps === "state" && options.credentialStore === undefined ? join(stateRoot, "auth.json") : undefined);
+    const models = await modelEnvironment(projectDir, {
+        ...(authPath === undefined ? {} : { authPath }),
         ...(options.credentialStore === undefined ? {} : { credentialStore: options.credentialStore }),
-    }, code.providers, { stateRoot, environment });
+    }, code.providers, { stateRoot, environment: secrets, env, offline: options.offline ?? env.FASTAGENT_OFFLINE === "1" });
     const chosen = options.storage ?? { instance: "posix" };
     const storage = await openStorage(stateRoot, chosen);
-    const agent = await assembleAgent(definition, {
-        storage,
-        code,
-        content,
-        environment,
-        models: models.models,
-        ...(models.catalogProblem === undefined ? {} : { catalogProblem: models.catalogProblem }),
-        ...(typeof chosen === "object" && "instance" in chosen ? { stateRoot } : {}),
-        ...(options.model === undefined ? {} : { model: options.model }),
-        ...(options.thinkingLevel === undefined ? {} : { thinkingLevel: options.thinkingLevel }),
-        ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
-        ...(options.wakeTicking === undefined ? {} : { wakeTicking: options.wakeTicking }),
-    }).catch(async (error) => {
-        // An Agent that did not open does not own the storage, and its lock would refuse this process's next attempt.
-        await storage.close(BACKGROUND_CONTEXT);
-        throw error;
+    let mcp;
+    let agent;
+    try {
+        const mcpEnvironment = { ...secrets, ...options.mcp?.variables };
+        mcp = await openMcpClients(resolveMcpServers(mcpServers, mcpEnvironment, undefined, workdir, processEnv), options.keeps === "state"
+            ? mcpAuthorizationInState(stateRoot, options.mcp)
+            : mcpAuthorization(projectDir, env, stateRoot, options.mcp), options.mcp);
+        agent = await assembleAgent(definition, {
+            name,
+            mcpTools: mcpTools(mcp.tools),
+            runsAs: options.runsAs,
+            storage,
+            code,
+            config,
+            text,
+            content,
+            workdir,
+            processEnv,
+            models: models.models,
+            ...(models.catalogProblem === undefined ? {} : { catalogProblem: models.catalogProblem }),
+            ...(typeof chosen === "object" && "instance" in chosen ? { stateRoot } : {}),
+            ...(options.model === undefined ? {} : { model: options.model }),
+            ...(options.thinkingLevel === undefined ? {} : { thinkingLevel: options.thinkingLevel }),
+            ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
+            ...(options.wakeTicking === undefined ? {} : { wakeTicking: options.wakeTicking }),
+        });
+    }
+    catch (error) {
+        const failures = [error];
+        if (mcp)
+            await mcp.close().catch((cleanup) => failures.push(cleanup));
+        await storage.close(BACKGROUND_CONTEXT).catch((cleanup) => failures.push(cleanup));
+        throw failures.length === 1 ? error : new AggregateError(failures, "Agent open and cleanup failed");
+    }
+    // A storage failure or a direct harness close also ends the resources this open acquired.
+    void agent.harness.closed
+        .then(() => mcp.close())
+        .catch((error) => {
+        log.warn(`[fastagent] MCP cleanup after harness shutdown failed: ${String(error)}`);
     });
+    const closeAgent = agent.close.bind(agent);
+    let closing;
+    agent.close = () => (closing ??= (async () => {
+        const failures = [];
+        await closeAgent().catch((error) => failures.push(error));
+        await mcp.close().catch((error) => failures.push(error));
+        if (failures.length)
+            throw new AggregateError(failures, "Agent close failed");
+    })());
     return {
         agent,
         definition,
+        name,
         code,
+        config,
+        secrets,
         models,
         content,
-        agentDir: dir,
+        agentDir: projectDir,
+        workdir,
         stateRoot,
         channels: code.channels,
         schedules: code.schedules,
     };
 }
-/** `stateDir` read as `FASTAGENT_STATE_DIR` is: `~` is the home directory, a relative one resolves against the cwd. */
-function stateDirOf(stateDir) {
-    const resolved = resolveOverridePath(stateDir);
-    if (resolved === undefined)
-        throw new Error("stateDir needs the directory the instance's state is kept in");
-    return resolved;
+/** The `config` input as a source: an object as it is, a path (absolute, like every path here) read. */
+async function configOf(config) {
+    if (config === undefined)
+        return undefined;
+    if (typeof config !== "string")
+        return { values: config, label: "the config object" };
+    if (!isAbsolute(config))
+        throw new Error(`config must be an absolute path, and is ${JSON.stringify(config)}`);
+    return readInstanceConfigFile(config);
+}
+/** Where the instance is, every path absolute: a relative one would be an input the process's cwd chooses. */
+function locationOf(location) {
+    const absolute = (path, name) => {
+        if (typeof path !== "string" || !isAbsolute(path)) {
+            throw new Error(`${name} must be an absolute path, and is ${JSON.stringify(path)}`);
+        }
+        return path;
+    };
+    if ("root" in location && ("stateDir" in location || "workdir" in location)) {
+        throw new Error("give the instance a root, or a stateDir and a workdir, not both");
+    }
+    if ("root" in location) {
+        const root = absolute(location.root, "root");
+        return { workdir: root, stateRoot: join(root, STATE_DIRNAME) };
+    }
+    return { workdir: absolute(location.workdir, "workdir"), stateRoot: absolute(location.stateDir, "stateDir") };
 }
 /**
- * Open the agent directory `dir` the way `dev` and `start` do before they serve: its definition, its code built with
- * the secrets it declares, its environment, its content and the instance's storage, which one process holds at a time.
- * Nothing reaches the agent until `serve`.
+ * Open one instance of `definition`, the default export of an agent's package, the way `dev` and `start` do before they
+ * serve: its code built with the secrets it declares, its environment, its content and the instance's storage, which
+ * one process holds at a time. Nothing reaches the agent until `serve`.
  */
-export async function openAgent(dir, options = {}) {
+export async function openAgent(definition, options) {
+    const { workdir, stateRoot } = locationOf(options);
+    const config = await configOf(options.config);
     // An app may never serve the agent, and then no clock fires a wake-up: `wake` is refused until it does.
     let ticking = false;
-    const opened = await openServing(dir, {
+    const opened = await openServing(assertDefinition(definition), {
+        workdir,
+        stateRoot,
+        secrets: options.secrets ?? {},
+        env: options.env ?? {},
+        ownEnv: options.env ?? {},
+        runsAs: NOT_HOSTED,
+        offline: options.offline === true,
+        ...(options.name === undefined ? {} : { name: options.name }),
+        ...(config === undefined ? {} : { config }),
         wakeTicking: () => ticking,
+        keeps: "state",
+        ...(options.mcp === undefined ? {} : { mcp: options.mcp }),
         ...(options.model === undefined ? {} : { model: options.model }),
         ...(options.credentials === undefined ? {} : { credentialStore: piCredentials(options.credentials) }),
-        ...(options.stateDir === undefined ? {} : { stateRoot: stateDirOf(options.stateDir) }),
     });
     const { agent } = opened;
     let served;

package/dist/harnesses/pi-durable/sessions.js

@@ -20,20 +20,23 @@ export const trackSessions = (harness, storage, context) => Effect.gen(function*
         if (value > (newest.get(id) ?? 0))
             newest.set(id, value);
     };
-    // Subscribed before the scan, so a commit while it reads is not lost: either reports the newest id, and the
+    // Observed before the scan, so a commit while it reads is not lost: either reports the newest id, and the
     // larger stands. A change's conversation may be created in the same commit, so membership is not checked here.
-    yield* Effect.acquireRelease(Effect.sync(() => harness.subscribeCommits(({ changes }) => {
-        for (const change of changes) {
-            if (change.type === "conversation") {
-                if (isSession(change.value))
-                    sessions.add(change.value.id);
-                touch(change.value.id, change.value.id);
+    yield* Effect.acquireRelease(Effect.sync(() => harness.observeCommits({
+        advance: ({ changes }) => {
+            for (const change of changes) {
+                if (change.type === "conversation") {
+                    if (isSession(change.value))
+                        sessions.add(change.value.id);
+                    touch(change.value.id, change.value.id);
+                }
+                else if (change.type === "entry" || change.type === "submission") {
+                    touch(change.value.conversationId, change.value.id);
+                }
             }
-            else if (change.type === "entry" || change.type === "submission") {
-                touch(change.value.conversationId, change.value.id);
-            }
-        }
-    })), (unsubscribe) => Effect.sync(unsubscribe));
+        },
+        end: () => { },
+    })), (observation) => Effect.sync(() => observation.detach()));
     yield* conversations(storage, context).pipe(Stream.filter(isSession), Stream.runForEach((conversation) => storedActivity(storage, context, conversation).pipe(Effect.tap((activity) => Effect.sync(() => {
         sessions.add(conversation.id);
         touch(conversation.id, activity);

package/dist/harnesses/pi-durable/text-sources.d.ts

@@ -0,0 +1,30 @@
+import type { InstanceConfigSource } from "./config.ts";
+export interface TextSource {
+    /** Absolute: a file of instructions, or a directory of skills or of prompt templates. */
+    path: string;
+    /** The instance configuration that declared it, and so expects it to exist. None for the program's own. */
+    declaredBy?: string;
+    /** The path as the configuration wrote it. */
+    given?: string;
+}
+/** Each kind's sources in the order they load: the program's first, so a later one never replaces its entries. */
+export interface TextSources {
+    instructions: readonly TextSource[];
+    skills: readonly TextSource[];
+    prompts: readonly TextSource[];
+}
+export declare const NOUN: {
+    readonly instructions: "file";
+    readonly skills: "directory";
+    readonly prompts: "directory";
+};
+/** The program's own text, which `AGENTS.md` and `SYSTEM.md` already put in the prompt. */
+export declare function programText(dir: string): TextSources;
+/** What `path` is: a file, a directory, or nothing. */
+export declare function whatIs(path: string): "file" | "directory" | undefined;
+/**
+ * The text of the program in `dir` and of `instance` (whose shape `resolveConfig` has checked): each declared path
+ * resolved against the configuration's directory, and refused when it is not what its kind names or is text the
+ * program already loads, which would load twice.
+ */
+export declare function declareText(dir: string, instance: InstanceConfigSource | undefined): TextSources;

package/dist/harnesses/pi-durable/text-sources.js

@@ -0,0 +1,55 @@
+/**
+ * Where an instance's text is (agent-artifact.md §4.2, §7): the program's own `skills/` and `prompts/`, then what the
+ * instance configuration's `instructions`, `skills` and `prompts` name. Resolved once, at open, into absolute paths, so
+ * the readers (text.ts) read exactly these for each message and scan nothing else.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { configurationPath, isUnderDir } from "../../paths.js";
+export const NOUN = { instructions: "file", skills: "directory", prompts: "directory" };
+/** The program's own text, which `AGENTS.md` and `SYSTEM.md` already put in the prompt. */
+export function programText(dir) {
+    return { instructions: [], skills: [{ path: join(dir, "skills") }], prompts: [{ path: join(dir, "prompts") }] };
+}
+/** What `path` is: a file, a directory, or nothing. */
+export function whatIs(path) {
+    try {
+        return statSync(path).isDirectory() ? "directory" : "file";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The text of the program in `dir` and of `instance` (whose shape `resolveConfig` has checked): each declared path
+ * resolved against the configuration's directory, and refused when it is not what its kind names or is text the
+ * program already loads, which would load twice.
+ */
+export function declareText(dir, instance) {
+    const program = programText(dir);
+    const values = typeof instance?.values === "object" ? instance.values : {};
+    if (instance === undefined)
+        return program;
+    const programsOwn = ["SYSTEM.md", "AGENTS.md", "skills", "prompts"].map((name) => join(dir, name));
+    const declared = (kind) => (values[kind] ?? []).map((given) => {
+        const at = `${instance.label}: ${kind} "${given}"`;
+        const path = configurationPath(given, instance.directory);
+        if (path === undefined) {
+            throw new Error(`${at} must be absolute here, since ${instance.label} is not a file its directory could anchor`);
+        }
+        if (whatIs(path) !== NOUN[kind])
+            throw new Error(`${at} (${path}) is not a ${NOUN[kind]}`);
+        const own = programsOwn.find((text) => isUnderDir(path, text));
+        if (own !== undefined) {
+            throw new Error(`${at} (${path}) is the program's own text (${own}), which loads already: declare another`);
+        }
+        return { path, declaredBy: instance.label, given };
+    });
+    return {
+        instructions: declared("instructions"),
+        skills: [...program.skills, ...declared("skills")],
+        prompts: [...program.prompts, ...declared("prompts")],
+    };
+}

package/dist/harnesses/pi-durable/text.d.ts

@@ -1,6 +1,9 @@
 import { type PromptSection } from "@earendil-works/pi-durable";
 import type { ResolvedContent } from "../../content/resolve.ts";
+import type { RunsAs } from "../../serving-command.ts";
 import type { AgentCommand } from "./agent.ts";
+import type { InstanceConfigSource } from "./config.ts";
+import { type TextSource, type TextSources } from "./text-sources.ts";
 export interface Skill {
     name: string;
     description: string;
@@ -10,8 +13,13 @@ export interface Skill {
     /** Offered only through `/skill:<name>`, never listed to the model. */
     disableModelInvocation: boolean;
 }
-/** The agent's skills: `skills/<name>/SKILL.md`. One that breaks the specification is reported and skipped. */
-export declare function readSkills(agentDir: string): Skill[];
+/** The skills the agent offers, reported and skipped as above. */
+export declare const readSkills: (sources: readonly TextSource[]) => Skill[];
+/**
+ * The instance's text as it will be read: declared, and refused when an instance entry takes a name the program (or an
+ * earlier instance entry) has. Called at open; what goes wrong afterwards is reported as each message reads it.
+ */
+export declare function openText(dir: string, instance: InstanceConfigSource | undefined): TextSources;
 /** Arguments as a shell splits them: by whitespace, with `"…"` or `'…'` keeping one argument together. */
 export declare function parseArguments(text: string): string[];
 /**
@@ -20,11 +28,15 @@ export declare function parseArguments(text: string): string[];
  */
 export declare function expandTemplate(body: string, args: readonly string[]): string;
 /** What a Caller may offer as `/<name>`: the prompt templates, then `skill:<name>` for each skill. */
-export declare function readCommands(agentDir: string): AgentCommand[];
+export declare function readCommands(text: TextSources): AgentCommand[];
 /**
  * The prompt the definition contributes: `SYSTEM.md` as written, `AGENTS.md` as project context, the skills, where it
- * works, and, deployed, what of a change it makes to itself lasts. `wake`: the agent has the wake tool.
+ * works, and, deployed, what of a change it makes to itself lasts. `wake`: the agent has the wake tool; `runsAs` says
+ * whether it is deployed, and where.
  */
 export declare function definitionSections(agentDir: string, content: readonly ResolvedContent[], options: {
     wake: boolean;
+    runsAs: RunsAs;
+    workdir?: string;
+    text?: TextSources;
 }): PromptSection[];