@nodetool-ai/agents 0.8.4-a24.2 → 0.8.4

package/dist/_skills/nodetool-custom-node-developer/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: nodetool-custom-node-developer
+description: "Create or update TypeScript NodeTool nodes and node packs in a NodeTool checkout or an npm package: decorated properties, process methods, streaming, registration. Needs a shell. For custom logic inside the product, use nodetool-js-scripting."
+---
+
+You are a NodeTool node developer. You create TypeScript nodes that extend `BaseNode` from `@nodetool-ai/node-sdk`.
+
+This is shell work: writing TypeScript, building and installing an npm pack,
+and restarting the server. The in-product agent cannot do it. Inside the
+product, custom logic is a Code node or a saved JS script in the QuickJS
+sandbox (`nodetool-js-scripting`).
+
+# Package Layout
+
+```
+my-nodes/
+├── package.json          # depends on @nodetool-ai/node-sdk
+├── tsconfig.json         # extends ../../tsconfig.base.json
+├── src/
+│   ├── index.ts          # exports registration function + ALL_NODES array
+│   └── nodes/
+│       ├── category-a.ts # node classes
+│       └── category-b.ts
+└── tests/
+    └── nodes.test.ts
+```
+
+# Node Template
+
+```typescript
+import { BaseNode, prop } from "@nodetool-ai/node-sdk";
+
+export class MyNode extends BaseNode {
+  // REQUIRED static fields
+  static readonly nodeType = "mypack.category.NodeName"; // namespace.category.Name
+  static readonly title = "Human-Readable Title";
+  static readonly description = "Brief description.\n    search, keywords, here";
+  static readonly metadataOutputTypes = { output: "str" }; // declare all outputs
+
+  // Inputs via @prop decorator
+  @prop({ type: "str", default: "", title: "Input Text" })
+  declare input_text: any;
+
+  @prop({ type: "int", default: 10, min: 1, max: 100, title: "Count" })
+  declare count: any;
+
+  // Process method — MUST return all keys from metadataOutputTypes
+  async process(): Promise<Record<string, unknown>> {
+    const text = String(this.input_text ?? "");
+    const count = Number(this.count ?? 10);
+    return { output: text.repeat(count) };
+  }
+}
+```
+
+# Input Resolution Pattern
+
+Property values **and** connected input values are assigned to instance fields
+*before* `process()` is called, so always read inputs from `this`:
+```typescript
+const value = this.field ?? defaultValue;
+```
+- `this.field` — resolved value (connection value if connected, else the
+  user-set property, else the `@prop` default)
+- `defaultValue` — extra in-code fallback for `null`/`undefined`
+
+Do **not** declare a `process(inputs: Record<string, unknown>)` parameter — the
+runtime calls `process(context?: ProcessingContext)`, so an `inputs` parameter
+typed that way fails strict type-checking.
+
+# @prop Decorator Options
+
+| Option | Type | Notes |
+|--------|------|-------|
+| `type` | string | **Required**: `"int"`, `"float"`, `"str"`, `"bool"`, `"list[any]"`, `"image"`, `"audio"`, `"video"`, `"document"`, `"dataframe"`, `"enum"`, `"any"` |
+| `default` | unknown | Default value |
+| `title` | string | Display name in UI |
+| `description` | string | Tooltip text |
+| `min` / `max` | number | Numeric bounds |
+| `required` | boolean | Validation flag |
+| `values` | (string\|number)[] | Enum options |
+
+# Patterns
+
+## Multi-Output Node
+```typescript
+static readonly metadataOutputTypes = { text: "str", confidence: "float" };
+
+async process(): Promise<Record<string, unknown>> {
+  return { text: "result", confidence: 0.95 }; // ALL keys must be returned
+}
+```
+
+## Streaming Output (genProcess)
+
+Streaming is structural. Overriding `genProcess` makes the node emit many
+values, and `outputCorrelation` says how each output relates to the run:
+`iteration` for one value per yield, `single` for one final value. There is no
+streaming flag.
+
+```typescript
+import type { OutputCorrelation } from "@nodetool-ai/protocol";
+
+static readonly metadataOutputTypes = { output: "any", index: "int" };
+static readonly outputCorrelation: Record<string, OutputCorrelation> = {
+  output: { kind: "iteration", source: "__execution__", group: "items" },
+  index: { kind: "iteration", source: "__execution__", group: "items" }
+};
+
+@prop({ type: "list[any]", default: [], title: "Input List" })
+declare input_list: unknown[];
+
+async process(): Promise<Record<string, unknown>> {
+  return {};
+}
+
+async *genProcess(): AsyncGenerator<Record<string, unknown>> {
+  const items = this.input_list ?? [];
+  for (let i = 0; i < items.length; i++) {
+    yield { output: items[i], index: i };
+  }
+}
+```
+
+A `chunk` output must come from `genProcess` with an `iteration` correlation,
+or it stays empty.
+
+## Streaming Input (collector)
+
+A node that consumes a stream sets `isStreamingInput` and implements `run()`,
+which reads the input stream and emits when it ends. `process()` alone fires
+once with buffered inputs and collects nothing across a stream.
+
+```typescript
+import type { StreamingInputs, StreamingOutputs } from "@nodetool-ai/node-sdk";
+import type { InputMode, OutputCorrelation } from "@nodetool-ai/protocol";
+
+static readonly metadataOutputTypes = { output: "list[any]" };
+static readonly isStreamingInput = true;
+static readonly inputMode: InputMode = "stream";
+static readonly outputCorrelation: Record<string, OutputCorrelation> = {
+  output: { kind: "aggregate", source: "input_item", collapse: "innermost" }
+};
+
+@prop({ type: "any", default: [], title: "Input Item" })
+declare input_item: unknown;
+
+async process(): Promise<Record<string, unknown>> {
+  return { output: [] };
+}
+
+async run(inputs: StreamingInputs, outputs: StreamingOutputs): Promise<void> {
+  const items: unknown[] = [];
+  for await (const item of inputs.stream("input_item")) {
+    items.push(item);
+  }
+  await outputs.emit("output", items);
+}
+```
+
+## Enum Input
+```typescript
+@prop({ type: "enum", values: ["low", "medium", "high"], default: "medium", title: "Quality" })
+declare quality: any;
+```
+
+## Secrets / API Keys
+```typescript
+static readonly requiredSettings = ["MY_API_KEY"];
+
+async process(): Promise<Record<string, unknown>> {
+  // Resolved secrets are available via the `_secrets` getter.
+  const apiKey = this._secrets.MY_API_KEY || process.env.MY_API_KEY;
+  if (!apiKey) throw new Error("MY_API_KEY not configured");
+  // use apiKey...
+}
+```
+
+## Media Refs (Image/Audio/Video)
+
+A ref may carry inline `data`, or only a `uri` (`asset://`, `file://`, storage,
+`http`). Read bytes with `loadMediaRefBytes`, which resolves every form. Return
+a ref with its `type` discriminator and raw bytes or raw base64 in `data`,
+never a `data:` URI.
+
+```typescript
+import { loadMediaRefBytes, type ProcessingContext } from "@nodetool-ai/runtime";
+
+@prop({ type: "image", title: "Input Image" })
+declare image: { uri?: string; data?: string | Uint8Array; asset_id?: string } | undefined;
+
+async process(context?: ProcessingContext): Promise<Record<string, unknown>> {
+  if (!this.image) throw new Error("No image provided");
+  const bytes = await loadMediaRefBytes(this.image, context);
+  if (!bytes) throw new Error("Image has no readable bytes");
+  const result: Uint8Array = await processImage(bytes);
+  return { output: { type: "image", data: result, content_type: "image/png" } };
+}
+```
+
+## Lifecycle Hooks
+```typescript
+async initialize(): Promise<void> { }   // once at start of run
+async preProcess(): Promise<void> { }   // before each process() call
+async finalize(): Promise<void> { }     // after all processing
+```
+
+# Optional Static Properties
+
+```typescript
+static readonly supportsDynamicInputs = true;   // user can add input slots
+static readonly supportsDynamicOutputs = true;  // user can add output slots
+static readonly inputFields = ["prompt"];       // shown as handles on the node body
+static readonly inlineFields = ["model"];       // edited inline on the node
+```
+
+Props in neither list appear only in the Inspector.
+
+# Scaffold a Pack
+
+The fastest start is the scaffolder, which generates a self-contained pack
+(package.json with the `nodetool` manifest field, tsconfig, an example node, a
+test, and a README):
+
+```bash
+npm run create:pack -- @myorg/my-nodes        # in the nodetool repo
+# or directly: node scripts/create-pack.mjs @myorg/my-nodes ./my-nodes
+```
+
+# Registration
+
+```typescript
+// src/index.ts
+import type { NodeClass, NodeRegistry } from "@nodetool-ai/node-sdk";
+import { MyNode, OtherNode } from "./nodes/my-nodes.js";
+
+export const ALL_NODES: readonly NodeClass[] = [MyNode, OtherNode];
+
+export function register(registry: NodeRegistry): void {
+  for (const nodeClass of ALL_NODES) {
+    registry.register(nodeClass);
+  }
+}
+```
+
+The server auto-loads packs — no need to edit its source. Mark the package as a
+pack with a `nodetool` field in `package.json`, naming the export above:
+
+```jsonc
+{
+  "name": "@myorg/my-nodes",
+  "main": "dist/index.js",
+  "nodetool": { "apiVersion": 1, "register": "register" }
+}
+```
+
+On startup the server scans installed dependencies, imports any package with a
+`nodetool` field, and calls the named export with the registry. Install the
+built pack where the server can resolve it (`npm install <pack>`, or `npm link`
+for local dev) and restart. The export may be sync or `async`.
+
+**Trust model.** Custom nodes run in-process as the server user (full
+filesystem/network/secret access, no sandbox), so loading is gated. In
+development unlisted packs load automatically. A production server
+(`NODETOOL_ENV=production`) and the desktop app
+(`NODETOOL_PACKS_REQUIRE_ALLOWLIST=1`) load only packs on the allowlist
+(`NODETOOL_PACKS_ALLOWLIST` or `~/.config/nodetool/packs.json`). An unlisted
+pack is skipped, so on Desktop add it to the allowlist before restarting. Packs also
+cannot register under reserved namespaces (`nodetool.`, `lib.`, provider names)
+or shadow an existing node type. Only install packs you trust.
+
+# Testing
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { MyNode } from "../src/nodes/my-nodes.js";
+
+describe("MyNode", () => {
+  it("processes input", async () => {
+    // Constructor assigns properties to instance fields.
+    const node = new MyNode({ input_text: "hello", count: 3 });
+    const result = await node.process();
+    expect(result.output).toBe("hellohellohello");
+  });
+});
+```
+
+# Common Pitfalls
+
+- **Forgetting output keys**: Every key in `metadataOutputTypes` must appear in the return object
+- **Wrong input access**: Read inputs from `this.field` (assigned before `process()`); do not add an `inputs` parameter to `process()`
+- **nodeType format**: Must be `namespace.category.Name` with dots as separators
+- **Mutable state without initialize()**: If using instance fields, reset them in `initialize()`
+- **Missing secrets declaration**: Add to `requiredSettings` array for proper UI prompting

package/dist/_skills/nodetool-deployment/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: nodetool-deployment
+description: "Self-host a NodeTool server with Docker Compose or nodetool deploy, rent a Runpod or Vast GPU worker with nodetool worker, or configure server auth. Everything here runs in the user's shell: the in-product agent explains the steps and does not run them."
+---
+
+You help users run NodeTool somewhere other than their desktop. Every command
+below runs in the user's shell. The in-product agent has no shell and no
+deployment tools, so it explains the steps and leaves running them to the user.
+
+# Which one
+
+| Need | Use |
+|------|-----|
+| A long-lived server that people connect in to | Docker: `docker-compose.yml` from the repository, or `nodetool deploy` for a remote host over SSH |
+| A rented GPU that the user's NodeTool connects out to, billed by the minute | `nodetool worker` on Runpod or Vast |
+
+`nodetool deploy` supports one target type, `docker`. There is no SSH-service,
+Runpod-endpoint or Cloud Run deploy type. Runpod and Vast are `nodetool worker`.
+
+# Server authentication
+
+The server picks its auth mode from `SUPABASE_URL` and `SUPABASE_KEY` alone. It
+reads neither `AUTH_PROVIDER` nor `NODETOOL_SERVER_MODE`.
+
+| Mode | Enabled by | Accepted credentials |
+|------|------------|----------------------|
+| Local | Default, with the Supabase variables unset | Loopback connections run as user `"1"` with no token. `NODETOOL_TRUST_LOCALHOST=false` turns that off. Sources in `NODETOOL_TRUST_LOCAL_NETWORKS` (comma-separated CIDRs) also run as user `"1"` with no token. A bearer equal to `SERVER_AUTH_TOKEN` runs as user `"1"`. A token minted by `nodetool deploy users-add` runs as that API user. Anything else gets `401`. |
+| Supabase | `SUPABASE_URL` and `SUPABASE_KEY` both set | Every non-public request needs a valid Supabase JWT. `SERVER_AUTH_TOKEN`, `NODETOOL_TRUST_LOCAL_NETWORKS` and API-user tokens are ignored. Loopback is trusted only with `NODETOOL_TRUST_LOCALHOST=true`. |
+
+In both modes, an access token (`ntk_…`) created in **Settings → MCP → Connect
+an agent remotely** authenticates as the person who created it. Send any token
+as `Authorization: Bearer <token>`. A WebSocket client that cannot set headers
+passes `?api_key=<token>` on the `/ws` URL.
+
+Docker NATs a published-port connection, so it arrives from the bridge gateway,
+not loopback. In Local mode that means `401` until the source range is in
+`NODETOOL_TRUST_LOCAL_NETWORKS` or the client sends a token. Every listed range
+runs as user `"1"` with no password, so list only networks you control. A
+server that other people reach over the internet needs Supabase mode, with
+`SUPABASE_ANON_KEY` set too so the web login screen works.
+
+# Docker Compose (single host)
+
+The repository's `docker-compose.yml` is the reference self-host setup.
+
+```bash
+cp .env.example .env          # fill in the provider keys you use
+docker compose up -d          # serves http://localhost:17777
+```
+
+- It runs in Local mode and trusts Docker's bridge ranges
+  (`172.16.0.0/12,192.168.65.0/24`) by default. Safe on a laptop, LAN or VPN.
+  Before exposing the port publicly, set `SUPABASE_URL`, `SUPABASE_KEY` and
+  `SUPABASE_ANON_KEY` in `.env`.
+- All state (database, assets, vector store, model cache, generated secret
+  key) lives on the `nodetool-data` volume at `/workspace`.
+- `NODETOOL_PORT` changes the host port. `NODETOOL_VERSION` pins an image tag.
+
+# `nodetool deploy` (remote Docker host)
+
+`deployment.yaml` lives in the user config directory, not the working directory.
+Open it with `nodetool deploy edit` rather than guessing the path.
+
+```bash
+nodetool deploy init                         # create deployment.yaml
+nodetool deploy add my-server --type docker  # describe one target
+nodetool deploy plan my-server               # review before touching the host
+nodetool deploy apply my-server              # --dry-run to print the steps only
+nodetool deploy status my-server
+nodetool deploy logs my-server --follow --tail 200
+nodetool deploy list                         # live state of every target
+nodetool deploy show my-server               # config only, no remote call
+nodetool deploy destroy my-server            # --force skips the confirmation
+```
+
+```yaml
+deployments:
+  my-server:
+    type: docker
+    host: 192.168.1.10        # localhost skips SSH and uses the local Docker
+    ssh:
+      user: ubuntu
+      key_path: ~/.ssh/id_ed25519
+    image:
+      name: ghcr.io/nodetool-ai/nodetool
+      tag: latest
+    container:
+      name: nodetool-server
+      port: 8000              # host port
+      gpu: "0"                # GPU device ids, or omit
+      environment:            # extra env, e.g. SUPABASE_URL, provider keys
+        OPENAI_API_KEY: "..."
+    paths:
+      workspace: ~/nodetool_data/workspace
+      hf_cache: ~/nodetool_data/hf-cache
+```
+
+The CLI writes a generated `server_auth_token` and a
+`container.environment.SECRETS_MASTER_KEY` into `deployment.yaml` for any
+target that lacks them. `apply` starts the container with the token as
+`SERVER_AUTH_TOKEN`, so in Local mode a client authenticates with
+`Authorization: Bearer <server_auth_token>`. The container keeps its database,
+assets, vector store and API users under `/workspace`.
+
+## Remote workflows and API users
+
+These verbs send an admin bearer token: `--token <token>`, else
+`NODETOOL_ADMIN_TOKEN`, else an interactive prompt.
+
+```bash
+nodetool deploy workflows sync my-server <workflow_id>   # assets and models must already be there
+nodetool deploy workflows list my-server
+nodetool deploy workflows run my-server <workflow_id> -p prompt="a red fox"
+nodetool deploy workflows delete my-server <workflow_id>
+
+nodetool deploy users-add my-server alice --role admin   # prints alice's token
+nodetool deploy users-list my-server
+nodetool deploy users-reset-token my-server alice
+nodetool deploy users-remove my-server alice
+```
+
+API-user tokens work in Local mode only (§ Server authentication).
+
+# `nodetool worker` (rented GPU)
+
+A worker is a Runpod or Vast instance that the user's NodeTool attaches to for
+GPU nodes. It bills by the minute until stopped. Confirm the GPU type and the
+expected hours with the user before creating one, and always set an auto-stop
+guard.
+
+Store the provider key first: `nodetool secrets store RUNPOD_API_KEY` (or
+`VAST_API_KEY`).
+
+```bash
+nodetool worker profile add hf-a40 --target runpod \
+  --image ghcr.io/nodetool-ai/nodetool-worker:latest \
+  --gpu "NVIDIA A40" --idle-timeout 15 --max-lifetime 240
+nodetool worker create --profile hf-a40 --attach
+
+nodetool worker list
+nodetool worker status <instance-id>
+nodetool worker stop <instance-id>     # or --all
+```
+
+- `--idle-timeout <minutes>` stops an idle worker. `--max-lifetime <minutes>` is
+  a hard limit. Set both, since a forgotten worker keeps billing.
+- `--disk <gb>` sizes the persistent volume that holds the model cache
+  (default 100). `--ssh-key <path.pub>` opens SSH for debugging.
+- `--attach` prints `NODETOOL_WORKER_URL`. For another shell, export
+  `NODETOOL_WORKER_TOKEN=$(nodetool worker token <instance-id>)`.
+- `nodetool worker models download --repo-id <owner/name>` pulls weights onto
+  the attached worker before a run, so the first run does not pay for the
+  download on GPU time. `models list` and `models delete` manage the cache.
+
+# Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `SUPABASE_URL`, `SUPABASE_KEY` | Turn on Supabase mode. `SUPABASE_KEY` is the service-role key |
+| `SUPABASE_ANON_KEY` | Public key the login screen uses. Without it no user can sign in |
+| `SECRETS_MASTER_KEY` | Encrypts stored secrets. Set it explicitly (`openssl rand -base64 32`). A lost key makes every stored secret unreadable |
+| `NODETOOL_TRUST_LOCAL_NETWORKS` | Local mode only: CIDRs that run as user `"1"` with no token |
+| `NODETOOL_TRUST_LOCALHOST` | Overrides whether loopback bypasses auth |
+| `NODETOOL_ENABLE_MCP=1` | Serves `/mcp` on a production server |
+| `NODETOOL_STORAGE_BACKEND` | `file` (default), `s3` or `supabase`, with `ASSET_BUCKET` and `TEMP_BUCKET` |
+| `DB_PATH`, `ASSET_FOLDER`, `VECTORSTORE_DB_PATH`, `HF_HOME` | Keep these on a persistent volume |
+| `HOST`, `PORT` | Bind address. The image binds `0.0.0.0` |
+| `NODETOOL_LOG_LEVEL` | Log level, default `info` |
+| Provider keys | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `HF_TOKEN`, `FAL_API_KEY` as needed |
+
+The image already sets `NODETOOL_ENV=production`. Production mode turns off the
+Python bridge, the file browser and `/mcp` (unless enabled), and loads only node
+packs on the allowlist. Do not set it on a desktop or development install.
+
+# Running the server directly
+
+```bash
+nodetool serve                          # 127.0.0.1:7777
+nodetool serve --host 0.0.0.0 --port 8080
+```
+
+Health checks: `GET /health` (liveness, no auth) and `GET /ready`.
+
+# Common pitfalls
+
+- **UI loads but every API call returns `401` in Docker**: the published port
+  arrives from the bridge gateway. Add the bridge range to
+  `NODETOOL_TRUST_LOCAL_NETWORKS` or send a token.
+- **`SERVER_AUTH_TOKEN` or `NODETOOL_TRUST_LOCAL_NETWORKS` stops working after
+  adding Supabase**: Supabase mode ignores both. Clients must sign in or use an
+  access token.
+- **Anon key in `SUPABASE_KEY`**: the server needs the service-role key there.
+- **No persistent volume**: the database, assets and secrets key vanish when the
+  container is recreated.
+- **Worker left running**: `nodetool worker list`, then `nodetool worker stop --all`.