@stratusagent/core 0.11.6 → 0.11.8

package/dist/index.d.ts

@@ -151,9 +151,11 @@ export interface Message {
     toolCalls?: ToolCall[];
     toolResult?: ToolResult;
     /**
-     * Images sent with a user message. Present only on `user` messages that
-     * carried one; a provider that can show the model an image sends these
-     * alongside the text, and one that cannot names them instead.
+     * Images sent with a user message, or returned by a tool call (moved
+     * here off `ToolResult.images` as the result is recorded). Present only
+     * on `user` and `tool` messages that carried one; a provider that can
+     * show the model an image sends these alongside the text, and one that
+     * cannot names them instead.
      */
     images?: ImageAttachment[];
     /**
@@ -169,6 +171,44 @@ export interface Message {
      * — the boundary provenance draws, here at the point text enters.
      */
     overheard?: boolean;
+    /**
+     * Appended by `observe`, so it started no turn. `overheard` alone cannot
+     * say so: a turn dispatched with `addressed: false` is overheard too, and
+     * is a turn. Present only when true; a message observed before this was
+     * recorded reads as a turn, which errs toward attributing nothing to an
+     * earlier one (`isLatestTurn`).
+     */
+    observed?: boolean;
+    /**
+     * The caller's idempotency key for the dispatch that brought this user
+     * message (`RunInput.idempotencyKey`). Written in the same save as the
+     * message, so a key is never durable without its message or the other
+     * way round; `workItemState` reads it back.
+     */
+    idempotencyKey?: string;
+    /**
+     * Why the turn this user message started failed, written by
+     * `recordTurnFailure` in the save that fails it. The session's
+     * `lastError` is the latest turn's and the next turn replaces it; this
+     * stays, so `turnFailureFor` can answer for any turn a key names.
+     */
+    turnError?: string;
+    /**
+     * This message's turn was continued once after the process running it
+     * died (`AgentRunner.continueTurn`). A host fails a second such turn
+     * instead of continuing it again: a turn that takes the process down
+     * with it would otherwise do so on every start. Present only when true.
+     */
+    continuedAfterCrash?: boolean;
+    /**
+     * The turn this message started could reach a provider that runs its own
+     * tool loop (a harness): what that turn did is not all in this
+     * transcript, so a crash mid-turn cannot be continued from it. Recorded
+     * at accept time, because the runtime a crashed turn ran on is not the
+     * one a restart resolves if the configuration changed in between.
+     * Present only when true; see `RunInput.hostedLoop`.
+     */
+    hostedLoop?: boolean;
 }
 export interface AgentDescriptor {
     id: string;
@@ -368,7 +408,48 @@ export interface ToolResult {
      * already hold hostile page content. A new result always carries one.
      */
     trust?: TrustLevel;
+    /**
+     * Images the call handed back through `ExecutionContext.attachImage` — a
+     * screenshot, an image file read from disk. In flight only: the runner
+     * moves them onto the tool message's `images` as it records the result,
+     * so they are stored, budgeted, and trimmed exactly as a user message's
+     * images are, and never serialized into the message content or carried
+     * on a bus event.
+     */
+    images?: ImageAttachment[];
 }
+/**
+ * What the model is told about a result labelled `external`, said once
+ * here rather than left for each tool to word — a third-party plugin or an
+ * MCP server never has to know the convention for its output to carry it.
+ */
+export declare const UNTRUSTED_TOOL_RESULT_NOTE: string;
+/**
+ * The text a provider hands the model for a tool result — the one
+ * serialization every provider and harness bridge uses, so the trust label
+ * reaches the model the same way whichever one carries the turn.
+ *
+ * An `external` result is wrapped in `{ untrusted, untrustedNote, output }`,
+ * the vocabulary `web.search` already used in-band. This marks the boundary
+ * and nothing more: a model can still follow text inside the envelope, and
+ * it is not a prompt-injection defence. Only `external` is wrapped, not
+ * `unknown`: `shell.run` declares `unknown`, and a marker on every command's
+ * output would teach the model that the marker is noise. A failed result is
+ * wrapped too, because the executor labels failures — a fetched server's
+ * error text is that server's text.
+ *
+ * The envelope is applied whatever the output already says, including
+ * `web.search`'s own `untrusted: true`. Skipping on a field of the output
+ * would let the output decide whether it is marked, and the output is the
+ * party not trusted; the repetition costs a sentence.
+ *
+ * Never mutates the result: the transcript, the dashboard, and the control
+ * API read the raw output. Deterministic for a given result, so a replayed
+ * transcript is byte-identical and the prompt cache holds. `Tool failed`
+ * stays unpunctuated because the API providers replay it from persisted
+ * transcripts, where a changed byte is a cache miss.
+ */
+export declare const renderToolResultContent: (result: Pick<ToolResult, "ok" | "output" | "error" | "trust">) => string;
 export type ProviderPart = {
     type: 'text';
     text: string;
@@ -379,7 +460,8 @@ export type ProviderPart = {
 /**
  * A streamed fragment of an in-progress provider response. Text deltas carry
  * output as it is generated; tool-call deltas announce that the model has
- * started emitting a call (input may still be incomplete). A reset delta
+ * started emitting a call (input may still be incomplete); thinking and
+ * progress deltas carry nothing but the fact of activity. A reset delta
  * tells consumers to DISCARD every fragment streamed so far for this
  * response — emitted when a provider abandons a partial attempt (e.g. a
  * fallback wrapper retrying after the primary failed mid-stream), so
@@ -400,6 +482,16 @@ export type ProviderDelta = {
  */
  | {
     type: 'thinking';
+}
+/**
+ * The provider is working on this response and has nothing to show for
+ * it yet: a retry it is waiting out, a context compaction, a message
+ * boundary. Content-free like `thinking`, and for the same reader — an
+ * activity watchdog that would otherwise take a busy provider for a
+ * stalled one. A renderer has nothing to draw for it.
+ */
+ | {
+    type: 'progress';
 } | {
     type: 'reset';
     /**
@@ -1391,6 +1483,13 @@ export declare class InMemoryAgentMemoryStore implements AgentMemoryStore {
  * Resolves named credentials for an agent. Implementations must enforce the
  * agent's `credentials` allowlist so secrets stay scoped per agent.
  */
+/** Whose a named credential is: one agent's own, or the whole fleet's. */
+export type CredentialScope = 'agent' | 'shared';
+/**
+ * How a credential request reaches a person: a form in the conversation's
+ * own channel, or a one-time link the agent passes on.
+ */
+export type CredentialDelivery = 'form' | 'link';
 export interface CredentialResolver {
     resolve(agent: AgentDefinition, name: string): Promise<string | undefined>;
 }
@@ -1499,6 +1598,99 @@ export declare const uncachedInputTokens: (total: number, ...cached: Array<numbe
  * nothing at all.
  */
 export declare const totalTokenUsage: (records: readonly TokenUsage[]) => TokenUsage | undefined;
+/**
+ * Facts about how an agent is run that only the host knows, told to the
+ * agent so it does not have to guess them.
+ *
+ * It does guess otherwise, and guesses wrong: an agent asked to reread its
+ * soul after an edit answered that it had none, because there was no
+ * `SOUL.md` in its workspace, which is where other agent runtimes keep one.
+ * Handed in by the host rather than written into the soul because the
+ * paths are the host's to own, and a copy in every soul would go stale the
+ * next time the layout moved, the way the workspace already did once.
+ */
+export interface AgentRuntimeContext {
+    /** Absolute path of the soul file this agent's persona was loaded from. */
+    soulPath?: string;
+    /**
+     * True when the host reads the soul again before every turn, so an edit
+     * reaches the agent's next reply. The daemon does; a one-shot run reads
+     * it once, and leaving this out says nothing either way.
+     */
+    soulReloads?: boolean;
+    /** Where this agent's files go: `AgentWorkspaces.forAgent`. */
+    workspace?: string;
+    /**
+     * The language the agent writes in, as a tag `isLanguageTag` accepts,
+     * already resolved by the host: the soul's `language:`, then the config
+     * file's. Absent means {@link DEFAULT_LANGUAGE}. Rendered in the reply
+     * section rather than here, so a host that says nothing else still gets
+     * the default rule.
+     */
+    language?: string;
+    /**
+     * What the host has configured to answer as this agent, and what it has
+     * observed: `onFallback` is true once this conversation has switched to
+     * the fallback, which is sticky, so a model asked what it is can tell a
+     * configured default from the one actually answering. The fallback
+     * wrapper sets it on the request it hands the fallback mid-turn, so the
+     * model that took over is not told it is the default.
+     */
+    model?: AgentModelContext;
+    /**
+     * Who can read this conversation, as the channel that carried the turn
+     * reported it on the turn's metadata (`conversationContextFrom`). Per
+     * turn rather than read off the session, so a thread that started before
+     * this existed, or a channel that grew since, is described as it is now.
+     */
+    conversation?: ConversationContext;
+}
+/**
+ * What kind of room a conversation is: one person, a few, a closed
+ * channel, or one the whole workspace can read. An agent that did not
+ * know told a person in a Slack DM they were "talking on the terminal",
+ * and would have posted the same reply to a thousand-person channel.
+ */
+export type ConversationKind = 'direct' | 'group' | 'private' | 'public';
+export interface ConversationContext {
+    kind: ConversationKind;
+    /** Members as the channel counts them, the agent included. */
+    members?: number;
+    /**
+     * Who a direct message is with. It reaches the system prompt, so a
+     * channel sets it only for someone the operator vouched for (a Slack
+     * principal), never from a name anyone could have typed.
+     */
+    with?: string;
+    /** The turn is a reply in a thread rather than the channel itself. */
+    thread?: boolean;
+    /**
+     * People outside this workspace read it too: a Slack Connect channel,
+     * or one shared across an organization's workspaces. Never set for a
+     * direct message.
+     */
+    shared?: boolean;
+}
+/**
+ * The metadata key a channel adapter records a turn's room under: a
+ * `ConversationContext`-shaped object, read back by
+ * `conversationContextFrom`.
+ */
+export declare const CONVERSATION_METADATA_KEY = "conversation";
+/**
+ * The room a turn's metadata describes, keeping only what is safe to put
+ * in front of the model, or undefined when it describes none.
+ */
+export declare const conversationContextFrom: (metadata: JsonObject | undefined) => ConversationContext | undefined;
+export interface AgentModelContext {
+    provider: string;
+    model?: string;
+    fallback?: {
+        provider: string;
+        model: string;
+    };
+    onFallback?: boolean;
+}
 export interface ProviderRequest {
     /**
      * The live session. **Persistable**: a provider that saves it, or hands
@@ -1551,6 +1743,12 @@ export interface ProviderRequest {
      * the model decides a description is relevant.
      */
     skills?: SkillDescriptor[];
+    /**
+     * What the host can say about how this agent is run: where its soul and
+     * workspace are. Rendered as the `runtime` section; see
+     * {@link AgentRuntimeContext}.
+     */
+    runtime?: AgentRuntimeContext;
     /**
      * Streaming sink. Adapters that stream call this per fragment and MUST
      * await the returned promise before the next call (backpressure); the
@@ -1657,7 +1855,29 @@ export interface ExecutionContext {
      * no sink gets whatever `outputTrust` declares.
      */
     markTrust?: (trust: TrustLevel) => void;
+    /**
+     * Hand the model an image with this call's result — a screenshot a tool
+     * took, an image file it read — so the agent can actually look at it
+     * rather than be told a path. Checked as it is attached: a format the
+     * model APIs refuse, an image over `IMAGE_ATTACHMENT_MAX_BYTES` or
+     * `IMAGE_ATTACHMENT_MAX_DIMENSION`, bytes that are not the image they
+     * claim to be, or more than `IMAGE_ATTACHMENTS_MAX_TOTAL_BYTES` in one
+     * call throws, so the tool can say so in its own result. Absent when the
+     * host cannot carry images; a tool then says it has no way to show one.
+     *
+     * The result's trust label covers the image too: a screenshot of a web
+     * page is the page's content.
+     */
+    attachImage?: (image: ImageAttachment) => void;
 }
+/**
+ * Collects what a tool attaches through `ExecutionContext.attachImage`,
+ * held to the limits that sink documents.
+ */
+export declare const createImageCollector: () => {
+    attach: (image: ImageAttachment) => void;
+    images: () => ImageAttachment[];
+};
 export interface Tool {
     name: string;
     description?: string;
@@ -1842,6 +2062,82 @@ export interface PendingApprovalRecord {
  * cannot disagree on which message is "the reply".
  */
 export declare const latestTurnReply: (session: Pick<Session, "messages">) => string | undefined;
+/**
+ * Whether a session's transcript already ends in the turn's answer: its
+ * last response holds no tool call, so the loop owed the model nothing more
+ * and only the save marking the turn completed is missing. A continuation
+ * then completes it without a provider call.
+ *
+ * Judged on the last response as a whole: a response's parts are saved
+ * together and its tool results after them all, so the trailing run of
+ * assistant messages is that one response. Any call in it — even one
+ * followed by text, which a provider may send in that order — means the
+ * model is owed another turn. Read it before `reconcileInterruptedToolCalls`
+ * splices results in.
+ */
+export declare const lastResponseIsAnswer: (session: Pick<Session, "messages">) => boolean;
+/**
+ * The end of a turn that answered: marked completed in one save, then
+ * announced. The runner's loop ends here, and so does a turn whose answer
+ * a process saved and then died before marking it completed — which needs
+ * no provider and no current agent definition to finish, so a host can do
+ * it with only its store and bus (`lastResponseIsAnswer` says when).
+ */
+export declare const completeAnsweredTurn: (finished: Session, store: SessionStore, bus: EventBus) => Promise<Session>;
+/**
+ * The longest idempotency key a dispatch accepts. Here rather than in the
+ * gateway that enforces it, because a channel composing keys from ids it
+ * does not bound (an agent's, a platform's) has to fit them to it.
+ */
+export declare const MAX_IDEMPOTENCY_KEY_LENGTH = 256;
+/**
+ * The reply of the turn a keyed message started (`Message.idempotencyKey`),
+ * where `latestTurnReply` is the newest turn's. A repeated dispatch resolves
+ * with the session as it stands, which may have moved on since: an adapter
+ * answering a redelivered message reads the reply here, or it would answer
+ * the old message with a newer turn's words. Undefined when no message
+ * carries the key, or its turn produced no text.
+ */
+export declare const turnReplyFor: (session: Pick<Session, "messages">, idempotencyKey: string) => string | undefined;
+/**
+ * The files the turn a keyed message started produced (`filePathsOf` over
+ * its tool results), the other half of what `turnReplyFor` reads. A
+ * channel uploads a turn's files as the results arrive, so an adapter
+ * answering a repeat of a finished turn — no events, only the session —
+ * has this and nothing else to find them by.
+ *
+ * A path, not the bytes: the transcript never held them. `producedAt` is
+ * when the result naming it was recorded, so a reader can refuse a path
+ * that has been written since — by now it may hold a later turn's file.
+ */
+export declare const turnFilesFor: (session: Pick<Session, "messages">, idempotencyKey: string) => Array<{
+    path: string;
+    producedAt: string;
+}>;
+/**
+ * Fail a session's in-flight turn: `status` and `lastError`, and the error
+ * on the turn's own user message (`Message.turnError`), where the next
+ * turn cannot overwrite it. The one write every path that fails a turn
+ * makes — the runner's and the gateway's sweeps — so `turnFailureFor`
+ * reads the same record whichever failed it. In flight, the turn's message
+ * is the session's newest user message (`observe` refuses to append).
+ */
+export declare const recordTurnFailure: (session: Session, error: string) => void;
+/**
+ * Whether the keyed message started the session's latest turn. A message
+ * `observe` appended since started no turn and is passed over
+ * (`Message.observed`); every other user message, keyed or not, addressed
+ * or not, started one.
+ */
+export declare const isLatestTurn: (session: Pick<Session, "messages">, idempotencyKey: string) => boolean;
+/**
+ * Why the turn a keyed message started failed, or undefined if it did not.
+ * Read from the message (`recordTurnFailure`), so a turn the session has
+ * moved on from still answers. A transcript written before turns carried
+ * their own failure has only the session's, which is the keyed turn's
+ * while it is the latest (`isLatestTurn`).
+ */
+export declare const turnFailureFor: (session: Pick<Session, "messages" | "status" | "lastError">, idempotencyKey: string) => string | undefined;
 /**
  * A user message's text as a prompt should carry it. The one place an
  * overheard message is framed, so the API providers' per-message blocks
@@ -1877,6 +2173,22 @@ export declare const promptTextOf: (message: Pick<Message, "content" | "overhear
  * as the answer rather than as a broken endpoint.
  */
 export declare const isUnaddressedTurn: (session: Pick<Session, "messages">) => boolean;
+/**
+ * Where the dispatch carrying `idempotencyKey` stands in this session:
+ * `undefined` if no message carries the key, `unfinished` if its message
+ * is the one the session's in-flight turn is on, `finished` otherwise.
+ *
+ * Derived, never recorded separately, which is what makes it exact. The
+ * keyed message is written in the same save that sets the status to
+ * `running` (accepted and started are one write), and the save that moves
+ * the status off `running` or `pending_approval` is the turn's final one,
+ * so `finished` is written in the same transaction as the final save by
+ * construction. While a turn is in flight its message is the session's
+ * newest user message — `observe` refuses to append during one, and the
+ * runner's wrap-up notes never reach the store — the same reading
+ * `isUnaddressedTurn` relies on.
+ */
+export declare const workItemState: (session: Pick<Session, "messages" | "status">, idempotencyKey: string) => "unfinished" | "finished" | undefined;
 export declare const markPromptDelivered: <T>(error: T) => T;
 export declare const promptWasDelivered: (error: unknown) => boolean;
 export interface PromptTextOptions {
@@ -2069,6 +2381,54 @@ export type StratusEvent = {
     reason: ApprovalResolutionReason;
     /** Who decided, when a person did. Channel-native id (a Slack user). */
     actor?: string;
+}
+/**
+ * An agent asked for a named credential it does not hold
+ * (`credential.request`), and it has already been put to someone: a form
+ * in the conversation it asked in (`via: 'form'`), or a one-time link the
+ * agent was handed to pass on (`via: 'link'`). The request is delivered
+ * first and announced after, so this is a record of a question that was
+ * asked, never a request for someone to render one. Nothing about it is
+ * a secret, and nothing that answers it ever travels on the bus. `scope` is whose the key would be: the
+ * agent's own (`agent`, the default) or the fleet's (`shared`).
+ *
+ * `metadata` is the session's, for the same reason an approval request
+ * carries it: it says which conversation to ask in.
+ */
+ | {
+    type: 'credential.requested';
+    sessionId: string;
+    agentId: string;
+    requestId: string;
+    name: string;
+    scope: CredentialScope;
+    /** The agent's own words on what it needs the key for. Untrusted text. */
+    reason?: string;
+    /** How it was put to someone. Absent from hosts before links existed, which only had forms. */
+    via?: CredentialDelivery;
+    metadata?: JsonObject;
+}
+/**
+ * A requested credential was stored for the agent that asked, and granted
+ * to it. Names only; the value went to the credential store and nowhere
+ * else.
+ *
+ * Emitted once the key is stored, whether or not the grant then landed:
+ * a key added from a chat is a change on disk, and a shared one is
+ * already usable by every agent granted that name, so it is recorded even
+ * when the soul write failed. `grantError` says it did, and why.
+ */
+ | {
+    type: 'credential.provided';
+    sessionId: string;
+    agentId: string;
+    requestId: string;
+    name: string;
+    scope: CredentialScope;
+    /** Who provided it. Channel-native id (a Slack user). */
+    actor?: string;
+    /** Set when the key was stored but could not be added to the soul. */
+    grantError?: string;
 } | {
     type: 'session.completed';
     sessionId: string;
@@ -2421,6 +2781,29 @@ export interface AgentWorkspaces {
      */
     all(): Promise<readonly string[]>;
 }
+/**
+ * Where one plugin keeps durable state of its own, answered by the host.
+ *
+ * A seam for the reason {@link AgentWorkspaces} is one: the layout is the
+ * host's to own. A plugin that needs to remember something across restarts
+ * — a channel's read position in a store it does not own, a cursor into a
+ * vendor's event log — would otherwise join a path onto `~/.stratus` itself,
+ * and every plugin doing so is one more copy of the layout to find when it
+ * moves. Per plugin, never per agent: what a plugin remembers is its own,
+ * and it makes whatever structure it needs beneath this.
+ */
+export interface PluginStateDirectory {
+    /**
+     * The directory, created and with its permissions settled, for a caller
+     * about to write. Private to the daemon's user, because what a plugin
+     * keeps is the daemon's business, and a plugin cannot be expected to know
+     * the mode the rest of the state is held to.
+     *
+     * Asked per write rather than captured at setup: a daemon runs for weeks,
+     * and the directory can be removed or replaced with a link under it.
+     */
+    prepare(): string;
+}
 export interface MemoryRegistrationHandle {
     register(contribution: MemoryStoreContribution): void;
 }
@@ -2471,6 +2854,15 @@ export interface PluginContext {
      * read as though it did.
      */
     workspaces?: AgentWorkspaces;
+    /**
+     * Where this plugin may keep durable state. See {@link PluginStateDirectory}.
+     *
+     * A host that omits it gives the plugin nowhere to remember anything
+     * across a restart. Such a plugin must say what it gives up — a channel
+     * that cannot store its read position cannot promise a message is handled
+     * once — and must never choose a directory of its own instead.
+     */
+    stateDirectory?: PluginStateDirectory;
     /**
      * The host's log, for what a plugin has to say after `setup` returns —
      * a server that dropped, a reconnect that failed. The daemon's is the
@@ -2549,6 +2941,15 @@ export interface SkillDescriptor {
  * else, per turn and in memory.
  */
 export interface Skill extends SkillDescriptor {
+    /**
+     * Ships with Stratus and is enabled for every agent, whatever its soul's
+     * `skills:` says. Reserved for the system's own documentation (the
+     * `stratus` skill; `SkillRegistry.register` refuses it on any other id): a skill from anywhere else changing how an agent
+     * behaves is opted into, but an agent that cannot read how the system it
+     * runs in works guesses instead, the way one suggested `passEnv` for a
+     * secret after reading the install around it.
+     */
+    builtin?: boolean;
     /**
      * Toolset globs this skill expects (`browser.*`, `fs.read`). Advisory: a
      * skill is prose and degrades, so an agent enabling one without the tools
@@ -2633,6 +3034,12 @@ export declare class SkillRegistry {
      * A read already underway keeps the promise it holds either way. `next`
      * is consumed — emptied, not shared — so nothing can go on mutating this
      * registry through it.
+     *
+     * A built-in skill serving now is never dropped by the swap: a `next`
+     * without one (its file unreadable mid-reload) keeps the one serving,
+     * and a bare alias `next` gave its id yields to it. A reload is
+     * all-or-nothing for what it read; it must not take away from every
+     * agent the one skill no soul can opt back into.
      */
     replaceWith(next: SkillRegistry): void;
     describe(): SkillDescriptor[];
@@ -2644,6 +3051,12 @@ export declare class SkillRegistry {
     read(id: string): Promise<string>;
 }
 export declare const SKILL_READ_TOOL_NAME = "skill.read";
+/**
+ * The built-in skill's id: how Stratus works, enabled for every agent.
+ * Reserved, so an operator directory or a plugin cannot put a different
+ * procedure under the name every agent is pointed at.
+ */
+export declare const STRATUS_SKILL_ID = "stratus";
 export interface SkillReadToolOptions {
     /**
      * Which `skills:` entries the session's agent is held to. Defaults to the
@@ -2727,6 +3140,43 @@ export declare const renderMemorySection: (memory: readonly MemoryEntry[] | Memo
  * here may ever include a body.
  */
 export declare const renderSkillsSection: (skills: readonly SkillDescriptor[] | undefined) => string | undefined;
+/**
+ * The language agents write in when nothing says otherwise: American
+ * English. A soul's `language:` and the config file's `language` override
+ * it; see `resolveRuntimeConfig`, which decides between those two.
+ */
+export declare const DEFAULT_LANGUAGE = "en-US";
+/** Whether a `language` setting is a BCP 47 tag; see `canonicalLanguageTag`. */
+export declare const isLanguageTag: (value: unknown) => value is string;
+/**
+ * How to reply, told to every agent before its persona.
+ *
+ * Models default to the long, headed, bulleted answer, and an agent is read
+ * mostly in chat, often on a phone, where that is the wrong shape. Souls
+ * were each growing their own copy of these rules, so they live here once.
+ * Short must not turn into incomplete, so the same section says a requested
+ * deliverable arrives whole and a blocker is always said. A long one goes
+ * where the reader can open it: an agent on Slack that answers with a path
+ * on the daemon's disk has handed over nothing, so when sharing is not
+ * possible the content itself goes in the reply.
+ *
+ * The accuracy rules are here for the same reason, each after an incident:
+ * an agent with no Slack tool insisted it had no Slack connection, and
+ * agents reported work as done that had only been drafted. The language
+ * rule is here because the default persona is not: a custom soul replaces
+ * it, and an agent wrote "favour" and "licence" into American website copy
+ * because nothing shared said which English. A pasted British paragraph is
+ * not a setting, so the rule says a task or a client's style guide decides
+ * one deliverable and nothing is inferred from source text.
+ *
+ * The last sentence lets the soul and the person override length, format,
+ * and language, and deliberately nothing else: a style preference never
+ * changes what an agent may do, and "be brief" must not read as "skip the
+ * blocker". Written without em dashes on purpose: a model imitates the
+ * prose it is prompted with, and a rule against them set in them undoes
+ * itself.
+ */
+export declare const renderReplySection: (language: string | undefined) => string;
 /**
  * Where the conversation is happening, for a session a channel started.
  *
@@ -2734,11 +3184,39 @@ export declare const renderSkillsSection: (skills: readonly SkillDescriptor[] |
  * dispatches (`slack` today). Without this the agent could not tell: an
  * agent with no Slack tool, asked about an attachment in a Slack DM, told
  * the person it had "no Slack connection at all" and argued the point.
- * Rendered from the session rather than handed in per turn so sessions
- * opened before this existed get it too. The name must look like a channel
+ * The channel is read from the session, so sessions opened before this
+ * existed get it too; the room (`ConversationContext`) comes per turn from
+ * the runtime, falling back to what the session's first turn recorded, so
+ * an agent in a Slack DM no longer tells the person they are "talking on
+ * the terminal". The name must look like a channel
  * id, since it is interpolated into the prompt.
+ *
+ * What it says about attachments is what the adapter writes into the
+ * message, not a promise that they arrive: it used to say that what people
+ * attach "reaches you", which read as though every file's contents did,
+ * when most reach the turn as a name only. The Slack adapter marks each
+ * file as read, shown, or unread with its reason; the section sends the
+ * model to that note and nowhere else.
  */
-export declare const renderChannelSection: (session: Pick<Session, "metadata">) => string | undefined;
+export declare const renderChannelSection: (session: Pick<Session, "metadata">, conversation?: ConversationContext) => string | undefined;
+/**
+ * How this agent is run, for a host that said (see
+ * {@link AgentRuntimeContext}).
+ *
+ * It says the soul is already in the prompt as firmly as it says where the
+ * file is. An agent told only a path treats it as something to go and read,
+ * and it usually cannot: the soul sits beside its state directory, outside
+ * any root an operator hands `tool-fs`, and it has to stay there, since
+ * the soul is what grants the agent its tools and credentials.
+ *
+ * Credentials get the same treatment, and for the same reason: an agent
+ * whose operator had stored a shared key went looking through its files and
+ * its environment for it. A named credential only ever reaches a plugin tool
+ * that declared it, so the section names what the soul grants and says there
+ * is nothing to find. Names only; a value never comes near a prompt.
+ * Written without em dashes for the reason the reply section is.
+ */
+export declare const renderRuntimeSection: (runtime: AgentRuntimeContext | undefined, agent: Pick<AgentDefinition, "credentials">) => string | undefined;
 export interface SystemPromptOptions {
     /** Host-level preamble, rendered before the agent's own persona. */
     preamble?: string;
@@ -2749,12 +3227,12 @@ export interface SystemPromptOptions {
  * Which part of what an agent is told a section is.
  *
  * The distinction a caller actually needs is stable versus volatile:
- * `preamble`, `replies`, `persona`, `channel`, and `skills` are byte-identical across every turn of
+ * `preamble`, `replies`, `persona`, `runtime`, `channel`, and `skills` are byte-identical across every turn of
  * an agent's life, while `memory` is rewritten whenever the agent remembers
  * anything. A provider that caches its request prefix has to place those two
  * groups differently, and it cannot tell them apart from rendered strings.
  */
-export type SystemPromptSectionKind = 'preamble' | 'replies' | 'persona' | 'channel' | 'memory' | 'skills';
+export type SystemPromptSectionKind = 'preamble' | 'replies' | 'persona' | 'runtime' | 'channel' | 'memory' | 'skills';
 export interface SystemPromptSection {
     kind: SystemPromptSectionKind;
     text: string;
@@ -2773,11 +3251,11 @@ export interface SystemPromptSection {
  * The order is the order. This is the one rule about what an agent is told;
  * `renderSystemPromptSections` is the same rule with the labels dropped.
  */
-export declare const renderSystemPromptParts: (request: Pick<ProviderRequest, "session" | "memory" | "skills">, options?: SystemPromptOptions) => SystemPromptSection[];
+export declare const renderSystemPromptParts: (request: Pick<ProviderRequest, "session" | "memory" | "skills" | "runtime">, options?: SystemPromptOptions) => SystemPromptSection[];
 /** The sections as plain strings, in the same order. */
-export declare const renderSystemPromptSections: (request: Pick<ProviderRequest, "session" | "memory" | "skills">, options?: SystemPromptOptions) => string[];
+export declare const renderSystemPromptSections: (request: Pick<ProviderRequest, "session" | "memory" | "skills" | "runtime">, options?: SystemPromptOptions) => string[];
 /** The sections joined the way single-string providers send them. */
-export declare const renderSystemPrompt: (request: Pick<ProviderRequest, "session" | "memory" | "skills">, options?: SystemPromptOptions) => string | undefined;
+export declare const renderSystemPrompt: (request: Pick<ProviderRequest, "session" | "memory" | "skills" | "runtime">, options?: SystemPromptOptions) => string | undefined;
 /**
  * The two producer channels, collected for one call: the tool's standing
  * `outputTrust` declaration and whatever the tool marks through the
@@ -2889,7 +3367,31 @@ export interface RunInput {
      * attachments instead, as an overheard one does.
      */
     addressed?: boolean;
+    /**
+     * The caller's name for this dispatch, stored on the user message
+     * (`Message.idempotencyKey`) in the same write as the message itself.
+     * The runner only records it; refusing a repeat is the host's job — see
+     * `workItemState` and the gateway's `DispatchInput.idempotencyKey`.
+     */
+    idempotencyKey?: string;
+    /**
+     * Whether this turn may run on a provider that hosts its own tool loop,
+     * stored on the user message (`Message.hostedLoop`). The host knows what
+     * it resolved for the turn; the runner only records it.
+     */
+    hostedLoop?: boolean;
     metadata?: JsonObject;
+    /**
+     * What the host can say about how this agent is run, rendered as the
+     * `runtime` section; see {@link AgentRuntimeContext}. Omitted, the
+     * section is not rendered.
+     *
+     * Per run rather than a runner option, because the answer belongs to the
+     * snapshot the host dispatched with: a daemon that re-reads the roster
+     * between two awaits would otherwise tell an agent running on one soul
+     * file that another file is its soul.
+     */
+    runtime?: AgentRuntimeContext;
     /** Aborting fails the turn cleanly; see RunAbortedError. */
     signal?: AbortSignal;
 }
@@ -2900,6 +3402,10 @@ export interface ResumeInput {
     images?: ImageAttachment[];
     /** See `RunInput.addressed`. */
     addressed?: boolean;
+    /** See `RunInput.idempotencyKey`. */
+    idempotencyKey?: string;
+    /** See `RunInput.hostedLoop`. */
+    hostedLoop?: boolean;
     /**
      * This turn's metadata — read for the sender's trust
      * (`SENDER_TRUST_METADATA_KEY`) and not merged into the session's. The
@@ -2908,6 +3414,8 @@ export interface ResumeInput {
      * trust.
      */
     metadata?: JsonObject;
+    /** See `RunInput.runtime`. */
+    runtime?: AgentRuntimeContext;
     /** Aborting fails the turn cleanly; see RunAbortedError. */
     signal?: AbortSignal;
 }
@@ -3104,6 +3612,30 @@ export declare class AgentRunner {
      */
     private labelLegacySession;
     resume(input: ResumeInput): Promise<Session>;
+    /**
+     * Picks up a turn whose process died while it was `running`: its user
+     * message is durable and its reply is not. Nothing is appended — the turn
+     * already has its message — so this is `resume` without the input.
+     * Dangling tool calls are closed as interrupted, telling the model they
+     * may not have run rather than running them again, and the loop goes back
+     * to the provider with the transcript as it stands.
+     *
+     * A transcript that already ends in the reply (the response was saved,
+     * and the process died before the save that marks the turn completed) is
+     * completed as it stands, with no provider call: asking again would send
+     * a second answer to one message.
+     *
+     * Marks the turn's message `continuedAfterCrash` in its first save, so a
+     * host can refuse to do this twice. Resolves `undefined` when the session
+     * is missing or no longer `running`. Never for a turn parked on a human:
+     * `recoverPendingApproval` re-enters the parked call, which reconciling
+     * here would close.
+     */
+    continueTurn(sessionId: string, options?: {
+        /** See `RunInput.runtime`. */
+        runtime?: AgentRuntimeContext;
+        signal?: AbortSignal;
+    }): Promise<Session | undefined>;
     /**
      * A message reaching the session with no turn run on it: something said
      * in a conversation the agent is in, to somebody else. Appended and
@@ -3122,11 +3654,18 @@ export declare class AgentRunner {
      */
     observe(input: ObserveInput): Promise<Session>;
     /**
-     * Appends a synthetic failed result directly after every tool call that
-     * has none — the durable trace of a turn interrupted between the call's
-     * save and its result's. The model sees an honest record ("interrupted,
-     * never ran to completion") instead of a wire-format violation, and a
-     * resume can decide to retry rather than assume the side effect landed.
+     * Adds a synthetic failed result for every tool call that has none — the
+     * durable trace of a turn interrupted between the call's save and its
+     * result's. The model sees an honest record ("interrupted, never ran to
+     * completion") instead of a wire-format violation, and a resume can
+     * decide to retry rather than assume the side effect landed.
+     *
+     * Placed where an uninterrupted turn would have written it: after the
+     * whole response the call came in — every assistant message that one
+     * save wrote — and after any results already recorded for it. Directly
+     * after the call would split a response whose text followed its call, and
+     * a provider replaying the response's raw turn (which already holds that
+     * text) would then send the text a second time.
      */
     private reconcileInterruptedToolCalls;
     /**
@@ -3163,11 +3702,14 @@ export declare class AgentRunner {
      * the allowlist actually granted (canonical before alias) — the id the
      * model is told is the id `skill.read` will accept.
      *
-     * Empty for an agent whose soul has no `skills:` key, which is what keys
-     * both `skill.read` gates: no skills, no reader.
+     * A built-in skill is in it for every agent; otherwise it is empty for
+     * an agent whose soul has no `skills:` key, which is what keys both
+     * `skill.read` gates: no skills, no reader.
      */
     private enabledSkillsFor;
     private executeTurns;
+    /** See `completeAnsweredTurn`; the loop's end and `continueTurn`'s. */
+    private completeTurn;
     /**
      * Finishes a turn that was parked on a human when the process died.
      *
@@ -3188,6 +3730,8 @@ export declare class AgentRunner {
          * about at all, so they still face the policy normally.
          */
         denyPending?: boolean;
+        /** See `RunInput.runtime`. */
+        runtime?: AgentRuntimeContext;
         signal?: AbortSignal;
     }): Promise<Session | undefined>;
     /**