@agimon-ai/po-codemode 0.0.1-alpha.2 → 0.0.1-alpha.20

package/README.md

@@ -7,7 +7,7 @@ This package is a composable [Po](https://www.npmjs.com/package/@agimon-ai/po) s
 ## Requirements
 
 - Node.js 24 or newer
-- `@earendil-works/pi-coding-agent` 1.3.0
+- `@earendil-works/pi-coding-agent` 1.4.0
 
 ## Install
 
@@ -19,26 +19,38 @@ The package declares poServer metadata for native server discovery. Include it t
 
 ## Use
 
-Run the registered command in the cockpit:
+Call `discover({})` to list the session's contributed namespaces and reusable scripts. Use `exec` to run a TypeScript async function body against them.
 
-```text
-/po-codemode
-```
+## Package behavior
 
-Show code mode namespaces
+Call `discover({ namespace: 'browser' })` for current types, then `exec({ code: 'return await browser.snapshot({});' })`. Namespace plugins supply their own `codemode-how-to-<plugin>` guides. Their summaries and the base `how-to-codemode` guide stay in the system prompt, outside skill search; `load_skill` still reads their full instructions by exact name.
 
-## Package behavior
+### npm imports
+
+On Node hosts, `await import('npm:is-number@7')` auto-installs through upm and returns the real module namespace. Registry names, scopes, versions, ranges, tags and subpaths are supported. The shared store uses the existing two-day release-age policy (exact and locked versions bypass it); lifecycle scripts are skipped. First installs may need a larger exec `timeoutMs`.
+
+Packages run with full Node authority. Native code is not preemptible, package resources are not automatically closed, and cancellation cannot stop an install already in progress. `new` works on imported constructors; subclassing and `instanceof` are unsupported. Edge hosts cannot import. Script globals still omit `fetch`, `require` and `process`.
+
+### Short Bash commands
+
+`shell.bash({ command, timeoutMs? })` returns `{ stdout, stderr, exitCode }` for code-side post-processing. It runs in the session cwd with its admitted environment. Nonzero exits are returned; startup failures, timeout and cancellation reject. The deadline defaults to 10 seconds (maximum 120 seconds) and the command is cancelled when exec ends. Each output stream is capped at 32768 characters with a `[truncated]` marker.
+
+This is foreground-only execution, not Runner supervision: no background option, interactive terminal, Runner IDs or persistent logs. The standalone Runner `bash` tool remains visible for those workflows. See [shell guidance](./src/prompts/codemode-how-to-shell/SKILL.md).
+
+### LLM transformations
+
+`llm.complete({ prompt, input? })` returns `{ text, model }`; `llm.json({ prompt, input?, schema })` returns `{ value, model }`. Calls are stateless, use no session history, and count toward session usage. JSON results require one private `return_result` call and local schema validation; tool choice is prompt-directed.
 
-> Before publishing, replace this paragraph with one concrete, copy-pasteable example of the package-specific input, output, configuration, or workflow that is not already demonstrated by the generated command.
+Set the optional `llmModel: provider/id` in the `@agimon-ai/po-codemode` package configuration to choose a default. A per-call `model` wins, otherwise the current session model is used. Limits per exec are 8 calls and 2 concurrent calls, with 64 KiB input per call and 1024 default / 4096 maximum output tokens. There are no retries. See [LLM guidance](./src/prompts/codemode-how-to-llm/SKILL.md) for pipelines and schema constraints.
 
-## Help
+## How-to guide
 
-The published package includes `llms.txt` and `src/prompts/po-use-codemode/SKILL.md`. Link additional prompts from `llms.txt` and declare them through named `resource/*.server.ts` routes using `defineResource`. Server lifecycle registration owns their disposal. Publish prompts under `src/prompts`, never export Markdown or copy it into `dist`.
+The published package includes `llms.txt` and `src/prompts/how-to-codemode/SKILL.md`. Link additional prompts from `llms.txt` and declare them through named `resource/*.server.ts` routes using `defineResource`. Server lifecycle registration owns their disposal. Publish prompts under `src/prompts`, never export Markdown or copy it into `dist`.
 
 ## Public API
 
 ```ts
-import { DefaultCodemodeExtensionService } from '@agimon-ai/po-codemode';
+import { createCodemodeRegistry, createCodemodeTools } from '@agimon-ai/po-codemode';
 ```
 
 The native server entry is also available at: