@fastagent-sh/fastagent 0.27.0 → 0.28.0

package/README.md

@@ -152,9 +152,9 @@ The package exports the supported surface only, from one entry per kind of user,
 | The Agent API | `Agent`, `AgentError` ([Agent API](docs/SPEC.md)) | Stable within its version |
 | Directory → agent → service | `openAgent`, `LocalAgent`, `serve()`'s `Service` (`fetch`, `listen`) | Usable now, may tighten before 1.0 |
 | Over HTTP | `connectAgent` (`/client`), the `/v1` routes ([Agent API](docs/SPEC.md) §9) | Stable within its version |
-| A host embedding agents | `createAgent`, `CredentialStore`, `credentialFile`, `signIn`, `signInOptions`, `providerAuth` ([embedding](docs/embedding.md#6-a-desktop-host)) | Usable now, may tighten before 1.0 |
+| A host embedding agents | `createAgent`, `addContent`, `removeContent`, `listContent`, `CredentialStore`, `credentialFile`, `signIn`, `signInOptions`, `providerAuth` ([embedding](docs/embedding.md#6-a-desktop-host)) | Usable now, may tighten before 1.0 |
 | Authoring | `defineAgent`, `defineChannel`, `defineSchedule`, `needs`, `sessionIdOf`, `readBodyCapped`, `text`, `secretEquals` | Usable now, may tighten before 1.0 |
-| Not exported | The assembly's parts (`router`, `createScheduler`), content editing, the model environment, harness internals | No compatibility promise |
+| Not exported | The assembly's parts (`router`, `createScheduler`), the environment's edit (`writeEnvironment`), the model environment, harness internals | No compatibility promise |
 
 A tool or an extension is pi-durable's own (`defineTool`, `defineExtension` from `@earendil-works/pi-durable`), and a
 custom provider is pi-ai's (`createProvider` from `@earendil-works/pi-ai`): `init` adds both packages to the agent.

package/dist/authoring.d.ts

@@ -10,7 +10,7 @@ export declare class ContentNameError extends Error {
     name: string;
 }
 export interface InitAgentOptions {
-    /** What the agent works on and knows: repositories into `context.json`, this machine's directories into
+    /** What the agent works on: repositories into `context.json`, this machine's directories into
      *  `context.local.json`. */
     content?: ContentAddition[];
     /**
@@ -36,26 +36,33 @@ export interface CreatedAgent {
  * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
  * repository whose first commit is what was written, since the agent changes itself and version control is how its
  * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
+ *
+ * `content` gives it any number of entries, each a directory of this machine or a GitHub repository. They are all
+ * checked before anything is written, and one that is refused leaves no directory. Two entries may bind the same
+ * directory, or one inside the other; the agent then reaches it by both names.
  */
-export declare function createAgent(dir: string): Promise<CreatedAgent>;
+export declare function createAgent(dir: string, options?: {
+    content?: ContentAddition[];
+}): Promise<CreatedAgent & {
+    content: ResolvedContent[];
+}>;
 /**
- * {@link createAgent} with what `fastagent init` adds: content, and the install. Every content entry is checked before
+ * {@link createAgent} with what `fastagent init` adds: the install. Every content entry is checked before
  * anything is written, and the scaffold is removed again when writing the content fails.
  */
 export declare function initAgent(dir: string, options?: InitAgentOptions): Promise<CreatedAgent & {
     content: ResolvedContent[];
 }>;
 /**
- * The agent's content, resolved for this instance (what `fastagent content list` shows), and the directories this
- * machine binds that are not here: the agent is not told of those.
+ * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. Missing local directories
+ * are listed separately; an agent opened here is not told of them.
  */
 export declare function listContent(agentDir: string): Promise<{
     content: ResolvedContent[];
     absent: BoundContent[];
 }>;
 /**
- * What an edit leaves: the entry it added or removed, by name, the agent's content after it, and what to tell the
- * user about what was left on this machine.
+ * The edited declaration resolved for this machine; an already-open agent keeps its startup snapshot until reopened.
  */
 export interface ContentEdit {
     name: string;

package/dist/authoring.js

@@ -2,7 +2,8 @@
  * Creating an agent and editing its content: `fastagent init` and `fastagent content` are thin wrappers over these (and
  * `fastagent env` writes its declaration through {@link writeEnvironment}), so the rules live here, not in a command.
  * Nothing here prints or exits; every refusal is thrown with the message the CLI shows. The package exports
- * {@link createAgent}; the content and environment edits wait for context packages, whose shape they follow.
+ * {@link createAgent} and the content edits ({@link addContent}, {@link removeContent}, {@link listContent}), which
+ * give an agent its own entries, without an alias prefix; the environment's edit is not exported.
  */
 import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
@@ -28,13 +29,16 @@ export class ContentNameError extends Error {
  * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
  * repository whose first commit is what was written, since the agent changes itself and version control is how its
  * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
+ *
+ * `content` gives it any number of entries, each a directory of this machine or a GitHub repository. They are all
+ * checked before anything is written, and one that is refused leaves no directory. Two entries may bind the same
+ * directory, or one inside the other; the agent then reaches it by both names.
  */
-export async function createAgent(dir) {
-    const { content: _, ...created } = await initAgent(dir);
-    return created;
+export async function createAgent(dir, options = {}) {
+    return initAgent(dir, options.content === undefined ? {} : { content: options.content });
 }
 /**
- * {@link createAgent} with what `fastagent init` adds: content, and the install. Every content entry is checked before
+ * {@link createAgent} with what `fastagent init` adds: the install. Every content entry is checked before
  * anything is written, and the scaffold is removed again when writing the content fails.
  */
 export async function initAgent(dir, options = {}) {
@@ -69,8 +73,8 @@ export async function initAgent(dir, options = {}) {
     return { dir: agentDir, created, content, repository: await initRepository(agentDir) };
 }
 /**
- * The agent's content, resolved for this instance (what `fastagent content list` shows), and the directories this
- * machine binds that are not here: the agent is not told of those.
+ * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. Missing local directories
+ * are listed separately; an agent opened here is not told of them.
  */
 export async function listContent(agentDir) {
     const dir = resolveAgentDir(agentDir);

package/dist/cli/commands/content.js

@@ -1,5 +1,5 @@
 /**
- * `fastagent content list|add|remove`: what the agent works on and knows, as `context.json` declares it and
+ * `fastagent content list|add|remove`: what the agent works on, as `context.json` declares it and
  * `context.local.json` binds it on this machine.
  */
 import { resolve } from "node:path";

package/dist/cli/commands/invoke.js

@@ -8,14 +8,12 @@ import { AgentError } from "../../agent-api.js";
 import { enterAgentEnv } from "../../env.js";
 import { dotEnvPath, loadEnvValues } from "../../value-file.js";
 import { installProxyFetch } from "../../proxy.js";
-import { modelRefOf } from "../../harnesses/pi-durable/open.js";
-import { openServing } from "../../harnesses/pi-durable/serve.js";
+import { modelRefOf } from "../../model-ref.js";
 import { connectAgent } from "../../http/client.js";
 import { API_KEY_VARIABLE, apiKeysFrom } from "../../http/server.js";
 import { resolveStateRoot, selectAgentEnvironment } from "../../paths.js";
 import { runInvokeJson, runInvokeStream } from "../invoke-stream.js";
 import { failStartup, failUsage, optionalAgentDirOrExit } from "../fail.js";
-import { enterAgentCommand, reportAuth } from "../shared.js";
 /**
  * `invoke`'s sessions, apart from the instance's storage, so `invoke` runs beside a serve of this directory, which holds
  * that one; one `invoke` at a time holds this one.
@@ -112,6 +110,10 @@ export async function runInvoke(message, dirArg, opts) {
         return runRemoteInvoke(message, dirArg, { ...opts, url: opts.url });
     if (opts.key !== undefined)
         failUsage("--key is the key --url calls with: pass --url too");
+    const [{ openServing }, { enterAgentCommand, reportAuth }] = await Promise.all([
+        import("../../harnesses/pi-durable/serve.js"),
+        import("../shared.js"),
+    ]);
     const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts);
     const file = invokeStorageFile(resolveStateRoot(agentDir));
     const { agent, models, definition } = await openServing(agentDir, {

package/dist/cli/content-view.d.ts

@@ -2,7 +2,7 @@
 import type { BoundContent } from "../content/declare.ts";
 import { type ResolvedContent } from "../content/resolve.ts";
 /**
- * The report lines for an agent's content — `works on` / `knows`, one per entry, then a `notice` line for each
+ * The report lines for an agent's content — `works on`, one per entry, then a `notice` line for each
  * thing its resolution has to say, then one for each directory this machine binds that is not here — shared by the
  * startup report, `info` and `content list`, so the three say the same thing.
  */

package/dist/cli/content-view.js

@@ -8,13 +8,13 @@ function contentKind(c) {
     return c.clone ? `${github}, a clone brought up to date at each start` : `${github}, your checkout bound here`;
 }
 /**
- * The report lines for an agent's content — `works on` / `knows`, one per entry, then a `notice` line for each
+ * The report lines for an agent's content — `works on`, one per entry, then a `notice` line for each
  * thing its resolution has to say, then one for each directory this machine binds that is not here — shared by the
  * startup report, `info` and `content list`, so the three say the same thing.
  */
 export function contentLines(content, absent = []) {
     const lines = content.flatMap((c) => [
-        [c.readonly ? "knows" : "works on", `${c.name.padEnd(width(content))}  ${c.location} (${contentKind(c)})`],
+        ["works on", `${c.name.padEnd(width(content))}  ${c.location} (${contentKind(c)})`],
         ...c.notices.map((notice) => ["notice", `${c.name}: ${notice}`]),
     ]);
     for (const binding of absent)

package/dist/cli/program.js

@@ -56,7 +56,7 @@ const init = {
     ],
     notes: "An agent is a directory holding a fastagent.config.ts, and it is also the agent's working directory. " +
         "It lives in a directory of its own, never inside a project or another agent: what it works on is declared " +
-        "as its content. Add a directory it only knows later with `fastagent content add <dir> --readonly`.",
+        "as its content. Add a directory later with `fastagent content add <dir>`.",
     run: async (args, f) => (await import("./commands/init.js")).runInit(args[0], {
         install: f.install !== false,
         content: f.content ?? [],
@@ -434,14 +434,14 @@ const env = {
 };
 const content = {
     name: "content",
-    summary: "list, add or remove what the agent works on and knows",
-    description: "Content is a directory the agent works on (or only knows, with --readonly): a GitHub repository declared " +
+    summary: "list, add or remove what the agent works on",
+    description: "Content is a directory the agent works on: a GitHub repository declared " +
         "by name in context.json, shared with the agent and cloned at content/<name>, or a directory of this " +
         "machine bound in context.local.json, which never leaves it.",
     subcommands: [
         {
             name: "list",
-            summary: "each content entry, where it is, and whether the agent works on it or only knows it",
+            summary: "each content entry and where it is",
             args: [AGENT_ARG],
             flags: [JSON_FLAG],
             examples: [{ cmd: "fastagent content list" }],
@@ -452,15 +452,13 @@ const content = {
             summary: "add a GitHub repository, or bind a directory of this machine, as content",
             args: [{ name: "<source>", description: "a directory, or github:owner/repo" }, AGENT_ARG],
             flags: [
-                { flags: "--readonly", description: "the agent knows it and does not write it" },
                 { flags: "--ref <ref>", description: "a repository: the branch, tag or commit to clone" },
                 { flags: "--name <name>", description: "its name (default: the directory's or repository's)" },
                 { flags: "--description <text>", description: "one sentence for the agent: what it is, how to treat it" },
             ],
             examples: [
-                { cmd: "fastagent content add ~/code/app", note: "works on" },
-                { cmd: "fastagent content add ~/handbook --readonly", note: "knows" },
-                { cmd: "fastagent content add github:acme/docs --readonly", note: "knows a clone" },
+                { cmd: "fastagent content add ~/code/app", note: "a directory of this machine" },
+                { cmd: "fastagent content add github:acme/docs", note: "a clone" },
             ],
             notes: "The root of a GitHub checkout is declared in context.json as that repository, and bound in " +
                 "context.local.json to the checkout, used as it is on this machine. github:owner/repo is cloned into " +
@@ -469,7 +467,6 @@ const content = {
                 "Any other directory is bound in context.local.json only: a deployed instance works without it. A bound " +
                 "directory may not contain the agent directory, nor sit inside it.",
             run: async (args, f) => (await import("./commands/content.js")).runContentAdd(args[0], args[1], {
-                readonly: f.readonly === true,
                 ...(typeof f.ref === "string" ? { ref: f.ref } : {}),
                 ...(typeof f.name === "string" ? { name: f.name } : {}),
                 ...(typeof f.description === "string" ? { description: f.description } : {}),

package/dist/content/declare.d.ts

@@ -4,8 +4,6 @@ export interface ContentEntry {
     github: string;
     /** The branch, tag or commit to clone. */
     ref?: string;
-    /** The agent knows it and does not write it. */
-    readonly?: boolean;
     /** One sentence for the agent: what this is, and how to treat it. */
     description?: string;
 }
@@ -15,7 +13,6 @@ export interface DeclaredContent {
     /** `owner/repo`. */
     repo: string;
     ref?: string;
-    readonly: boolean;
     description?: string;
 }
 /**
@@ -25,7 +22,6 @@ export interface DeclaredContent {
 export interface ContentBinding {
     /** Absolute, `~/`, or relative to the agent directory. */
     path: string;
-    readonly?: boolean;
     description?: string;
 }
 /** A binding, read: `path` absolute. */
@@ -38,7 +34,6 @@ export type BoundContent = {
 } | {
     /** A directory only this machine has. */
     kind: "local";
-    readonly: boolean;
     description?: string;
 });
 /** What an agent's content is declared as: the shared declaration, and this machine's bindings. */
@@ -64,7 +59,7 @@ export declare function declareContent(raw: unknown): DeclaredContent[];
 export declare function declareBindings(raw: unknown, declared: readonly DeclaredContent[], agentDir: string): BoundContent[];
 /**
  * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is
- * released, writable content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
+ * released, content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
  * it of the real paths.
  */
 export declare function nestingError(agentDir: string, location: string, name: string): string | undefined;

package/dist/content/declare.js

@@ -1,5 +1,5 @@
 /**
- * WHAT AN AUTHOR DECLARES an agent works on or knows, read and refused in ONE place (file.ts reads the files through
+ * WHAT AN AUTHOR DECLARES an agent works on, read and refused in ONE place (file.ts reads the files through
  * it): the `content` map of `context.json`, which is shared and so holds only repositories every instance reaches, and
  * the `content` map of `context.local.json`, the directories of this machine it is bound to. Pure: what is on the disk
  * is resolve.ts's question. docs/design/agent-model.md §3 is the rule.
@@ -11,8 +11,8 @@ import { CONTEXT_FILE, LOCAL_CONTEXT_FILE, isUnderDir } from "../paths.js";
  * The keys an entry and a binding carry, in the order they are written: where it is, then how it is treated. One list
  * each, so a key the reader accepts is one the writer keeps.
  */
-const ENTRY_KEYS = ["github", "ref", "readonly", "description"];
-const BINDING_KEYS = ["path", "readonly", "description"];
+const ENTRY_KEYS = ["github", "ref", "description"];
+const BINDING_KEYS = ["path", "description"];
 /** A name becomes a directory name, so it is one path segment (the spelling a release's agent name has). */
 const NAME = /^[A-Za-z0-9_-]+$/;
 /** Whether `name` can name a content entry. */
@@ -62,16 +62,14 @@ export function declareBindings(raw, declared, agentDir) {
             if (shared.name !== name) {
                 throw new Error(`${at} binds the entry ${CONTEXT_FILE} names "${shared.name}": spell it the same`);
             }
-            for (const key of ["readonly", "description"]) {
-                if (e[key] !== undefined) {
-                    throw new Error(`${at} binds this machine's checkout of the entry ${CONTEXT_FILE} declares, which says "${key}" for ` +
-                        `every instance: give it only "path"`);
-                }
+            if (e.description !== undefined) {
+                throw new Error(`${at} binds this machine's checkout of the entry ${CONTEXT_FILE} declares, which says "description" for ` +
+                    `every instance: give it only "path"`);
             }
             return { name, path, kind: "checkout" };
         }
-        const treatment = treatmentOf(at, e);
-        return { name, path, kind: "local", ...treatment };
+        const description = descriptionOf(at, e);
+        return { name, path, kind: "local", ...(description !== undefined ? { description } : {}) };
     });
 }
 /** `path` as written in `context.local.json`, absolute: `~/` is the home directory, a relative one the agent's. */
@@ -112,14 +110,11 @@ function objectWithKeys(at, value, keys) {
     }
     return e;
 }
-function treatmentOf(at, e) {
+function descriptionOf(at, e) {
     if (e.description !== undefined && (typeof e.description !== "string" || e.description === "")) {
         throw new Error(`${at}: "description" must be a non-empty string`);
     }
-    if (e.readonly !== undefined && typeof e.readonly !== "boolean")
-        throw new Error(`${at}: "readonly" must be a boolean`);
-    const description = e.description;
-    return { readonly: e.readonly === true, ...(description !== undefined ? { description } : {}) };
+    return e.description;
 }
 function declareOne(name, entry) {
     const at = `content "${name}"`;
@@ -129,7 +124,7 @@ function declareOne(name, entry) {
             throw new Error(`${at}: "${key}" must be a non-empty string`);
         }
     }
-    const treatment = treatmentOf(at, e);
+    const description = descriptionOf(at, e);
     if (e.github === undefined) {
         throw new Error(`${at} needs "github": ${CONTEXT_FILE} is shared, so it declares only what every instance reaches — bind a ` +
             `directory of this machine in ${LOCAL_CONTEXT_FILE} instead (fastagent content add <dir>)`);
@@ -141,11 +136,11 @@ function declareOne(name, entry) {
     // git reads a leading "-" as an option, and no branch, tag or commit name has one.
     if (ref?.startsWith("-"))
         throw new Error(`${at}: "ref" must name a branch, tag or commit, got "${ref}"`);
-    return { name, repo, ...(ref !== undefined ? { ref } : {}), ...treatment };
+    return { name, repo, ...(ref !== undefined ? { ref } : {}), ...(description !== undefined ? { description } : {}) };
 }
 /**
  * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is
- * released, writable content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
+ * released, content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
  * it of the real paths.
  */
 export function nestingError(agentDir, location, name) {

package/dist/content/resolve.d.ts

@@ -4,8 +4,6 @@ import { type CloneOutcome } from "./git.ts";
 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. */

package/dist/content/resolve.js

@@ -33,10 +33,9 @@ export function absentNotice(binding) {
         `not told of it`);
 }
 function resolveRepository(agentDir, entry, checkout) {
-    const { name, readonly, description } = entry;
+    const { name, description } = entry;
     const repository = {
         name,
-        readonly,
         ...(description !== undefined ? { description } : {}),
         kind: "github",
         repo: entry.repo,
@@ -62,12 +61,11 @@ function resolveRepository(agentDir, entry, checkout) {
     return { ...repository, location, notices, clone: true };
 }
 function resolveLocal(agentDir, binding) {
-    const { name, readonly, description } = binding;
+    const { name, description } = binding;
     const location = realpathSync(binding.path);
     checkBinding(agentDir, name, location);
     return {
         name,
-        readonly,
         ...(description !== undefined ? { description } : {}),
         location,
         notices: [],

package/dist/content/source.d.ts

@@ -1,6 +1,5 @@
 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;

package/dist/content/source.js

@@ -14,7 +14,6 @@ import { checkoutOf, githubRepoOf } from "./git.js";
  */
 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 } : {};

package/dist/deploy/preflight.js

@@ -27,33 +27,25 @@ import { checkPackages, MISE_PACKAGE_NAMES, miseBinary, packageSpecs } from "../
 /**
  * What each content entry becomes on the host, one line each, so none is missing there unsaid (agent-model.md §3). A
  * repository `context.json` declares is cloned there, as on this machine without a checkout bound. A directory only
- * this machine binds stays here: the deployed agent works without it, which the line says and says how to change. One
- * the agent works on is a warning, since the deployed agent lacks data it was meant to work on; one it only knows, a
- * note.
+ * this machine binds stays here: the deployed agent works without it, which the line says and says how to change. It
+ * is a warning, since the deployed agent lacks data it was meant to work on.
  */
 function checkContent({ declared, bound }, storageResets, report) {
     for (const entry of declared) {
         const fate = storageResets
             ? "cloned afresh on every deployment, since the host's storage starts over; what the agent did not push is lost"
             : "cloned on the host, and brought up to date in place at each start";
-        report.note(`${roleOf(entry)} ${entry.name}: github ${entry.repo}${entry.ref ? `@${entry.ref}` : ""}, ${fate}`);
+        report.note(`works on ${entry.name}: github ${entry.repo}${entry.ref ? `@${entry.ref}` : ""}, ${fate}`);
     }
     for (const binding of bound) {
         if (binding.kind !== "local")
             continue;
-        const stays = `${roleOf(binding)} ${binding.name}: a directory of this machine (${binding.path}, bound in ` +
+        const stays = `works on ${binding.name}: a directory of this machine (${binding.path}, bound in ` +
             `${LOCAL_CONTEXT_FILE}), stays here, and the deployed agent works without it`;
-        if (binding.readonly) {
-            report.note(`${stays}; to ship what the agent reads there, copy it into the agent directory, which every release carries`);
-        }
-        else {
-            report.warn(`${stays}; to work on it from a host, move it to a GitHub repository and add it as github:owner/repo`);
-        }
+        report.warn(`${stays}; to work on it from a host, move it to a GitHub repository and add it as github:owner/repo, or copy ` +
+            `what it only needs to read there into the agent directory, which every release carries`);
     }
 }
-function roleOf(entry) {
-    return entry.readonly ? "knows" : "works on";
-}
 /**
  * What the image needs to install the packages the agent declares: the agent's own mise for linux in its package.json,
  * so the image's install brings it, packages FastAgent installs from, and a PyPI package's runtime. A machine without

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

@@ -1,5 +1,5 @@
 import type { ModelThinkingLevel, Models, Provider } from "@earendil-works/pi-ai";
-import { type Extension, type HarnessSettings, type ModelRef, type Storage, type ToolRegistration } from "@earendil-works/pi-durable";
+import { type Extension, type HarnessSettings, type Storage, type ToolRegistration } from "@earendil-works/pi-durable";
 import type { ResolvedContent } from "../../content/resolve.ts";
 import { type DeclaredSecret } from "../../declared-secrets.ts";
 import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
@@ -14,7 +14,6 @@ export interface AgentDefinition {
     config: AgentConfig;
     registry: Registry;
 }
-export declare function modelRefOf(spec: string, where: string): ModelRef;
 /** The agent package's `fastagent.config.ts`, checked; `{}` without one. */
 export declare function loadConfig(dir: string): Promise<AgentConfig>;
 /** The default model a process here runs with: `--model` > `FASTAGENT_MODEL` > the configuration's `model`. */
@@ -65,7 +64,7 @@ export declare function buildDefinitionShape(definition: AgentDefinition, env: N
 export declare function definitionProviders(agentDir: string, env?: NodeJS.ProcessEnv): Promise<Provider[]>;
 export interface AssembleAgentOptions {
     storage: Storage;
-    /** What the agent works on and knows (`context.json`'s content), resolved for this instance. */
+    /** What the agent works on (`context.json`'s content), resolved for this instance. */
     content?: readonly ResolvedContent[];
     /** The definition's code, built once with its secrets (`buildDefinition`). */
     code: BuiltDefinition;

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

@@ -25,6 +25,7 @@ import { channelModuleProblem } from "../../channels/discover.js";
 import { AGENT_CONFIG_FILE as CONFIG_FILE } from "../../paths.js";
 import { readPackageJson } from "../../runtime.js";
 import { DEV_SERVE_ENV } from "../../serving-command.js";
+import { modelRefOf } from "../../model-ref.js";
 import { MAX_SCHEDULES, scheduleConfigProblem } from "../../schedule/schedule.js";
 import { openDurableAgent } from "./agent.js";
 import { isNeeds } from "./define.js";
@@ -97,13 +98,6 @@ function checkConfig(config, file) {
     }
     return config;
 }
-export function modelRefOf(spec, where) {
-    const slash = typeof spec === "string" ? spec.indexOf("/") : -1;
-    if (slash < 1 || slash === spec.length - 1) {
-        throw new Error(`${where} must be "provider/modelId", got ${JSON.stringify(spec)}`);
-    }
-    return { provider: spec.slice(0, slash), modelId: spec.slice(slash + 1) };
-}
 /** The agent package's `fastagent.config.ts`, checked; `{}` without one. */
 export async function loadConfig(dir) {
     const configPath = join(dir, CONFIG_FILE);

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

@@ -39,7 +39,7 @@ export interface OpenedServing {
     definition: AgentDefinition;
     code: BuiltDefinition;
     models: ModelEnvironment;
-    /** What the agent works on and knows, resolved for this instance. */
+    /** What the agent works on, resolved for this instance. */
     content: readonly ResolvedContent[];
     agentDir: string;
     /** Where the instance's state is: its storage, its channels' and schedules' state, its wake-ups. */

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

@@ -263,14 +263,12 @@ function contentKind(c) {
     // changes stays, and reaches anyone else only when pushed. The declared ref is what it follows, not a claim about
     // where it is: a clone the agent moved elsewhere is left there.
     const clone = `a shallow clone of github ${c.repo}${c.ref ? ` (declared ${c.ref})` : ""} in your own storage`;
-    return c.readonly
-        ? `${clone}, brought up to date each time you start`
-        : `${clone}: what you change in it stays, and each time you start it is brought up to date where that touches nothing of yours; push to share a change`;
+    return `${clone}: what you change in it stays, and each time you start it is brought up to date where that touches nothing of yours; push to share a change`;
 }
 /**
  * Where the agent is and what it works on (agent-model.md §4): its own directory is itself, and each content entry is named
- * with its location, whether it is the agent's to change, and where a change there goes. A result written where it
- * does not last is how knowledge gets lost, so the agent is told which is which.
+ * with its location and where a change there goes. A result written where it does not last is how knowledge gets
+ * lost, so the agent is told which is which.
  */
 function contentSection({ agentDir, content }) {
     const own = `Your working directory, ${agentDir}, is your own directory: it holds your definition, and files you create ` +
@@ -278,15 +276,11 @@ function contentSection({ agentDir, content }) {
     if (content.length === 0)
         return `${own} Nothing else is declared for you: you work only in your own directory.`;
     const line = (c) => `- ${c.name}: ${c.location} (${contentKind(c)})${c.description !== undefined ? ` ${c.description}` : ""}`;
-    const worksOn = content.filter((c) => !c.readonly);
-    const knows = content.filter((c) => c.readonly);
     return [
         own,
-        ...(worksOn.length > 0 ? ["You work on:", ...worksOn.map(line)] : []),
-        ...(knows.length > 0 ? ["You know, and do not write:", ...knows.map(line)] : []),
-        `Run a command in one of these directories with \`cd <its location> && …\`; file tools take the location directly.` +
-            (worksOn.length > 0
-                ? " A result worth keeping belongs in a directory you work on, not in your own directory."
-                : " You write only in your own directory: the directories above are for reading."),
+        "You work on:",
+        ...content.map(line),
+        `Run a command in one of these directories with \`cd <its location> && …\`; file tools take the location directly. ` +
+            `A result worth keeping belongs in a directory you work on, not in your own directory.`,
     ].join("\n");
 }

package/dist/index.d.ts

@@ -7,7 +7,11 @@ export type { Agent, AgentErrorData, AgentInfo, CompactOptions, ContentPart, Cre
 export { AgentError, LIMITS, hasEnded } from "./agent-api.ts";
 export { openAgent, type LocalAgent, type OpenAgentOptions, type ServeAgentOptions, } from "./harnesses/pi-durable/serve.ts";
 export type { Service } from "./service.ts";
-export { createAgent, type CreatedAgent } from "./authoring.ts";
+export { ContentNameError, addContent, createAgent, listContent, removeContent, type ContentEdit, type CreatedAgent, } from "./authoring.ts";
+export type { ContentAddition, SourceOptions } from "./content/source.ts";
+export { readContentSource } from "./content/source.ts";
+export type { BoundContent, ContentBinding, ContentEntry } from "./content/declare.ts";
+export type { ResolvedContent } from "./content/resolve.ts";
 export { SignInCancelled, type Credential, type CredentialStore, type ProviderAuth, type SignInEvent, type SignInInteraction, type SignInMethod, type SignInOption, type SignInPrompt, type SignInRequest, type SignInResult, } from "./sign-in-api.ts";
 export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.ts";
 export { defineAgent, defineSchedule, needs, type AgentConfig, type Needs, type SecretSpec, type SecretValues, } from "./harnesses/pi-durable/define.ts";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { AgentError, LIMITS, hasEnded } from "./agent-api.js";
 export { openAgent, } from "./harnesses/pi-durable/serve.js";
-export { createAgent } from "./authoring.js";
+export { ContentNameError, addContent, createAgent, listContent, removeContent, } from "./authoring.js";
+export { readContentSource } from "./content/source.js";
 export { SignInCancelled, } from "./sign-in-api.js";
 export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.js";
 export { defineAgent, defineSchedule, needs, } from "./harnesses/pi-durable/define.js";

package/dist/model-ref.d.ts

@@ -0,0 +1,3 @@
+/** Model selection syntax shared by a local definition and a remote Caller, without loading a harness. */
+import type { ModelRef } from "./agent-api.ts";
+export declare function modelRefOf(spec: string, where: string): ModelRef;

package/dist/model-ref.js

@@ -0,0 +1,7 @@
+export function modelRefOf(spec, where) {
+    const slash = typeof spec === "string" ? spec.indexOf("/") : -1;
+    if (slash < 1 || slash === spec.length - 1) {
+        throw new Error(`${where} must be "provider/modelId", got ${JSON.stringify(spec)}`);
+    }
+    return { provider: spec.slice(0, slash), modelId: spec.slice(slash + 1) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.27.0",
+  "version": "0.28.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",