@vedmalex/ai-connect 0.7.0 → 0.9.0

package/README.md

@@ -215,6 +215,27 @@ const result = await client.generate({
 });
 ```
 
+#### ACP model selection + headless harness-noise suppression
+
+For headless / batch prompts (e.g. per-document extraction) the ACP transport drives an interactive coding agent. Two behaviours make that robust by default:
+
+- **Model via the protocol.** The route's model (`routeHints.model ?? account model`) is selected through a `session/set_model` call after `session/new` — you do **not** need to inject an `ANTHROPIC_MODEL` env var, and there is no env-driven "model switched" announcement leaking into the output. The call is sent only when the agent advertises a model catalog, the requested model is in its `availableModels`, and it differs from the current model; a model the agent does not advertise is surfaced as a `warning` (it is not silently replaced by the agent default).
+- **Harness-noise suppression + guard.** Known interactive-harness marker lines (a model-switch announcement, a `Готов к работе` / `Жду …` idle greeting, `<local-command-caveat>` commentary) are filtered out of the answer text on both the `generate` and the streaming (`delta`) paths. If a turn yields **only** such harness chatter and no task output, it is surfaced as `temporary_unavailable` so the consumer can retry / fall back rather than receiving the greeting as a successful generation.
+
+All three are on by default and can be toggled via `acp` client options:
+
+```ts
+const client = createLocalClient(config, {
+  acp: {
+    selectModel: true,            // session/set_model from the route model (default true)
+    suppressHarnessNoise: true,   // filter harness marker lines from text + deltas (default true)
+    failOnHarnessOnlyTurn: true,  // harness-only turn → temporary_unavailable (default true)
+  },
+});
+```
+
+> Limitation: the harness-noise filter / guard recognises a curated, locale-specific marker set (Claude harness, RU greetings). A reworded or other-locale greeting that still carries non-marker text is not classified as harness-only. The model-switch root cause is removed independently by `selectModel`.
+
 Dedicated provider-specific ACP examples:
 
 - [examples/acp-claude.ts](/Users/vedmalex/work/ai-connect/examples/acp-claude.ts)
@@ -1059,7 +1080,7 @@ Use explicit runtime entry points when you know the target in advance:
 Notes:
 
 - `@vedmalex/ai-connect/browser` is the browser-safe bundle.
-- `@vedmalex/ai-connect` defaults to the full Node/Bun-oriented entry.
+- `@vedmalex/ai-connect` defaults to the full Node/Bun-oriented entry. Its `package.json` `exports` already resolve the `node` and `bun` conditions to the respective builds, so `@vedmalex/ai-connect/node` and `@vedmalex/ai-connect/bun` are just explicit aliases of `.` — both are built from the same `src/index.ts` entry (esbuild, `node20` target). The `node` and `bun` outputs are byte-identical builds; the separate subpaths exist only for callers who want to name the target explicitly. Prefer the default `.` import unless you have a specific reason to pin one.
 - `@vedmalex/ai-connect/local` is the focused local runtime entry with ACP support.
 
 ## Public API
@@ -1291,12 +1312,24 @@ See:
 - [examples/acp-claude.ts](/Users/vedmalex/work/ai-connect/examples/acp-claude.ts)
 - [examples/acp-codex.ts](/Users/vedmalex/work/ai-connect/examples/acp-codex.ts)
 - [examples/browser-basic.ts](/Users/vedmalex/work/ai-connect/examples/browser-basic.ts)
+- [examples/browser-client-tools.ts](/Users/vedmalex/work/ai-connect/examples/browser-client-tools.ts)
+- [examples/cancellation-timeout.ts](/Users/vedmalex/work/ai-connect/examples/cancellation-timeout.ts)
+- [examples/clean-context.ts](/Users/vedmalex/work/ai-connect/examples/clean-context.ts)
+- [examples/fanout-throttle.ts](/Users/vedmalex/work/ai-connect/examples/fanout-throttle.ts)
+- [examples/health-probe.ts](/Users/vedmalex/work/ai-connect/examples/health-probe.ts)
+- [examples/image-edit-test.ts](/Users/vedmalex/work/ai-connect/examples/image-edit-test.ts)
+- [examples/image-test.ts](/Users/vedmalex/work/ai-connect/examples/image-test.ts)
+- [examples/image-workflow.ts](/Users/vedmalex/work/ai-connect/examples/image-workflow.ts)
 - [examples/local-acp.ts](/Users/vedmalex/work/ai-connect/examples/local-acp.ts)
+- [examples/local-client-tools.ts](/Users/vedmalex/work/ai-connect/examples/local-client-tools.ts)
 - [examples/local-test-server.ts](/Users/vedmalex/work/ai-connect/examples/local-test-server.ts)
+- [examples/model-context.ts](/Users/vedmalex/work/ai-connect/examples/model-context.ts)
+- [examples/model-selector.ts](/Users/vedmalex/work/ai-connect/examples/model-selector.ts)
+- [examples/pdf-document-input.ts](/Users/vedmalex/work/ai-connect/examples/pdf-document-input.ts)
+- [examples/public-routes.ts](/Users/vedmalex/work/ai-connect/examples/public-routes.ts)
 - [examples/rotation-fallback.ts](/Users/vedmalex/work/ai-connect/examples/rotation-fallback.ts)
-- [examples/image-test.ts](/Users/vedmalex/work/ai-connect/examples/image-test.ts)
-- [examples/image-edit-test.ts](/Users/vedmalex/work/ai-connect/examples/image-edit-test.ts)
-- [examples/image-workflow.ts](/Users/vedmalex/work/ai-connect/examples/image-workflow.ts)
+- [examples/streaming-deltas.ts](/Users/vedmalex/work/ai-connect/examples/streaming-deltas.ts)
+- [examples/usage-accounting.ts](/Users/vedmalex/work/ai-connect/examples/usage-accounting.ts)
 - [examples/wide-event-logging.ts](/Users/vedmalex/work/ai-connect/examples/wide-event-logging.ts)
 
 Example execution notes: