@fastagent-sh/fastagent 0.29.0 → 0.30.1

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

@@ -1,4 +1,4 @@
-import { watchEvents, } from "@earendil-works/pi-durable";
+import { AgentDoc, InboxDoc, LiveDoc, UsageDoc, } from "@earendil-works/pi-durable";
 import * as Effect from "effect/Effect";
 import * as Queue from "effect/Queue";
 import * as Stream from "effect/Stream";
@@ -6,6 +6,8 @@ import { AgentError, agentError, errorData } from "../../agent-api.js";
 import { port, portError } from "../../effect-port.js";
 import { isPublished, replyText, thinkingOf } from "./entries.js";
 import { hasEnded, isInput, sessionOf } from "./messages.js";
+/** Revisions a Caller may leave unread before its stream ends: pi-durable keeps no bound for a synchronous observer. */
+const UNREAD_REVISIONS = 1000;
 /**
  * The session's events after the entry `after` names (`"start"`: every entry; absent: none). An unknown session or
  * entry, and a storage that fails before the snapshot, fail the stream; a failure after it is a `stream_error`.
@@ -25,22 +27,30 @@ export function sessionEvents({ harness, reads, ids, context, failureOf, maxRetr
             }
             after = entry.id;
         }
-        const batches = yield* Effect.acquireRelease(Queue.bounded(1), Queue.shutdown);
-        const watch = yield* Effect.acquireRelease(port(() => watchEvents(harness, conversation.id, context)), (stream) => Effect.promise(() => stream.stop()));
-        // Taking one batch at a time keeps pi-durable's own bound on what a slow Caller leaves undelivered.
-        watch.start((events) => Effect.runPromiseExit(Queue.offer(batches, { events })).then(() => undefined));
-        void watch.closed.then((end) => Effect.runPromiseExit(Queue.offer(batches, { end })));
-        const { snapshot } = watch;
-        const newest = snapshot.entries.reduce((max, entry) => (max === undefined || entry.id > max ? entry.id : max), undefined);
-        const live = liveTranslator(reads, maxRetries, snapshot);
+        const pending = yield* Effect.acquireRelease(Queue.unbounded(), Queue.shutdown);
+        let behind = false;
+        const observation = yield* Effect.acquireRelease(port(() => harness.observeConversation(conversation.id, {
+            advance: (call) => {
+                if (behind || call.kind !== "value")
+                    return;
+                behind = Queue.sizeUnsafe(pending) >= UNREAD_REVISIONS;
+                Queue.offerUnsafe(pending, behind ? { behind } : { view: call.value });
+            },
+            end: (end) => {
+                Queue.offerUnsafe(pending, { end });
+            },
+        }, context)), (attached) => Effect.sync(() => attached.detach()));
+        const snapshot = observation.value;
+        const newest = newestEntry(snapshot);
+        const live = liveTranslator(harness, reads, conversation, context, maxRetries, snapshot);
         const replay = after === undefined || newest === undefined || after >= newest
             ? Stream.empty
             : replayed(reads, conversation, after, newest);
         const present = Stream.succeed({
             type: "state",
-            session: sessionOf(ids.encode(conversation.id), snapshot, snapshot.usage, snapshot.agent),
+            session: sessionOf(ids.encode(conversation.id), docOf(snapshot, LiveDoc), docOf(snapshot, UsageDoc), docOf(snapshot, AgentDoc)),
         });
-        const events = Stream.fromQueue(batches).pipe(Stream.mapEffect((batch) => "end" in batch ? Effect.succeed([ended(batch.end)]) : live.translate(batch.events)), Stream.flattenIterable);
+        const events = Stream.fromQueue(pending).pipe(Stream.mapEffect((next) => ("view" in next ? live.translate(next.view) : Effect.succeed([ended(next)]))), Stream.flattenIterable);
         return Stream.concat(Stream.concat(replay, present), events).pipe(Stream.catchCause((cause) => Stream.succeed(streamError(failureOf(portError(cause))))), Stream.takeUntil((event) => event.type === "stream_error"));
     }).pipe(Effect.catchCause((cause) => {
         const error = portError(cause);
@@ -49,15 +59,22 @@ export function sessionEvents({ harness, reads, ids, context, failureOf, maxRetr
 }
 const streamError = (error) => ({ type: "stream_error", error: errorData(error) });
 function ended(end) {
-    switch (end.reason) {
-        case "session_failed":
-            return streamError(agentError("unavailable", `The agent's storage failed: ${String(end.error)}`));
+    if ("behind" in end) {
+        return streamError(agentError("unavailable", "This stream fell behind the session; continue after its last entry"));
+    }
+    switch (end.end.kind) {
+        case "failed":
+            return streamError(agentError("unavailable", `The agent stopped serving this session: ${String(end.end.error)}`));
         case "listener_error":
-            return streamError(agentError("internal", `Following the session failed: ${end.error.message}`));
+            return streamError(agentError("internal", `Following the session failed: ${end.end.error.message}`));
         default:
-            return streamError(agentError("unavailable", `The agent stopped serving this session (${end.reason})`));
+            return streamError(agentError("unavailable", `The agent stopped serving this session (${end.end.kind})`));
     }
 }
+/** The newest entry a view has seen: its window's last, or the one before an empty window. */
+function newestEntry(view) {
+    return view.entries.at(-1)?.id ?? view.before;
+}
 function replayed(reads, conversation, after, through) {
     return reads
         .publishedPages(conversation, {
@@ -68,145 +85,162 @@ function replayed(reads, conversation, after, through) {
         .pipe(Stream.mapEffect(reads.publish), Stream.flattenIterable, Stream.map(entryEvent));
 }
 const entryEvent = (entry) => ({ type: "entry", entry });
+/** A built-in document of the view, as its token types it. */
+const docOf = (view, token) => view.docs[token.definition.kind];
+const liveOf = (view) => docOf(view, LiveDoc);
+/** The inputs a view has not ended: queued in its inbox, or taken by its run. */
+function unendedInputs(view) {
+    const inbox = docOf(view, InboxDoc);
+    return new Set([
+        ...(inbox?.items ?? []).flatMap((item) => (item.mode === "write" ? [] : [item.id])),
+        ...(liveOf(view)?.run?.inputs ?? []),
+    ]);
+}
+/** A reply's text and thinking as a Caller has been shown them. */
+const shownOf = (content) => ({ text: replyText({ content }), thinking: thinkingOf({ content }) ?? "" });
 /**
- * What one commit's events add for a Caller: the reply's deltas, the tool calls that start and their status lines,
- * retries, the published entries, and a `done` for each message that ended, before the next message's entry.
+ * What one revision of the view adds for a Caller, against the revision before it: the reply's deltas, the tool calls
+ * that start and their status lines, retries, the entries appended, and a `done` for each message that ended, before
+ * the next message's entry.
  */
-function liveTranslator(reads, maxRetries, snapshot) {
-    let reply = [...(snapshot.generation?.message?.content ?? [])];
-    let shown = { text: replyText({ content: reply }), thinking: thinkingOf({ content: reply }) ?? "" };
-    const outputs = new Map(snapshot.tools.map((slot) => [slot.callId, slot.output ?? ""]));
-    const lines = new Map();
-    const outer = new Map(snapshot.nestedTools.map((slot) => [slot.callId, slot.parentCallId]));
+function liveTranslator(harness, reads, conversation, context, maxRetries, snapshot) {
+    const first = liveOf(snapshot);
+    let newest = newestEntry(snapshot);
+    let shown = shownOf(first?.generation?.message?.content ?? []);
+    let retry = retryKey(first);
+    let unended = unendedInputs(snapshot);
+    const toolArgs = new Map();
+    const started = new Set((first?.tools ?? []).filter((slot) => slot.status !== "pending").map((slot) => slot.callId));
+    const lines = new Map((first?.tools ?? []).flatMap((slot) => lineOf(slot.callId, slot.output)));
+    const nested = new Map((first?.nestedTools ?? []).map((slot) => [slot.callId, slot.parentCallId]));
     const outermost = (callId) => {
-        const parent = outer.get(callId);
+        const parent = nested.get(callId);
         return parent === undefined ? callId : outermost(parent);
     };
-    const restart = () => {
-        reply = [];
-        shown = { text: "", thinking: "" };
+    const learnToolArgs = (records) => {
+        for (const record of records) {
+            const model = record.model?.[0];
+            if (model?.role !== "assistant")
+                continue;
+            for (const block of model.content)
+                if (block.type === "toolCall")
+                    toolArgs.set(block.id, block.arguments);
+        }
+    };
+    learnToolArgs(snapshot.entries);
+    /**
+     * The answers that made calls now starting, read back through the history when the view's window began after them
+     * (a Caller attached late in a long round). A call no answer made stays unknown, and `toolEvents` refuses it.
+     */
+    const recallToolArgs = (live) => {
+        const missing = (live?.tools ?? []).filter((slot) => slot.status !== "pending" && !started.has(slot.callId) && !toolArgs.has(slot.callId));
+        if (missing.length === 0)
+            return Effect.void;
+        const known = () => missing.every((slot) => toolArgs.has(slot.callId));
+        return reads.history(conversation, { order: "descending" }).pipe(Stream.tap((record) => Effect.sync(() => learnToolArgs([record]))), Stream.takeUntil(known), Stream.runDrain);
     };
-    const deltas = () => {
-        const now = { text: replyText({ content: reply }), thinking: thinkingOf({ content: reply }) ?? "" };
-        const added = (channel) => now[channel].length > shown[channel].length && now[channel].startsWith(shown[channel])
-            ? [{ type: "delta", channel, text: now[channel].slice(shown[channel].length) }]
-            : [];
+    const deltas = (content) => {
+        const now = shownOf(content);
+        const added = (channel) => {
+            if (now[channel].length <= shown[channel].length)
+                return [];
+            const from = now[channel].startsWith(shown[channel]) ? shown[channel].length : 0;
+            return [{ type: "delta", channel, text: now[channel].slice(from) }];
+        };
         const events = [...added("thinking"), ...added("text")];
         shown = now;
         return events;
     };
-    const apply = (changes) => {
-        for (const change of changes) {
-            switch (change.type) {
-                case "message":
-                    reply = [...change.message.content];
-                    break;
-                case "text_start":
-                case "thinking_start":
-                case "toolcall_start":
-                case "block":
-                    reply[change.contentIndex] = change.block;
-                    break;
-                case "text_delta": {
-                    const block = reply[change.contentIndex];
-                    if (block?.type === "text")
-                        reply[change.contentIndex] = { ...block, text: block.text + change.delta };
-                    break;
-                }
-                case "thinking_delta": {
-                    const block = reply[change.contentIndex];
-                    if (block?.type === "thinking") {
-                        reply[change.contentIndex] = { ...block, thinking: block.thinking + change.delta };
-                    }
-                    break;
-                }
-                case "toolcall_delta":
-                    break;
-            }
-        }
-    };
     const progress = (toolCallId, text) => {
         if (text === undefined || lines.get(toolCallId) === text)
             return [];
         lines.set(toolCallId, text);
         return [{ type: "tool_progress", toolCallId, text }];
     };
+    const toolEvents = (live) => {
+        const events = [];
+        const tools = live?.tools ?? [];
+        for (const slot of tools) {
+            if (slot.status === "pending")
+                continue;
+            if (!started.has(slot.callId)) {
+                started.add(slot.callId);
+                const args = toolArgs.get(slot.callId);
+                if (args === undefined)
+                    throw new Error(`tool call ${slot.callId} started with no answer that made it`);
+                events.push({ type: "tool_started", toolCallId: slot.callId, name: slot.name, args });
+            }
+            if (slot.status === "running")
+                events.push(...progress(slot.callId, lastLine(slot.output ?? "")));
+        }
+        const calls = live?.nestedTools ?? [];
+        for (const slot of calls) {
+            if (nested.has(slot.callId))
+                continue;
+            nested.set(slot.callId, slot.parentCallId);
+            events.push(...progress(outermost(slot.callId), callLine(slot.name, slot.arguments)));
+        }
+        const current = new Set([...tools, ...calls].map((slot) => slot.callId));
+        for (const callId of [...started, ...lines.keys(), ...nested.keys(), ...toolArgs.keys()]) {
+            if (current.has(callId))
+                continue;
+            started.delete(callId);
+            lines.delete(callId);
+            nested.delete(callId);
+            toolArgs.delete(callId);
+        }
+        return events;
+    };
+    /** The entries `view` appended: its window's new ones, after those a window that moved past them left out. */
+    const appended = (view) => Effect.gen(function* () {
+        const fresh = view.entries.filter((entry) => newest === undefined || entry.id > newest);
+        const skipped = view.before === undefined || (newest !== undefined && view.before <= newest)
+            ? []
+            : yield* reads
+                .history(conversation, {
+                order: "ascending",
+                minEntryId: ((newest ?? 0) + 1),
+                maxEntryId: view.before,
+            })
+                .pipe(Stream.runCollect);
+        const records = [...skipped, ...fresh];
+        newest = records.at(-1)?.id ?? newest;
+        return records;
+    });
+    const endedMessages = (view, known) => {
+        const now = unendedInputs(view);
+        const gone = [...unended].filter((id) => !now.has(id));
+        unended = now;
+        return Effect.forEach(gone, (id) => port(async () => (await harness.submission(id, context))?.status(context)).pipe(Effect.flatMap((record) => isInput(record) && hasEnded(record) ? reads.message(record, known) : Effect.undefined))).pipe(Effect.map((messages) => messages.flatMap((message) => (message === undefined ? [] : [message]))));
+    };
     return {
-        translate: (events) => Effect.gen(function* () {
+        translate: (view) => Effect.gen(function* () {
+            const records = yield* appended(view);
+            learnToolArgs(records);
+            const live = liveOf(view);
             const before = [];
-            const entries = [];
-            const settled = [];
-            for (const [index, event] of events.entries()) {
-                switch (event.type) {
-                    case "snapshot":
-                        return [
-                            streamError(agentError("unavailable", "This stream fell behind the session; continue after its last entry")),
-                        ];
-                    case "message_start":
-                        // An entry's own start comes right before its end; any other is a new reply being written.
-                        if (events[index + 1]?.type !== "message_end" && event.message.role === "assistant") {
-                            reply = [...event.message.content];
-                            shown = { text: "", thinking: "" };
-                            before.push(...deltas());
-                        }
-                        break;
-                    case "message_update":
-                        apply(event.changes);
-                        before.push(...deltas());
-                        break;
-                    case "message_end":
-                    case "entry_appended":
-                        entries.push(event.entry);
-                        if (event.entry.model?.[0]?.role === "assistant")
-                            restart();
-                        break;
-                    case "tool_execution_start":
-                        if (event.parentToolCallId === undefined) {
-                            before.push({
-                                type: "tool_started",
-                                toolCallId: event.toolCallId,
-                                name: event.toolName,
-                                args: event.args,
-                            });
-                        }
-                        else {
-                            outer.set(event.toolCallId, event.parentToolCallId);
-                            before.push(...progress(outermost(event.toolCallId), callLine(event.toolName, event.args)));
-                        }
-                        break;
-                    case "tool_execution_update": {
-                        if (event.parentToolCallId !== undefined || event.output === undefined)
-                            break;
-                        const output = event.output;
-                        const current = outputs.get(event.toolCallId) ?? "";
-                        const next = "set" in output ? output.set : current.slice(output.trimStart ?? 0) + (output.append ?? "");
-                        outputs.set(event.toolCallId, next);
-                        before.push(...progress(event.toolCallId, lastLine(next)));
-                        break;
-                    }
-                    case "auto_retry_start":
-                        restart();
-                        before.push({
-                            type: "retrying",
-                            attempt: event.attempt,
-                            maxAttempts: maxRetries,
-                            delayMs: Math.max(0, event.at - Date.now()),
-                            reason: event.errorMessage,
-                        });
-                        break;
-                    case "tool_execution_end":
-                        outputs.delete(event.toolCallId);
-                        lines.delete(event.toolCallId);
-                        outer.delete(event.toolCallId);
-                        break;
-                    case "submission":
-                        if (isInput(event.record) && hasEnded(event.record))
-                            settled.push(event.record);
-                        break;
-                }
+            const nextRetry = retryKey(live);
+            if (nextRetry !== undefined && nextRetry !== retry && live?.generation?.retry !== undefined) {
+                shown = shownOf([]);
+                before.push({
+                    type: "retrying",
+                    attempt: live.generation.attempt,
+                    maxAttempts: maxRetries,
+                    delayMs: Math.max(0, live.generation.retry.at - Date.now()),
+                    reason: live.generation.retry.error,
+                });
+            }
+            retry = nextRetry;
+            const reply = live?.generation?.message?.content;
+            if (reply !== undefined)
+                before.push(...deltas(reply));
+            if (reply === undefined || records.some((record) => record.model?.[0]?.role === "assistant")) {
+                shown = shownOf([]);
             }
-            const published = yield* reads.publish(entries.filter(isPublished));
-            const dones = yield* Effect.forEach(settled, (record) => reads.message(record, entries));
+            yield* recallToolArgs(live);
+            before.push(...toolEvents(live));
+            const published = yield* reads.publish(records.filter(isPublished));
+            const dones = yield* endedMessages(view, records);
             // pi-durable places the next queued message in the commit that ends a run: its message's `done` goes first.
             const next = published.findIndex((entry) => entry.kind === "user");
             const at = next === -1 ? published.length : next;
@@ -219,6 +253,15 @@ function liveTranslator(reads, maxRetries, snapshot) {
         }),
     };
 }
+/** Which retry a generation waits for, so each is reported once. */
+function retryKey(live) {
+    const generation = live?.generation;
+    return generation?.retry === undefined ? undefined : `${generation.attempt}:${generation.retry.at}`;
+}
+function lineOf(callId, output) {
+    const line = lastLine(output ?? "");
+    return line === undefined ? [] : [[callId, line]];
+}
 /** The last line with text, a running tool's status. pi-durable's output already has no control characters. */
 function lastLine(text) {
     const lines = text.split("\n");

package/dist/harnesses/pi-durable/execution-env.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The agent's execution environment: pi-durable's local one, with the environment of every process it starts given
+ * outright. Its own `inheritEnv` would add this process's whole environment to a command's, and the bash tool asks for
+ * it on every call, so it is forced off here.
+ */
+import type { Context } from "@earendil-works/chord";
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+type Exec = NodeExecutionEnv["exec"];
+export declare class InstanceExecutionEnv extends NodeExecutionEnv {
+    #private;
+    constructor(options: {
+        cwd: string;
+        processEnv: Readonly<Record<string, string>>;
+    });
+    exec(command: Parameters<Exec>[0], options: Parameters<Exec>[1], context: Context): ReturnType<Exec>;
+}
+export {};

package/dist/harnesses/pi-durable/execution-env.js

@@ -0,0 +1,11 @@
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+export class InstanceExecutionEnv extends NodeExecutionEnv {
+    #processEnv;
+    constructor(options) {
+        super({ cwd: options.cwd });
+        this.#processEnv = options.processEnv;
+    }
+    exec(command, options, context) {
+        return super.exec(command, { ...options, inheritEnv: false, env: { ...this.#processEnv, ...options?.env } }, context);
+    }
+}

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

@@ -1,12 +1,10 @@
-/** MCP tools on pi-durable. No replay promise is inferred from a server's annotations. */
-import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-durable";
 import { McpError } from "../../mcp-api.js";
 export function mcpTools(tools) {
     return tools.map((tool) => defineTool({
         name: tool.name,
         description: tool.definition.description ?? `MCP tool ${tool.definition.name} from ${tool.server}`,
-        parameters: Type.Unsafe(tool.definition.inputSchema),
+        parameters: tool.definition.inputSchema,
         replay: "unsafe",
         execute: async (args, api, context) => {
             try {

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

@@ -1,38 +1,24 @@
 import type { ModelThinkingLevel, Models, Provider } from "@earendil-works/pi-ai";
 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";
+import type { RunsAs } from "../../serving-command.ts";
 import { type Schedule } from "../../schedule/schedule.ts";
 import { type DurableAgent, type Unfinished } from "./agent.ts";
-import { type AgentConfig } from "./define.ts";
-import { type Registry } from "./registry.ts";
-/** An agent package as it was read: where it is, its configuration, and the modules its registry lists. */
-export interface AgentDefinition {
-    dir: string;
-    name: string;
-    config: AgentConfig;
-    registry: Registry;
-}
-/** The agent package's `fastagent.config.ts`, checked; `{}` without one. */
-export declare function loadConfig(dir: string): Promise<AgentConfig>;
+import { type EffectiveConfig, type InstanceConfigSource } from "./config.ts";
+import { type AgentDefinition, type IngressConfig } from "./definition.ts";
+import { type TextSources } from "./text-sources.ts";
 /** The default model a process here runs with: `--model` > `FASTAGENT_MODEL` > the configuration's `model`. */
-export declare function modelSpecFor(config: AgentConfig, flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
-/** Read the agent package in `dir`: `fastagent.config.ts` (optional) and `.fastagent/registry.ts`, generated first. */
-export declare function loadDefinition(directory: string): Promise<AgentDefinition>;
-export declare function definitionSecrets(definition: AgentDefinition): DeclaredSecret[];
-/**
- * The list a person deploying or running the agent reads instead of its code (`.fastagent/secrets.json`): each name
- * once, what it is for, whether the agent runs without it, and where it is declared.
- */
-export declare function secretsManifest(definition: AgentDefinition): {
-    name: string;
-    description?: string;
-    optional: boolean;
-    declaredIn: string[];
-}[];
-/** Generate the registry, read the definition, and write its secrets manifest beside the registry. */
-export declare function prepareDefinition(dir: string): Promise<AgentDefinition>;
+export declare function modelSpecFor(config: Pick<EffectiveConfig, "model">, flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+/** A definition and the instance configuration it opens with: what a command resolves before it opens an agent. */
+export interface Project {
+    definition: AgentDefinition;
+    instance?: InstanceConfigSource;
+}
+/** The development project in `dir`, as `dev` opens it: its source and the `fastagent.json` at its root, if any. */
+export declare function loadDevProject(dir: string): Promise<Project>;
+/** The source project in `dir` as a definition: `fastagent.config.ts` (optional) and the modules of `src/`. */
+export declare function loadSourceDefinition(directory: string): Promise<AgentDefinition>;
 /** The definition's code, built with the values of the secrets it declares. */
 export interface BuiltDefinition {
     tools: ToolRegistration[];
@@ -43,30 +29,45 @@ export interface BuiltDefinition {
     /** What the scheduler fires, each named by its file. */
     schedules: Schedule[];
 }
+/** What a build reads of an instance's configuration: its settings, and how its channels receive. */
+export interface BuildConfig extends IngressConfig {
+    settings: Readonly<Record<string, unknown>>;
+}
 /**
  * Refuse to run while a required secret has no value, naming where it is declared; otherwise build every module with
- * the values it declared, and refuse one that is not what its directory holds.
+ * the values it declared, and refuse one that is not what its directory holds. A channel that receives either way is
+ * built the way `config` chooses, and only that way's secrets are asked for.
  */
-export declare function buildDefinition(definition: AgentDefinition, env?: NodeJS.ProcessEnv): BuiltDefinition;
+export declare function buildDefinition(definition: AgentDefinition, env: NodeJS.ProcessEnv, instance?: BuildConfig): BuiltDefinition;
 /**
  * The definition's code built only to read its shape (which channels, with which ingress, which schedules, which
  * providers): a declared secret `env` holds no value for has a stand-in, since the shape must not depend on whether
  * this machine holds the values. Whatever a build refuses, this refuses too.
  */
-export declare function buildDefinitionShape(definition: AgentDefinition, env: NodeJS.ProcessEnv): BuiltDefinition;
+export declare function buildDefinitionShape(definition: AgentDefinition, env: NodeJS.ProcessEnv, config?: BuildConfig): BuiltDefinition;
 /**
  * The providers of the definition in `agentDir`, for a command that reads models without serving (`models`, `login`,
  * the first-run picker): with the values `env` holds and stand-ins for the rest, so listing a model or signing in to
  * it needs no secret the serve would. Without these a provider in code, or one replacing a built-in's id, would be
  * unknown there, or verified against the built-in's endpoint.
  */
-export declare function definitionProviders(agentDir: string, env?: NodeJS.ProcessEnv): Promise<Provider[]>;
+export declare function definitionProviders(agentDir: string, env: NodeJS.ProcessEnv): Promise<Provider[]>;
 export interface AssembleAgentOptions {
     storage: Storage;
+    /** Who runs the instance, as far as the prompt says where the agent runs (deployed, on AgentCore). */
+    runsAs: RunsAs;
     /** What the agent works on (`context.json`'s content), resolved for this instance. */
     content?: readonly ResolvedContent[];
+    /** The instance's name (`instanceName`): what `info().name` reports. Default: the definition's, as one segment. */
+    name?: string;
+    /** The agent's working directory: the definition's own, unless the instance is elsewhere. */
+    workdir?: string;
     /** The definition's code, built once with its secrets (`buildDefinition`). */
     code: BuiltDefinition;
+    /** The configuration this instance opens with (`resolveConfig`). */
+    config: EffectiveConfig;
+    /** The text it reads for each message (`openText`). Default: the program's own. */
+    text?: TextSources;
     mcpTools?: ToolRegistration[];
     /**
      * pi-ai's built-ins and the definition's providers over the instance's credentials, lists refreshed: the model
@@ -84,11 +85,8 @@ export interface AssembleAgentOptions {
     /** Whether that scheduler runs now: an app's `openAgent` runs one only while it serves. Default always. */
     wakeTicking?: () => boolean;
     unfinished?: Unfinished;
-    /**
-     * What the agent's environment adds to this process's, for the commands it runs: its value file's variables and its
-     * packages' PATH.
-     */
-    environment?: Readonly<Record<string, string>>;
+    /** The whole environment of the processes the agent starts (child-env.ts): nothing of this process's is added. */
+    processEnv: Readonly<Record<string, string>>;
 }
 /** Open the definition as an Agent over `models`: the coding tools, then its own. */
 export declare function assembleAgent(definition: AgentDefinition, options: AssembleAgentOptions): Promise<DurableAgent>;