fix(prompt): retry a failed registry prompt fetch on the next run

api/index.api.md

@@ -1923,6 +1923,7 @@ export const ERROR_CODES: {
     readonly LOUSHO_REGISTRY_UNSAFE_PATH: "Do not install this item; it asks to write outside its allowed folder or is too large, so tell the registry owner.";
     readonly LOUSHO_REGISTRY_FILE_EXISTS: "Pass --overwrite to replace the existing file, or move your file away first.";
     readonly LOUSHO_REGISTRY_MANIFEST_MISMATCH: "Do not install this item: its code reaches for something its permission manifest does not declare; tell the registry owner, who fixes the code or the manifest.";
+    readonly LOUSHO_PROMPT_UNRESOLVED: "Start the observe daemon (set LOUSHO_OBSERVE to its URL), or pass `instructions` as a fallback.";
     readonly LOUSHO_TOOL_NOT_FOUND: "Use one of the tool names listed in the message, or register the tool yourself.";
     readonly LOUSHO_TOOL_NEEDS_CREDENTIALS: "Build the agent with createAgent() and pass the configured tool.";
     readonly LOUSHO_TOOL_EXECUTION_FAILED: "Look at the tool's own error (the `cause`) and fix the tool or its input.";

api/mcp.api.md

@@ -560,6 +560,7 @@ const ERROR_CODES: {
     readonly LOUSHO_REGISTRY_UNSAFE_PATH: "Do not install this item; it asks to write outside its allowed folder or is too large, so tell the registry owner.";
     readonly LOUSHO_REGISTRY_FILE_EXISTS: "Pass --overwrite to replace the existing file, or move your file away first.";
     readonly LOUSHO_REGISTRY_MANIFEST_MISMATCH: "Do not install this item: its code reaches for something its permission manifest does not declare; tell the registry owner, who fixes the code or the manifest.";
+    readonly LOUSHO_PROMPT_UNRESOLVED: "Start the observe daemon (set LOUSHO_OBSERVE to its URL), or pass `instructions` as a fallback.";
     readonly LOUSHO_TOOL_NOT_FOUND: "Use one of the tool names listed in the message, or register the tool yourself.";
     readonly LOUSHO_TOOL_NEEDS_CREDENTIALS: "Build the agent with createAgent() and pass the configured tool.";
     readonly LOUSHO_TOOL_EXECUTION_FAILED: "Look at the tool's own error (the `cause`) and fix the tool or its input.";

api/testing.api.md

@@ -82,6 +82,7 @@ const ERROR_CODES: {
     readonly LOUSHO_REGISTRY_UNSAFE_PATH: "Do not install this item; it asks to write outside its allowed folder or is too large, so tell the registry owner.";
     readonly LOUSHO_REGISTRY_FILE_EXISTS: "Pass --overwrite to replace the existing file, or move your file away first.";
     readonly LOUSHO_REGISTRY_MANIFEST_MISMATCH: "Do not install this item: its code reaches for something its permission manifest does not declare; tell the registry owner, who fixes the code or the manifest.";
+    readonly LOUSHO_PROMPT_UNRESOLVED: "Start the observe daemon (set LOUSHO_OBSERVE to its URL), or pass `instructions` as a fallback.";
     readonly LOUSHO_TOOL_NOT_FOUND: "Use one of the tool names listed in the message, or register the tool yourself.";
     readonly LOUSHO_TOOL_NEEDS_CREDENTIALS: "Build the agent with createAgent() and pass the configured tool.";
     readonly LOUSHO_TOOL_EXECUTION_FAILED: "Look at the tool's own error (the `cause`) and fix the tool or its input.";

api/tools.api.md

@@ -656,6 +656,7 @@ const ERROR_CODES: {
     readonly LOUSHO_REGISTRY_UNSAFE_PATH: "Do not install this item; it asks to write outside its allowed folder or is too large, so tell the registry owner.";
     readonly LOUSHO_REGISTRY_FILE_EXISTS: "Pass --overwrite to replace the existing file, or move your file away first.";
     readonly LOUSHO_REGISTRY_MANIFEST_MISMATCH: "Do not install this item: its code reaches for something its permission manifest does not declare; tell the registry owner, who fixes the code or the manifest.";
+    readonly LOUSHO_PROMPT_UNRESOLVED: "Start the observe daemon (set LOUSHO_OBSERVE to its URL), or pass `instructions` as a fallback.";
     readonly LOUSHO_TOOL_NOT_FOUND: "Use one of the tool names listed in the message, or register the tool yourself.";
     readonly LOUSHO_TOOL_NEEDS_CREDENTIALS: "Build the agent with createAgent() and pass the configured tool.";
     readonly LOUSHO_TOOL_EXECUTION_FAILED: "Look at the tool's own error (the `cause`) and fix the tool or its input.";

api/worker.api.md

@@ -1297,6 +1297,7 @@ const ERROR_CODES: {
     readonly LOUSHO_REGISTRY_UNSAFE_PATH: "Do not install this item; it asks to write outside its allowed folder or is too large, so tell the registry owner.";
     readonly LOUSHO_REGISTRY_FILE_EXISTS: "Pass --overwrite to replace the existing file, or move your file away first.";
     readonly LOUSHO_REGISTRY_MANIFEST_MISMATCH: "Do not install this item: its code reaches for something its permission manifest does not declare; tell the registry owner, who fixes the code or the manifest.";
+    readonly LOUSHO_PROMPT_UNRESOLVED: "Start the observe daemon (set LOUSHO_OBSERVE to its URL), or pass `instructions` as a fallback.";
     readonly LOUSHO_TOOL_NOT_FOUND: "Use one of the tool names listed in the message, or register the tool yourself.";
     readonly LOUSHO_TOOL_NEEDS_CREDENTIALS: "Build the agent with createAgent() and pass the configured tool.";
     readonly LOUSHO_TOOL_EXECUTION_FAILED: "Look at the tool's own error (the `cause`) and fix the tool or its input.";

docs/errors.md

@@ -88,7 +88,7 @@ Find a code by area:
 
 | Area | Codes | When you meet them |
 | ---- | ----- | ------------------ |
-| [Configuration](#configuration) | [`LOUSHO_CONFIG_INVALID`](#lousho_config_invalid), [`LOUSHO_CONFIG_MISSING_PROVIDER`](#lousho_config_missing_provider), [`LOUSHO_CONFIG_MISSING_AGENT`](#lousho_config_missing_agent), [`LOUSHO_CONFIG_MISSING_INPUT`](#lousho_config_missing_input), [`LOUSHO_CONFIG_CONFLICTING_OPTIONS`](#lousho_config_conflicting_options), [`LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`](#lousho_config_missing_checkpoint_store), [`LOUSHO_CONFIG_RESOLVER_FAILED`](#lousho_config_resolver_failed) | A `createAgent()` or executor call that is missing or mixing options, or a config resolver that failed. |
+| [Configuration](#configuration) | [`LOUSHO_CONFIG_INVALID`](#lousho_config_invalid), [`LOUSHO_CONFIG_MISSING_PROVIDER`](#lousho_config_missing_provider), [`LOUSHO_CONFIG_MISSING_AGENT`](#lousho_config_missing_agent), [`LOUSHO_CONFIG_MISSING_INPUT`](#lousho_config_missing_input), [`LOUSHO_CONFIG_CONFLICTING_OPTIONS`](#lousho_config_conflicting_options), [`LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`](#lousho_config_missing_checkpoint_store), [`LOUSHO_CONFIG_RESOLVER_FAILED`](#lousho_config_resolver_failed), [`LOUSHO_PROMPT_UNRESOLVED`](#lousho_prompt_unresolved) | A `createAgent()` or executor call that is missing or mixing options, or a config resolver that failed. |
 | [Providers and peers](#providers-and-peers) | [`LOUSHO_PROVIDER_SPEC_INVALID`](#lousho_provider_spec_invalid), [`LOUSHO_PROVIDER_UNKNOWN`](#lousho_provider_unknown), [`LOUSHO_PROVIDER_MISSING_API_KEY`](#lousho_provider_missing_api_key), [`LOUSHO_PROVIDER_REQUEST_FAILED`](#lousho_provider_request_failed), [`LOUSHO_PROVIDER_RATE_LIMITED`](#lousho_provider_rate_limited), [`LOUSHO_PEER_MISSING`](#lousho_peer_missing), [`LOUSHO_HOSTED_TOOL_UNSUPPORTED`](#lousho_hosted_tool_unsupported), [`LOUSHO_UNSUPPORTED_CONTENT`](#lousho_unsupported_content) | Resolving a model string, a missing API key or peer package, a failed or rate-limited model request, a hosted tool the provider cannot run, a file the provider cannot send. |
 | [Agent spec files](#agent-spec-files) | [`LOUSHO_SPEC_NOT_FOUND`](#lousho_spec_not_found), [`LOUSHO_SPEC_INVALID`](#lousho_spec_invalid), [`LOUSHO_SPEC_UNKNOWN_FIELD`](#lousho_spec_unknown_field), [`LOUSHO_SPEC_UNSUPPORTED_FORMAT`](#lousho_spec_unsupported_format) | Loading an `AgentSpec` file with `loadSpec()` or `specToAgent()`. |
 | [Tools](#tools) | [`LOUSHO_TOOL_NOT_FOUND`](#lousho_tool_not_found), [`LOUSHO_TOOL_NEEDS_CREDENTIALS`](#lousho_tool_needs_credentials), [`LOUSHO_TOOL_EXECUTION_FAILED`](#lousho_tool_execution_failed), [`LOUSHO_TOOL_ARGS_INVALID`](#lousho_tool_args_invalid), [`LOUSHO_MCP_START_FAILED`](#lousho_mcp_start_failed), [`LOUSHO_MCP_CALL_FAILED`](#lousho_mcp_call_failed) | A tool the model called is unknown, needs credentials, threw, or got invalid arguments; a stdio MCP server did not start or a call to one failed. |
@@ -182,6 +182,22 @@ names the option and `error.cause` is what the function threw.
 
 **Example:** `createAgent({ provider, model: ({ metadata }) => plans[metadata.plan].model })` with an unknown plan.
 
+### LOUSHO_PROMPT_UNRESOLVED
+
+**Means:** `createAgent({ prompt: 'name@version' })` (or `LOUSHO_PROMPT`) has no
+`instructions` fallback and the prompt could not be fetched: the observe daemon
+is unreachable, answered 404 for that name and version, or `LOUSHO_OBSERVE` is
+not set. The first `send()` rejects and `stream()` ends with an `error` event;
+the model is never called, so the agent never runs without a system prompt. The
+message names the prompt ref.
+
+**Fix:** start the daemon (`lousho observe`) and set `LOUSHO_OBSERVE` to its URL,
+publish the prompt (`lousho prompt push`), or pass `instructions` as the fallback
+(with it set, an unreachable daemon only logs a warning and the run uses the
+embedded text). See [Observability](./observability.md).
+
+**Example:** `createAgent({ provider, prompt: 'mira@latest' })` with no daemon running.
+
 ## Providers and peers
 
 ### LOUSHO_PROVIDER_SPEC_INVALID

docs/observability.md

@@ -236,6 +236,19 @@ Prompts, model output and tool arguments/results are sensitive and large, so
 the `gen_ai.*` content attributes are **never recorded by default**. Opt in
 per agent with `createAgent({ exporter, captureContent: true })`.
 
+The exception is a local collector: when `LOUSHO_OBSERVE` points at loopback
+(`1`/`true`, or a URL whose host is `127.0.0.1`, `localhost` or `::1`),
+`createAgent` defaults `captureContent` to `true`, so the daemon's trace view
+shows the prompt, the model output and the tool arguments and results that
+explain a failure. The data stays in the daemon's db on your machine. Turn it
+off with `captureContent: false`; a collector beyond loopback keeps the
+opt-in default. The default applies to agents built with `createAgent`.
+
+`redactContent` keeps only the legacy `input`/`prompt`/`args`/`result`
+attributes off; it does not scrub `gen_ai.*` message content. On a loopback
+collector the message text, including any secret typed into a prompt, is
+stored in the local db, so set `captureContent: false` if that is not wanted.
+
 #### Advanced: the executor API
 
 With the executor, opt in per run:
@@ -404,8 +417,11 @@ The daemon also serves two stores agents can use at runtime:
 
 - **Prompt registry.** `createAgent({ prompt: 'name@version' })` or
   `LOUSHO_PROMPT` fetches instructions from it at build (`@latest` resolves
-  on the daemon; an unreachable daemon falls back to `instructions`). Every
-  run logs the exact version used. `lousho prompt push` publishes a new
+  on the daemon; an unreachable daemon falls back to `instructions`; with no
+  `instructions`, the run fails with `LOUSHO_PROMPT_UNRESOLVED`). A failed
+  fetch is not cached: the next run retries it, so a daemon that was briefly
+  down at build recovers without a restart. Every run logs the exact version
+  used. `lousho prompt push` publishes a new
   version.
 - **Context hub.** `hub()` / `hubTools()` let agents publish and query
   namespaced key-values scoped `private` (the writing agent only) or

llms-full.txt

@@ -8391,7 +8391,7 @@ Find a code by area:
 
 | Area | Codes | When you meet them |
 | ---- | ----- | ------------------ |
-| [Configuration](#configuration) | [`LOUSHO_CONFIG_INVALID`](#lousho_config_invalid), [`LOUSHO_CONFIG_MISSING_PROVIDER`](#lousho_config_missing_provider), [`LOUSHO_CONFIG_MISSING_AGENT`](#lousho_config_missing_agent), [`LOUSHO_CONFIG_MISSING_INPUT`](#lousho_config_missing_input), [`LOUSHO_CONFIG_CONFLICTING_OPTIONS`](#lousho_config_conflicting_options), [`LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`](#lousho_config_missing_checkpoint_store), [`LOUSHO_CONFIG_RESOLVER_FAILED`](#lousho_config_resolver_failed) | A `createAgent()` or executor call that is missing or mixing options, or a config resolver that failed. |
+| [Configuration](#configuration) | [`LOUSHO_CONFIG_INVALID`](#lousho_config_invalid), [`LOUSHO_CONFIG_MISSING_PROVIDER`](#lousho_config_missing_provider), [`LOUSHO_CONFIG_MISSING_AGENT`](#lousho_config_missing_agent), [`LOUSHO_CONFIG_MISSING_INPUT`](#lousho_config_missing_input), [`LOUSHO_CONFIG_CONFLICTING_OPTIONS`](#lousho_config_conflicting_options), [`LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE`](#lousho_config_missing_checkpoint_store), [`LOUSHO_CONFIG_RESOLVER_FAILED`](#lousho_config_resolver_failed), [`LOUSHO_PROMPT_UNRESOLVED`](#lousho_prompt_unresolved) | A `createAgent()` or executor call that is missing or mixing options, or a config resolver that failed. |
 | [Providers and peers](#providers-and-peers) | [`LOUSHO_PROVIDER_SPEC_INVALID`](#lousho_provider_spec_invalid), [`LOUSHO_PROVIDER_UNKNOWN`](#lousho_provider_unknown), [`LOUSHO_PROVIDER_MISSING_API_KEY`](#lousho_provider_missing_api_key), [`LOUSHO_PROVIDER_REQUEST_FAILED`](#lousho_provider_request_failed), [`LOUSHO_PROVIDER_RATE_LIMITED`](#lousho_provider_rate_limited), [`LOUSHO_PEER_MISSING`](#lousho_peer_missing), [`LOUSHO_HOSTED_TOOL_UNSUPPORTED`](#lousho_hosted_tool_unsupported), [`LOUSHO_UNSUPPORTED_CONTENT`](#lousho_unsupported_content) | Resolving a model string, a missing API key or peer package, a failed or rate-limited model request, a hosted tool the provider cannot run, a file the provider cannot send. |
 | [Agent spec files](#agent-spec-files) | [`LOUSHO_SPEC_NOT_FOUND`](#lousho_spec_not_found), [`LOUSHO_SPEC_INVALID`](#lousho_spec_invalid), [`LOUSHO_SPEC_UNKNOWN_FIELD`](#lousho_spec_unknown_field), [`LOUSHO_SPEC_UNSUPPORTED_FORMAT`](#lousho_spec_unsupported_format) | Loading an `AgentSpec` file with `loadSpec()` or `specToAgent()`. |
 | [Tools](#tools) | [`LOUSHO_TOOL_NOT_FOUND`](#lousho_tool_not_found), [`LOUSHO_TOOL_NEEDS_CREDENTIALS`](#lousho_tool_needs_credentials), [`LOUSHO_TOOL_EXECUTION_FAILED`](#lousho_tool_execution_failed), [`LOUSHO_TOOL_ARGS_INVALID`](#lousho_tool_args_invalid), [`LOUSHO_MCP_START_FAILED`](#lousho_mcp_start_failed), [`LOUSHO_MCP_CALL_FAILED`](#lousho_mcp_call_failed) | A tool the model called is unknown, needs credentials, threw, or got invalid arguments; a stdio MCP server did not start or a call to one failed. |
@@ -8485,6 +8485,22 @@ names the option and `error.cause` is what the function threw.
 
 **Example:** `createAgent({ provider, model: ({ metadata }) => plans[metadata.plan].model })` with an unknown plan.
 
+### LOUSHO_PROMPT_UNRESOLVED
+
+**Means:** `createAgent({ prompt: 'name@version' })` (or `LOUSHO_PROMPT`) has no
+`instructions` fallback and the prompt could not be fetched: the observe daemon
+is unreachable, answered 404 for that name and version, or `LOUSHO_OBSERVE` is
+not set. The first `send()` rejects and `stream()` ends with an `error` event;
+the model is never called, so the agent never runs without a system prompt. The
+message names the prompt ref.
+
+**Fix:** start the daemon (`lousho observe`) and set `LOUSHO_OBSERVE` to its URL,
+publish the prompt (`lousho prompt push`), or pass `instructions` as the fallback
+(with it set, an unreachable daemon only logs a warning and the run uses the
+embedded text). See [Observability](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/observability.md).
+
+**Example:** `createAgent({ provider, prompt: 'mira@latest' })` with no daemon running.
+
 ## Providers and peers
 
 ### LOUSHO_PROVIDER_SPEC_INVALID
@@ -13896,6 +13912,19 @@ Prompts, model output and tool arguments/results are sensitive and large, so
 the `gen_ai.*` content attributes are **never recorded by default**. Opt in
 per agent with `createAgent({ exporter, captureContent: true })`.
 
+The exception is a local collector: when `LOUSHO_OBSERVE` points at loopback
+(`1`/`true`, or a URL whose host is `127.0.0.1`, `localhost` or `::1`),
+`createAgent` defaults `captureContent` to `true`, so the daemon's trace view
+shows the prompt, the model output and the tool arguments and results that
+explain a failure. The data stays in the daemon's db on your machine. Turn it
+off with `captureContent: false`; a collector beyond loopback keeps the
+opt-in default. The default applies to agents built with `createAgent`.
+
+`redactContent` keeps only the legacy `input`/`prompt`/`args`/`result`
+attributes off; it does not scrub `gen_ai.*` message content. On a loopback
+collector the message text, including any secret typed into a prompt, is
+stored in the local db, so set `captureContent: false` if that is not wanted.
+
 #### Advanced: the executor API
 
 With the executor, opt in per run:
@@ -14064,8 +14093,11 @@ The daemon also serves two stores agents can use at runtime:
 
 - **Prompt registry.** `createAgent({ prompt: 'name@version' })` or
   `LOUSHO_PROMPT` fetches instructions from it at build (`@latest` resolves
-  on the daemon; an unreachable daemon falls back to `instructions`). Every
-  run logs the exact version used. `lousho prompt push` publishes a new
+  on the daemon; an unreachable daemon falls back to `instructions`; with no
+  `instructions`, the run fails with `LOUSHO_PROMPT_UNRESOLVED`). A failed
+  fetch is not cached: the next run retries it, so a daemon that was briefly
+  down at build recovers without a restart. Every run logs the exact version
+  used. `lousho prompt push` publishes a new
   version.
 - **Context hub.** `hub()` / `hubTools()` let agents publish and query
   namespaced key-values scoped `private` (the writing agent only) or

src/cli/prompt.ts

@@ -32,7 +32,8 @@ const HELP = `${USAGE}
 
 Manages the prompt registry a 'lousho observe' collector serves. Agents run with
 createAgent({ prompt: 'name@version' }) or LOUSHO_PROMPT=name@version and fetch their
-instructions here at build (falling back to embedded instructions when the daemon is down).
+instructions here at build (falling back to embedded instructions when the daemon is down; without
+them the run fails with LOUSHO_PROMPT_UNRESOLVED).
 
 Options:
   --name N       'push': the registry name (default: the file's basename, e.g. prompts/mira.txt -> mira; required for '-')