npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0-c - Mend

better-dsh 0.2.5 → 0.3.0-c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1002) hide show

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/custom-models.md DELETED Viewed

@@ -1,284 +0,0 @@
-<!--
-source: https://omp.sh/docs/custom-models
-fetched: 2026-09-06
--->
-# Custom models & providers
-> Connect omp to a local server, an OpenAI-compatible gateway, or a model that is not in the built-in catalog.
-## Connect a model omp does not already know
-Use a custom provider when your model runs at a private URL, behind a company gateway, or under an id that omp does not list. You can declare the exact model yourself or let omp discover the models exposed by the server.
-You often do **not** need this file for local inference. omp automatically looks for Ollama at `http://127.0.0.1:11434`, llama.cpp at `http://127.0.0.1:8080`, and LM Studio at `http://127.0.0.1:1234/v1`. Start the server and open `/model`; if its models are already there, select one and stop.
-Otherwise, create `~/.omp/agent/models.yml`. This is the smallest valid configuration for an unauthenticated server that implements OpenAI Chat Completions:
-```yaml
-providers:
-  local-openai:
-    baseUrl: http://127.0.0.1:8000/v1
-    api: openai-completions
-    auth: none
-    models:
-      - id: Qwen/Qwen2.5-Coder-32B-Instruct
-```
-The provider id, `local-openai`, is yours to choose. The model `id` must be the exact id accepted by the server. Use `openai-responses` instead if the server implements `/v1/responses` rather than `/v1/chat/completions`.
-For a newly declared model, omitted metadata defaults to its id as the display name, text-only input, no configurable reasoning, a 128,000-token context window, a 16,384-token output limit, and zero cost. Those defaults make a minimal entry usable, but you should set the real limits and capabilities when they differ.
-## Verify and select it
-First ask omp to load the file and list just your provider:
-```bash
-omp models local-openai
-```
-A valid, available model appears under `local-openai` with its context, output, thinking, and image capabilities. A YAML or schema problem instead prints `models.yml validation failed` and the field that failed.
-Then exercise the endpoint with an exact selector:
-```bash
-omp -p --model local-openai/Qwen/Qwen2.5-Coder-32B-Instruct "Reply with only OK"
-```
-Exact `provider/model-id` selectors avoid ambiguity when several providers expose the same model id. To make it your normal interactive model, start `omp`, enter `/model`, find the provider and model, and assign it to **Default**. The model hub reloads `models.yml` when it opens and saves the role assignment. `/switch` (or <kbd>Alt</kbd>+<kbd>P</kbd>) switches only the current session.
-See [Model roles](/docs/roles) for assigning the same model to `smol`, `slow`, `plan`, or another role.
-## Add authentication
-For a remote OpenAI-compatible service, point `apiKey` at an environment variable:
-```yaml
-providers:
-  myco:
-    baseUrl: https://llm.internal.example/v1
-    apiKey: MYCO_LLM_API_KEY
-    api: openai-responses
-    models:
-      - id: myco-large
-        name: MyCo Large
-        reasoning: true
-        input: [text, image]
-        contextWindow: 200000
-        maxTokens: 32000
-        cost:
-          input: 3
-          output: 15
-          cacheRead: 0.3
-          cacheWrite: 3.75
-```
-```bash
-export MYCO_LLM_API_KEY='…'
-omp models myco
-```
-`apiKey` resolution is deliberate but worth knowing:
-1. A value beginning with `!` is a shell command; its trimmed stdout is the key.
-2. Otherwise, omp looks for an environment variable with that exact name.
-3. If no such variable exists, omp uses the configured text as the literal key.
-For example, `apiKey: "!op read op://team/llm/key"` reads from 1Password. Header values use the same rules. Prefer environment variables or secret-manager commands over committing a literal credential. See [Environment variables](/docs/env) and [Providers](/docs/providers) for built-in provider authentication.
-`auth` defaults to `apiKey`. Use `auth: none` only for a genuinely unauthenticated endpoint. `auth: oauth` is valid only when that provider's OAuth support is already supplied by omp or an extension; `models.yml` cannot define a new OAuth flow.
-Set `authHeader: true` only when a gateway specifically needs `Authorization: Bearer <resolved-apiKey>` injected as an ordinary header. Standard provider clients already apply their normal authentication scheme.
-## Discover a server's model list
-If an OpenAI-compatible server exposes `GET /v1/models`, discovery avoids maintaining a `models` list by hand:
-```yaml
-providers:
-  lab:
-    baseUrl: http://127.0.0.1:8000/v1
-    api: openai-completions
-    auth: none
-    discovery:
-      type: openai-models-list
-```
-Run `omp models refresh lab` to force an online refresh and show only matching models. Ordinary launches use the cached catalog when it is fresh.
-`discovery.type` accepts:
-| Type | Use it for |
-| --- | --- |
-| `ollama` | Ollama's native `/api/tags` and `/api/show` endpoints. |
-| `llama.cpp` | llama.cpp's native model and properties endpoints. |
-| `lm-studio` | LM Studio's OpenAI-compatible model list and metadata. |
-| `openai-models-list` | A generic OpenAI-compatible `GET /v1/models` endpoint. |
-| `litellm` | A LiteLLM gateway; uses its richer metadata routes and falls back to `/v1/models`. |
-| `proxy` | A mixed OpenAI/Anthropic proxy whose model rows advertise `supported_endpoint_types`. |
-Except for `proxy`, discovery requires provider-level `api`. `proxy` derives a model's API from its advertised endpoint types and uses provider-level `api` only as a fallback. Optional `discovery.timeoutMs` must be a positive number of milliseconds.
-Do not label a generic OpenAI-compatible server as `ollama`: Ollama discovery expects Ollama's native endpoints. Use `openai-models-list` instead.
-## Override a built-in provider
-A provider entry without `models` changes an existing provider rather than replacing its catalog. This is useful for a company gateway or for correcting metadata:
-```yaml
-providers:
-  openai:
-    baseUrl: https://gateway.internal.example/v1
-    apiKey: COMPANY_OPENAI_KEY
-    headers:
-      X-Team: coding
-    modelOverrides:
-      gpt-5.4:
-        contextWindow: 400000
-```
-Provider `headers`, `compat`, and `remoteCompaction` are baselines. Model headers replace provider headers with the same name, and `modelOverrides` patches one bundled or discovered model. If a custom `models` entry uses the same provider and id as an existing model, the custom definition replaces that model's transport configuration.
-## File and provider reference
-The default path is `~/.omp/agent/models.yml`; `~/.omp/agent/models.yaml` is used when the `.yml` file is absent. If neither YAML file exists and legacy `models.json` does, omp migrates it to `models.yml`. The root object accepts only `providers`.
-Each key below `providers` becomes the provider portion of the selector.
-| Provider field | Meaning |
-| --- | --- |
-| `baseUrl` | Endpoint root. Required when `models` is non-empty. It must be a non-empty string. |
-| `api` | Default API for declared or discovered models. May instead be set on every declared model. |
-| `apiKey` | Environment-variable name, `!command`, or literal credential. Required for declared models unless `auth` is `none` or `oauth`. |
-| `auth` | `apiKey` (default), `none`, or `oauth`. |
-| `headers` | String-to-string request headers. Values support environment-variable and `!command` resolution. |
-| `authHeader` | When true, adds a Bearer `Authorization` header from `apiKey`. |
-| `models` | Full model definitions owned by this provider. |
-| `discovery` | Live catalog configuration: `type` plus optional positive `timeoutMs`. |
-| `modelOverrides` | Map from model id to sparse metadata patches. |
-| `compat` | Advanced request/response compatibility overrides; normally omit it and use omp's automatic detection. |
-| `disableStrictTools` | Disables strict tool-schema markers for endpoints, commonly Anthropic-compatible proxies, that reject them. |
-| `remoteCompaction` | Provider-wide remote compaction configuration. Model values merge on top. |
-| `guardrailIdentifier` | Amazon Bedrock guardrail id or ARN. |
-| `guardrailVersion` | Bedrock guardrail version; defaults to `DRAFT` when a guardrail is set. |
-| `guardrailTrace` | Bedrock trace mode: `enabled`, `disabled`, or `enabled_full`. |
-| `transport` | Only `pi-native`; routes through a compatible `omp auth-gateway`. Requires that gateway as `baseUrl` and its bearer as `apiKey`. |
-A provider without models must still do something: set at least one usable override such as `baseUrl`, `headers`, `apiKey`, `auth: none`, `compat`, `disableStrictTools`, `guardrailIdentifier`, `remoteCompaction`, `modelOverrides`, or `discovery`.
-### API values
-| `api` value | Endpoint family |
-| --- | --- |
-| `openai-completions` | OpenAI-compatible Chat Completions. |
-| `openai-responses` | OpenAI-compatible Responses API. |
-| `openai-codex-responses` | Codex-flavored Responses API. |
-| `azure-openai-responses` | Azure-hosted Responses API. |
-| `anthropic-messages` | Anthropic Messages API. |
-| `bedrock-converse-stream` | Amazon Bedrock Converse streaming. |
-| `google-generative-ai` | Gemini public API. |
-| `google-gemini-cli` | Gemini CLI-compatible API. |
-| `google-vertex` | Gemini through Vertex AI. |
-These are the transports built into omp. An endpoint with a different wire protocol requires an extension, not another string in `models.yml`.
-## Model field reference
-| Model field | Meaning |
-| --- | --- |
-| `id` | Required, non-empty upstream model id. |
-| `name` | Picker label; defaults to `id`. |
-| `api` | Overrides provider `api` for this model. |
-| `baseUrl` | Overrides provider `baseUrl` for this model. |
-| `reasoning` | Marks the model as reasoning-capable. Must be true for a `thinking` control surface to apply. |
-| `thinking` | Explicit effort controls; see below. Omit it to let known model identity and compatibility determine controls. |
-| `input` | Supported inputs: `[text]` or `[text, image]`. |
-| `imageInputDecoder` | Only `stb`; converts WebP input for a local backend that cannot decode it. |
-| `tokenizer` | Optional local token estimator: `claude-v3`, `claude-v47`, `claude-v5`, `claude-v5-sonnet`, `qwen3`, `deepseek-v3`, `kimi-k2`, or `glm5`. |
-| `supportsTools` | Whether the endpoint supports tool calling. |
-| `cost` | Per-million-token rates. A full definition requires `input`, `output`, `cacheRead`, and `cacheWrite`. |
-| `premiumMultiplier` | Multiplier applied to reported model cost. |
-| `contextWindow` | Positive total context-token limit used by the context meter and overflow handling. |
-| `maxTokens` | Positive maximum output tokens. |
-| `omitMaxOutputTokens` | Omits the maximum-output-token request field when true. |
-| `headers` | Per-model headers, merged over provider headers. Values support env names and `!command`. |
-| `compat` | Per-model compatibility overrides, merged over provider `compat`. |
-| `contextPromotionTarget` | Model id or `provider/model-id` to switch to after a context-overflow error, before compaction. |
-| `compactionModel` | Model selector to prefer for compaction. |
-| `remoteCompaction` | Per-model remote compaction settings. |
-`modelOverrides` accepts the same metadata fields except `id`, `api`, and `baseUrl`. Its `cost` object may be partial, while a full model definition's `cost` must contain all four rates.
-### Thinking fields
-A new explicit `thinking` block uses this shape:
-```yaml
-reasoning: true
-thinking:
-  mode: effort
-  efforts: [low, medium, high]
-  defaultLevel: medium
-```
-| Field | Meaning |
-| --- | --- |
-| `mode` | Required: `effort`, `budget`, `google-level`, `anthropic-adaptive`, or `anthropic-budget-effort`. |
-| `efforts` | Required for new configs: an ordered, non-empty subset of `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |
-| `defaultLevel` | Default from the supported effort set. |
-| `effortMap` | Optional mapping from those effort names to provider-specific strings. |
-| `supportsDisplay` | Whether the provider accepts a thinking-display preference. |
-Legacy `levels`, or the pair `minLevel` and `maxLevel`, are still accepted and normalized to `efforts`; prefer `efforts` in new files.
-### Remote compaction fields
-`remoteCompaction` may appear at provider, model, or override level. It accepts `enabled`, `api`, `endpoint`, `model`, `v2StreamingEnabled`, `v2Endpoint`, and `streamingEndpoint`. Endpoint and model strings must be non-empty. Leave this block out unless your provider offers a compatible server-side compaction endpoint.
-## Advanced compatibility fields
-Most OpenAI-compatible services work without `compat`. Set these fields only to match documented endpoint behavior or to address a concrete request error. Every field is optional; provider values form the baseline and model values merge over them.
-**Request and streaming:**`supportsStore`, `supportsDeveloperRole`, `supportsMultipleSystemMessages`, `maxTokensField` (`max_completion_tokens` or `max_tokens`), `supportsUsageInStreaming`, `supportsToolChoice`, `supportsForcedToolChoice`, `alwaysSendMaxTokens`, `strictResponsesPairing`, `streamIdleTimeoutMs`, `cacheControlFormat` (`anthropic`), `supportsLongPromptCacheRetention`, `supportsImageDetailOriginal`, and `extraBody`.
-**Reasoning:**`supportsReasoningEffort`, `supportsReasoningParams`, `reasoningEffortMap`, `thinkingFormat` (`openai`, `openrouter`, `zai`, `qwen`, or `qwen-chat-template`), `qwenTemplateReasoningEffort`, `reasoningContentField` (`reasoning_content`, `reasoning`, or `reasoning_text`), `requiresReasoningContentForToolCalls`, `allowsSyntheticReasoningContentForToolCalls`, `requiresAssistantContentForToolCalls`, `disableReasoningOnForcedToolChoice`, `disableReasoningOnToolChoice`, and `whenThinking`. `whenThinking` contains another partial compatibility block applied only while thinking is active.
-**Tools and message history:**`requiresToolResultName`, `requiresMistralToolIds`, `requiresAssistantAfterToolResult`, `requiresThinkingAsText`, `supportsStrictMode`, `toolStrictMode` (`all_strict` or `none`), and `requiresToolResultId`.
-**Streaming and Anthropic-compatible behavior:**`streamMarkupHealingPattern` (`kimi`, `dsml`, `qwen`, or `thinking`), `supportsEagerToolInputStreaming`, `allowAnthropicHeaderOverrides`, and `replayUnsignedThinking`.
-**Gateway routing:**`openRouterRouting` and `vercelGatewayRouting`, each with optional `only` and `order` string lists.
-**Bedrock prompt caching:**`promptCacheMode` (`none`, `automatic`, or `explicit`), `promptCacheMinimumTokens`, `promptCacheMaximumCheckpoints`, and `supportsLongPromptCacheRetention`.
-## Troubleshooting
-### The provider does not appear
-Run `omp models <provider-id>`. One invalid custom entry disables custom providers from that file for the run, while built-in providers remain available. Check these rules first:
-- A provider with `models` needs `baseUrl`.
-- It needs `apiKey`, unless `auth` is `none` or already-supported `oauth`.
-- It needs provider-level `api` or an `api` on every model.
-- `id` must be non-empty; provided `contextWindow` and `maxTokens` must be positive.
-- The root key is `providers`; settings such as `modelRoles` and `modelProviderOrder` belong in `config.yml`, not `models.yml`.
-### The model appears but requests return 401 or 403
-Confirm that the environment variable named by `apiKey` is exported in the shell that starts omp. Remember that a missing variable name falls back to a literal token, so `apiKey: MYCO_LLM_API_KEY` can still load even when the variable is absent. Check whether the service expects its normal SDK auth header or an explicit Bearer header; only the latter needs `authHeader: true`.
-### Requests return 404 or “unsupported endpoint”
-Check the API family and URL together. `openai-completions` needs Chat Completions, while `openai-responses` needs Responses. Generic OpenAI-compatible base URLs commonly end in `/v1`; llama.cpp discovery accepts its native root and normalizes model request URLs itself.
-### Discovery returns no models
-Make sure the server is running, then run `omp models refresh <provider-id>`. Use `ollama` only for native Ollama endpoints and `openai-models-list` for a generic `/v1/models` service. If the server is remote or slow, set a larger positive `discovery.timeoutMs`.
-### Tool calls or reasoning fail with a 400
-For an Anthropic-compatible proxy that rejects strict tool schemas, set `disableStrictTools: true`. For an OpenAI-compatible dialect mismatch, change only the relevant `compat` field named by the service's error; broad copied compatibility blocks can disable features the endpoint actually supports.
-### Context or usage numbers look wrong
-Discovered endpoints do not always report reliable metadata. Declare the model explicitly, or add a `modelOverrides` entry with the real `contextWindow`, `maxTokens`, `input`, `reasoning`, and `cost` values.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/custom-tools.md DELETED Viewed

@@ -1,248 +0,0 @@
-<!--
-source: https://omp.sh/docs/custom-tools
-fetched: 2026-09-06
--->
-# Custom tools
-> Give omp a typed, project-specific action, then use it from ordinary prompts like any built-in capability.
-## Add an action that omp does not have
-A custom tool is a small TypeScript or JavaScript module that lets omp call code you control. It is useful for project-specific work such as querying an internal service, checking a domain invariant, or performing a carefully bounded operation.
-Start with a project tool so its source can be reviewed with the repository. Create `.omp/tools/hello/index.ts`, restart omp from the project, and ask it to use the tool. Use an [MCP server](/docs/mcp) instead when the capability already lives in a separate service or needs to be shared by several clients.
-> **Custom tools are trusted code.** omp imports discovered tool modules and runs them with your user account's permissions. Review project-local `.omp/tools` code before opening omp in an unfamiliar repository.
-## Create the smallest tool
-From the project root:
-```bash
-mkdir -p .omp/tools/hello
-```
-Create `.omp/tools/hello/index.ts`:
-```ts
-import type { CustomToolFactory } from "@oh-my-pi/pi-coding-agent";
-const factory: CustomToolFactory = pi => ({
-  name: "hello",
-  label: "Hello",
-  description: "Greet a person by name",
-  parameters: pi.zod.object({
-    name: pi.zod.string().describe("The person to greet"),
-  }),
-  async execute(_toolCallId, params) {
-    return {
-      content: [{ type: "text", text: `Hello, ${params.name}!` }],
-      details: { greeted: params.name },
-    };
-  },
-});
-export default factory;
-```
-No schema package needs to be installed for this example. omp injects the schema builders into the factory as `pi`.
-### Load and test it
-Tool discovery happens when a session starts. Exit any running session, then launch omp again from the project root:
-```bash
-omp
-```
-Enter `/tools` and confirm that `hello` is listed. Then prompt:
-```text
-Use the hello tool to greet Ada.
-```
-You should see a **Hello** tool card and a final result containing `Hello, Ada!`. For a one-shot check, start a fresh process:
-```bash
-omp -p 'Use the hello tool to greet Ada.'
-```
-You write the factory and its `execute` function; you do **not** call `execute` or enter a JSON tool request. The model chooses the tool from your natural-language request, constructs arguments that match `parameters`, and omp validates those arguments before running your code. A precise `description`, field descriptions, and narrow schemas make that choice more reliable.
-## Choose where it loads
-| Scope | Recommended path | Use it when |
-| --- | --- | --- |
-| Project | `.omp/tools/<name>/index.ts` | The tool belongs to one repository and should be reviewed with it. |
-| User | `<active-config-dir>/tools/<name>/index.ts` | You want the tool in every project for the active omp profile. Run `omp config path` to print the active config directory; the default is `~/.omp/agent`. |
-The native omp directories also accept flat `.ts` and `.js` files such as `.omp/tools/hello.ts`. A named subdirectory with `index.ts` is preferable when the tool has supporting files. omp also discovers flat `.ts` and `.js` tools in user and project `.claude/tools` and `.codex/tools` directories for compatibility.
-A discovered `.md` or `.json` file is metadata, not an executable tool module. The executable module must export a factory function; a default export is the supported, unambiguous form shown above.
-## Factory and definition API
-Import `CustomToolFactory` from `@oh-my-pi/pi-coding-agent`. A factory may return one tool, an array of tools, or a promise of either. Each returned tool name must be unique across built-ins and every other loaded custom tool.
-### Required fields
-| Field | Author contract |
-| --- | --- |
-| `name` | Registry name used to identify the tool. Do not reuse a built-in or another custom tool name. |
-| `label` | Human-readable name shown in the TUI. |
-| `description` | Short, specific guidance that helps the model decide when the tool applies. |
-| `parameters` | Schema for accepted arguments. omp derives the TypeScript type of `params` from it and validates calls before `execute`. |
-| `execute` | Async implementation that returns an `AgentToolResult`. |
-### Optional behavior
-| Field | Effect |
-| --- | --- |
-| `strict` | Requests strict schema handling for the tool. |
-| `hidden` | Keeps the tool disabled unless it is explicitly selected. |
-| `loadMode` | `"discoverable"` keeps the schema out of the always-present tool set; `"essential"` keeps it top-level. Custom tools default to `"discoverable"`. |
-| `approval` | Declares the capability tier: `"read"`, `"write"`, or `"exec"`; it may also be a decision object or a function of the parsed arguments. An omitted approval is treated as `"exec"`. |
-| `onSession` | Receives lifecycle events for setup, state changes, and cleanup. |
-| `renderCall` | Replaces the default TUI rendering of the call. |
-| `renderResult` | Replaces the default TUI rendering of partial and final results. |
-`renderCall(args, options, theme)` and `renderResult(result, options, theme)` return a `Component` from `@oh-my-pi/pi-tui`. Their `options` include `expanded` and `isPartial`; partial renders can also receive `spinnerFrame`. Renderers affect what the person sees, not what the model receives.
-## Parameter schemas
-The factory host supplies three public schema builders:
-| Builder | Guidance |
-| --- | --- |
-| `pi.zod` | Zod-compatible builder used in the starter example. |
-| `pi.arktype` | Native omptype/ArkType builder. |
-| `pi.typebox` | Compatibility shim for tools authored against the older TypeBox-style API. Prefer a current builder for new tools. |
-Keep schemas as small as the operation allows. Use enums for finite actions, describe fields whose meaning is not obvious, and put defaults in the schema when omission has a safe meaning.
-```ts
-parameters: pi.zod.object({
-  action: pi.zod.enum(["check", "summarize"]),
-  path: pi.zod.string().describe("Repository-relative file path"),
-  limit: pi.zod.number().int().positive().optional().default(20),
-}),
-```
-## Execution, progress, and cancellation
-The complete execution signature is:
-```ts
-async execute(toolCallId, params, onUpdate, ctx, signal) {
-  // ...
-}
-```
-| Argument | Use |
-| --- | --- |
-| `toolCallId` | Correlate logs or UI state for this invocation. |
-| `params` | Validated, schema-typed arguments. |
-| `onUpdate` | Optional callback for partial progress shown to the user. The model receives the final returned `content`, not these progress updates. |
-| `ctx` | `CustomToolContext` for advanced session-aware tools. Ordinary tools should prefer the stable factory host API and avoid depending on session internals. |
-| `signal` | Optional `AbortSignal`. Check it in long-running work and forward it to cancellable operations. |
-The factory host exposes the session working directory as `pi.cwd` and a cancellation-aware process helper as `pi.exec(command, args, options?)`:
-```ts
-async execute(_id, params, onUpdate, _ctx, signal) {
-  onUpdate?.({
-    content: [{ type: "text", text: `Checking ${params.path}…` }],
-  });
-  const result = await pi.exec("git", ["status", "--short", "--", params.path], {
-    cwd: pi.cwd,
-    signal,
-  });
-  if (result.code !== 0) {
-    throw new Error(result.stderr || "git status failed");
-  }
-  return { content: [{ type: "text", text: result.stdout || "No changes" }] };
-}
-```
-Interactive UI methods are available through `pi.ui` only when `pi.hasUI` is true. Print, RPC, and other headless modes do not provide an interactive UI, so every tool intended for those modes must have a non-interactive path.
-## Results and errors
-Return an `AgentToolResult`:
-```ts
-return {
-  content: [
-    { type: "text", text: "Check complete." },
-    { type: "image", mimeType: "image/png", data: pngBase64 },
-  ],
-  details: { checked: 12 },
-  isError: false,
-};
-```
-- `content` is required. It contains text and/or base64 image blocks and is the result the model can use in its next step.
-- `details` is optional structured state for UI rendering, logging, and history. It is not substituted for user-readable `content`.
-- `isError: true` marks an expected, non-throwing failure while preserving a structured result.
-Throw an `Error` for failures that prevent the operation from producing a useful result. omp converts a thrown or rejected error into a failed tool result for the model and shows the failure to the user. Use `isError: true` when your tool intentionally catches a domain failure and can return a clear, structured explanation itself. Never hide a failure behind successful-looking content.
-Forward `signal` to `pi.exec` and other cancellable APIs. That allows the user's stop action to cancel subprocess work instead of leaving it running.
-## Session lifecycle
-Add `onSession(event, ctx)` only when the tool owns resources or state that must follow session changes. It may be synchronous or async.
-```ts
-onSession(event) {
-  if (event.reason === "shutdown") {
-    // Close resources created by this factory.
-  }
-},
-```
-`event` is a discriminated union. Current reasons are:
-| Reasons | When they occur |
-| --- | --- |
-| `start`, `switch`, `branch`, `tree`, `shutdown` | Session creation, navigation, and teardown. These events carry `previousSessionFile`; it is populated for switch/branch and otherwise may be undefined. |
-| `auto_compaction_start`, `auto_compaction_end` | Before and after automatic context compaction. |
-| `auto_retry_start`, `auto_retry_end` | Before and after automatic retry handling. |
-| `ttsr_triggered` | When runtime rules trigger. |
-| `todo_reminder` | When a todo reminder is emitted. |
-Lifecycle errors are logged as warnings and do not crash the session. Keep cleanup idempotent and keep durable state outside in-memory closures if it must survive process restarts.
-## Troubleshooting
-### `/tools` does not list the tool
-1. Restart omp; direct custom-tool directories are scanned at session startup.
-2. Confirm the project session was launched from the directory containing `.omp/tools`.
-3. Confirm the module is a `.ts` or `.js` file and default-exports a function.
-4. Check that the factory returns an object with `name`, `description`, `parameters`, and `execute`.
-5. Look for `Custom tool load failed` in today's logs under `~/.omp/logs/`.
-### The module loads, but this tool is missing
-Its `name` probably collides with a built-in or a tool loaded earlier. Collisions are rejected; there is no override flag. Rename the tool and restart omp.
-### The model does not choose it
-Make the tool `description` say exactly when it should be used, describe ambiguous parameters, and narrow broad strings to enums or constrained schemas. During testing, name the tool explicitly in your natural-language prompt. Use `loadMode: "essential"` only when the tool must remain top-level on every request; otherwise keep the discoverable default.
-### It works interactively but fails in print or RPC mode
-The implementation probably assumes a TUI. Guard calls to `pi.ui` with `pi.hasUI` and provide a headless behavior, or return a clear error explaining that the operation requires an interactive session.
-## Related
-- [MCP](/docs/mcp) — expose tools served by an external process.
-- [Extension authoring](/docs/extension-authoring) — package tools with commands and event behavior.
-- [Hooks](/docs/hooks) — observe or change existing tool calls instead of adding a new capability.
-- [Plugins](/docs/plugins) — distribute tools with other omp customizations.