@worldapptechnologies/nulu-agent-tool-presentation 0.0.0-stage → 1.6.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+---
+description: "The agent-plane presentation selector for users and maintainers choosing, configuring, or debugging which form of its tools an agent preset's models see."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @worldapptechnologies/nulu-agent-tool-presentation
+
+
+## Summary
+
+Use `nulu-agent-tool-presentation` in an [agent preset](../../preset/agent-presets/README.md) to fix whether models see every native tool schema, only `run_code` with a generated SDK, or both forms. Each preset can choose independently, so native and PTC agents can share one process without sharing tool catalogs. Selecting `ptc` or `both` requires a compatible PTC runtime; a deployment without one rejects the preset at mount time before its first prompt. The `mode` field is required when this package is present, while omitting the package keeps the deployment default.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Add this row to an agent preset to fix how every agent joined to that preset sees its tools. `native` presents each visible tool schema as a function definition; `ptc` presents only the `run_code` transport plus a generated SDK and the rule that only `run_code` may be called directly; `both` presents both forms. Agents that declare nothing get the deployment-wide `mode` on the [`nulu-tools`](../tools/README.md) row.
+
+### Add the row to a preset
+
+```yaml
+- name: '@worldapptechnologies/nulu-agent-tool-presentation'
+  config:
+    mode: ptc
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `mode` | required | `native` — every schema; `ptc` — `run_code` plus generated SDK; `both` — both forms |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#worldapptechnologiesnulu-agent-tool-presentation) is the exhaustive source for every accepted field. `mode` is required rather than defaulted because a preset without this row inherits the deployment default.
+
+### What PTC mode requires
+
+Selecting `ptc` or `both` needs a composed PTC runtime (`ctx.ptcRuntime`) whose language has a registered SDK renderer — the TypeScript runtime ships via [`nulu-ptc-runtime-node`](../../ptc-runtime/ptc-runtime-node/README.md), and both the TypeScript and Python SDK renderers are built into `nulu-tools`. A preset that selects a PTC mode against a deployment composing no such runtime refuses to mount, naming this row, so the failure lands where the operator can act instead of at the session's first request.
+
+### One presentation per agent
+
+One agent declares one presentation. A second declaration in the same composition is refused rather than merged: two answers to "which form does the model see" is a contradiction, not an override.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the package realizes the behavior above; the observable contract is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The tool registry cannot move into a preset: its consumers are all host-plane — the agent loop reads its scheduler, the API proxy reads its presenters, and every tool plugin registers into it — and a service only moves down when all of its consumers move with it. What a preset can own is the presentation of that registry. `ctx.tools.presentAs()` declares it for the mounting scope, which is the preset's standing mount, so the declaration covers every agent joined to that preset and a PTC mode preset runs beside native ones in one process. One row per composition, not one per session.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `mode` config, `apply` wiring `ctx.tools.presentAs` for the mounting scope |
+| — | No runtime invariant companion is published; this package makes exactly one scoped call into `ctx.tools` and owns no event or snapshot of its own; the relation it establishes — which presentation one agent's assembly uses — is the tool registry's to hold, and `nulu-tools` observes it there. |
+
+### Behavior notes
+
+`native` applies immediately. A PTC mode instead waits for `ctx.ptcRuntime`, a host-plane service: a preset selecting PTC mode against a deployment composing no runtime holds this row pending, and `nulu-agent-presets` refuses the mount naming this id. `presentAs` is itself the effect, so the declaration unwinds with this row without a second wrapper owning it.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+The package-level contract is enough for most consumers; read these when you need the surrounding domain.
+
+- [tools package](../tools/README.md) — the tool presentation modes and `presentAs` API.
+- [agent-presets package](../../preset/agent-presets/README.md) — how presets compose agents and their standing mounts.
+- [Node ptc-runtime package](../../ptc-runtime/ptc-runtime-node/README.md) — the TypeScript runtime a PTC mode needs.
+- [PTC mode executor-collapse note](../../../.agents/notes/implemented/bug-fix/2026-08-07-ptc-executor-collapse.md) — why the announced and callable surfaces stay the same.
+- [Core group map](../README.md) — how the core packages compose.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the tool presentation it selects in `nulu-tools` — the row only chooses between the two projections `nulu-tools` owns and registers no prompt, schema, or result of its own.
+
+#### KV Cache effect
+
+No direct invalidation; the presentation is fixed when the agent is composed, so its request prefix is stable for the session's life.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when this row needs special care. They are current package constraints, not a task backlog.
+
+- **The runtime stays host-plane** — a preset can select PTC mode but cannot supply the TypeScript runtime it needs; a deployment that composes none can compose no PTC preset.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/lib/index.js

@@ -0,0 +1,51 @@
+import z from "@worldapptechnologies/schemastery";
+//#region lib/types/index.js
+/**
+* Agent-plane presentation selector: the row an agent preset carries to say
+* which form of its tools the model sees.
+*
+* The tool registry itself stays on the host plane — the agent loop's
+* scheduler, the API proxy's presenters, and every tool plugin are all its
+* consumers, so it cannot move into a preset. What a preset CAN own is the
+* presentation: `ctx.tools.presentAs()` declares it for the mounting SCOPE,
+* which is the preset's standing mount, so the declaration covers every agent
+* joined to that preset and a PTC mode preset runs beside native ones in one
+* process. One row per composition, not one per session.
+*
+* A PTC mode needs a TypeScript PTC runtime, which is a host-plane service
+* ([`nulu-ptc-runtime-node`](../../../ptc-runtime/ptc-runtime-node/README.md)).
+* This row therefore waits for it rather than assuming it: a preset selecting
+* PTC mode against a deployment that composes no runtime fails at mount, named
+* in the preset's own activation audit, instead of at the first prompt.
+* @module @worldapptechnologies/nulu-agent-tool-presentation
+*/
+/** Cordis plugin name. */
+const name = "tool-presentation";
+/**
+* Required services. `ptcRuntime` is NOT listed: a `native` row must mount in
+* a deployment that composes no runtime, and the mode-dependent wait is
+* declared inside {@link apply} instead.
+*/
+const inject = ["tools"];
+/** Runtime schema. */
+const Config = z.object({ mode: z.union([
+	"native",
+	"ptc",
+	"both"
+]).required() });
+/**
+* Declare the tool presentation for every agent this composition covers.
+* @param ctx - the mounting composition's scope context (a preset's standing scope).
+* @param config - the selected presentation.
+*/
+function apply(ctx, config) {
+	if (config.mode === "native") {
+		ctx.tools.presentAs("native");
+		return;
+	}
+	ctx.inject(["ptcRuntime"], (runtimeCtx) => {
+		runtimeCtx.tools.presentAs(config.mode);
+	});
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Agent-plane presentation selector: the row an agent preset carries to say
+ * which form of its tools the model sees.
+ *
+ * The tool registry itself stays on the host plane — the agent loop's
+ * scheduler, the API proxy's presenters, and every tool plugin are all its
+ * consumers, so it cannot move into a preset. What a preset CAN own is the
+ * presentation: `ctx.tools.presentAs()` declares it for the mounting SCOPE,
+ * which is the preset's standing mount, so the declaration covers every agent
+ * joined to that preset and a PTC mode preset runs beside native ones in one
+ * process. One row per composition, not one per session.
+ *
+ * A PTC mode needs a TypeScript PTC runtime, which is a host-plane service
+ * ([`nulu-ptc-runtime-node`](../../../ptc-runtime/ptc-runtime-node/README.md)).
+ * This row therefore waits for it rather than assuming it: a preset selecting
+ * PTC mode against a deployment that composes no runtime fails at mount, named
+ * in the preset's own activation audit, instead of at the first prompt.
+ * @module @worldapptechnologies/nulu-agent-tool-presentation
+ */
+import type { Context } from '@worldapptechnologies/cordis';
+import z from '@worldapptechnologies/schemastery';
+import type { ToolPresentationMode } from '@worldapptechnologies/nulu-tools';
+/** Cordis plugin name. */
+export declare const name = "tool-presentation";
+/**
+ * Required services. `ptcRuntime` is NOT listed: a `native` row must mount in
+ * a deployment that composes no runtime, and the mode-dependent wait is
+ * declared inside {@link apply} instead.
+ */
+export declare const inject: string[];
+/** Plugin config. */
+export interface Config {
+    /**
+     * The form this agent's model sees. `native` sends every visible schema,
+     * `ptc` sends only `run_code` plus a generated SDK, `both` sends both.
+     * Required rather than defaulted: the deployment default is what a preset
+     * without this row already gets, so an omitted value would mean the row was
+     * composed for nothing.
+     */
+    mode: ToolPresentationMode;
+}
+/** Runtime schema. */
+export declare const Config: z<Config>;
+/**
+ * Declare the tool presentation for every agent this composition covers.
+ * @param ctx - the mounting composition's scope context (a preset's standing scope).
+ * @param config - the selected presentation.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@worldapptechnologies/nulu-agent-tool-presentation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Agent-plane presentation selector: composes one agent's tools as PTC mode, native, or both",
+  "version": "1.6.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/worldapptechnologies/nulu-harness.git",
+    "directory": "packages/core/agent-tool-presentation"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@worldapptechnologies/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@worldapptechnologies/nulu-tools": "^1.6.4",
+    "@worldapptechnologies/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@worldapptechnologies/nulu-agent": "^1.6.4",
+    "@worldapptechnologies/nulu-ptc-runtime": "^1.6.4",
+    "@worldapptechnologies/nulu-scope": "^1.6.4",
+    "@worldapptechnologies/nulu-session": "^1.6.4",
+    "@worldapptechnologies/nulu-system-prompt": "^1.6.4",
+    "@worldapptechnologies/nulu-tools": "^1.6.4",
+    "@worldapptechnologies/cordis": "^4.0.2"
+  }
 }