@nodetool-ai/agents 0.7.0-rc.23 → 0.8.1

package/dist/capabilities/agents.specs.js

@@ -0,0 +1,243 @@
+/**
+ * The `agents` module's specs — data only, no implementation.
+ *
+ * Split out so a belt can be assembled synchronously: the registry's eager
+ * spec table imports this file, never `agents.ts`, so nothing the
+ * implementations pull in reaches the entry graph. `agents.ts` imports these
+ * back and attaches each to its implementation, so there is one spec object
+ * behind both halves.
+ */
+import { READ_ONLY_SEARCH_DESCRIPTION } from "../prompts/read-only-search-prompt.js";
+import { START_SUBTASK_DESCRIPTION, START_SUBTASK_SCHEMA, WAIT_SUBTASKS_DESCRIPTION, WAIT_SUBTASKS_SCHEMA } from "../prompts/background-subtask-prompt.js";
+import { isString } from "../utils/type-guards.js";
+export const RUN_SUBTASK_DESCRIPTION = [
+    "Spawn a focused subtask handled by a fresh agent loop. The subtask returns",
+    "the subagent's final assistant message as plain text.",
+    "",
+    "Call this when work warrants its own focused execution — research a",
+    "question end-to-end, perform a multi-step transformation, draft a",
+    "self-contained artifact. Emit multiple `run_subtask` calls in one turn",
+    "to run independent subtasks concurrently. Subtasks can themselves call",
+    "`run_subtask` up to the recursion depth limit.",
+    "",
+    "The subtask inherits the parent's full toolset. If you need a specific",
+    "output shape (e.g. JSON), say so inside `instructions` — do not request a",
+    "schema here. The subagent will write the result; you'll receive that",
+    "text verbatim and can quote or parse it."
+].join("\n");
+export const RUN_SUBTASK_SCHEMA = {
+    type: "object",
+    properties: {
+        description: {
+            type: "string",
+            description: "Short user-facing label for the subtask (3-7 words). Shown in the UI card."
+        },
+        prompt: {
+            type: "string",
+            description: 'Full task description for the subagent. Self-contained — the subagent does not see the parent\'s chat history. If you need a structured response, say so here (e.g. "reply as JSON with fields x, y, z").'
+        }
+    },
+    required: ["description", "prompt"],
+    additionalProperties: false
+};
+export const RUN_SEARCH_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "Precise description of what to locate. Self-contained — the search loop does not see the parent's chat history."
+        },
+        breadth: {
+            type: "string",
+            enum: ["medium", "very thorough"],
+            default: "medium",
+            description: 'How wide to sweep. "medium" (default) checks a few likely locations and obvious naming variants; "very thorough" systematically searches many locations and naming conventions.'
+        }
+    },
+    required: ["query"],
+    additionalProperties: false
+};
+export const runSubtaskSpec = {
+    name: "run_subtask",
+    description: RUN_SUBTASK_DESCRIPTION,
+    inputSchema: RUN_SUBTASK_SCHEMA,
+    // The child's events nest under the caller's card, which needs the caller's
+    // tool-call id. `SubAgentTool` declares the same thing on the class path.
+    needsToolCallId: true,
+    // The child loop's own tools are gated inside it, so spawning one has no
+    // side effect of its own.
+    category: "read",
+    userMessage: (params) => {
+        const desc = isString(params["description"])
+            ? params["description"].trim()
+            : "";
+        return desc ? `Running subtask: ${desc}` : "Running subtask";
+    }
+};
+export const runSearchSpec = {
+    name: "run_search",
+    // The description is the prompt module's own, so the capability and the
+    // class cannot drift apart.
+    description: READ_ONLY_SEARCH_DESCRIPTION,
+    inputSchema: RUN_SEARCH_SCHEMA,
+    // As for `run_subtask`: the search loop's events nest under the caller.
+    needsToolCallId: true,
+    // The child loop is filtered to a read-only allowlist and cannot recurse.
+    category: "read",
+    userMessage: (params) => {
+        const query = isString(params["query"]) ? params["query"].trim() : "";
+        return query ? `Searching: ${query}` : "Searching workspace";
+    }
+};
+export const startSubtaskSpec = {
+    name: "start_subtask",
+    description: START_SUBTASK_DESCRIPTION,
+    inputSchema: START_SUBTASK_SCHEMA,
+    // The child's events nest under the caller's card, which needs the caller's
+    // tool-call id — same as `run_subtask`.
+    needsToolCallId: true,
+    // Spawning has no side effect of its own; the child loop's tools are gated
+    // inside it. The registry bookkeeping is per-turn state, not a mutation.
+    category: "read",
+    userMessage: (params) => {
+        const desc = isString(params["description"]) ? params["description"].trim() : "";
+        return desc
+            ? `Starting background subtask: ${desc}`
+            : "Starting background subtask";
+    }
+};
+export const waitSubtasksSpec = {
+    name: "wait_subtasks",
+    description: WAIT_SUBTASKS_DESCRIPTION,
+    inputSchema: WAIT_SUBTASKS_SCHEMA,
+    category: "read"
+};
+export const CREATE_PLAN_DESCRIPTION = [
+    "Decompose an objective into an executable plan and show it to the user.",
+    "It PLANS ONLY — nothing in the plan runs, and no tool in it is called.",
+    "",
+    "Call this when the user asks for work that takes several steps and they",
+    "want to see the shape of it first: the planner returns a DAG of tasks,",
+    "each with its own steps and dependencies, and independent tasks are marked",
+    "as such so the user can see what would run concurrently.",
+    "",
+    "The plan streams into the conversation as it is built. Return your own",
+    "short summary afterwards — do not re-list every step the user can already",
+    "see."
+].join("\n");
+export const CREATE_PLAN_SCHEMA = {
+    type: "object",
+    properties: {
+        objective: {
+            type: "string",
+            description: "What the plan must achieve, self-contained. The planner does not see the chat history, so restate any constraint that matters (inputs, formats, limits)."
+        }
+    },
+    required: ["objective"],
+    additionalProperties: false
+};
+export const createPlanSpec = {
+    name: "create_plan",
+    description: CREATE_PLAN_DESCRIPTION,
+    inputSchema: CREATE_PLAN_SCHEMA,
+    // Planning reads the toolbelt's names to route steps and calls none of them,
+    // so it is read-only — which is also what keeps it callable in plan mode,
+    // where every other category is blocked.
+    category: "read",
+    userMessage: (params) => {
+        const objective = isString(params["objective"]) ? params["objective"].trim() : "";
+        return objective ? `Planning: ${objective.slice(0, 60)}` : "Planning";
+    }
+};
+export const EXECUTE_PLAN_DESCRIPTION = [
+    "Run a plan that already exists — the one `create_plan` produced and the",
+    "user has seen. It EXECUTES: every step runs with the tools it needs, and",
+    "independent tasks run concurrently.",
+    "",
+    "Pass the plan itself, not a reference to it: `title` plus the `tasks`",
+    "array exactly as `create_plan` returned it. Copy it verbatim unless the",
+    "user asked for a change (dropping a task, reordering, editing a step) — in",
+    "that case pass the amended plan, and it is the amended plan that runs.",
+    "",
+    "Tasks stream into the conversation as they finish. Each task's result is",
+    "also written to shared memory under `task:<task id>`, so read it back with",
+    "`read_shared` instead of re-running the work. The call returns how every",
+    "task settled; write the answer yourself from those results."
+].join("\n");
+const EXECUTE_PLAN_STEP_SCHEMA = {
+    type: "object",
+    properties: {
+        id: {
+            type: "string",
+            description: "Step id, unique across the whole plan."
+        },
+        instructions: {
+            type: "string",
+            description: "What this step does, self-contained."
+        },
+        depends_on: {
+            type: "array",
+            items: { type: "string" },
+            description: "Ids of steps in the same task that must finish first ([] for none)."
+        }
+    },
+    required: ["id", "instructions"]
+};
+export const EXECUTE_PLAN_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string", description: "The plan's title." },
+        tasks: {
+            type: "array",
+            description: "The plan's tasks, as `create_plan` returned them. Dependencies form a DAG; independent tasks run concurrently.",
+            items: {
+                type: "object",
+                properties: {
+                    id: {
+                        type: "string",
+                        description: "Task id, unique across the plan."
+                    },
+                    title: { type: "string", description: "Task title." },
+                    depends_on: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Ids of tasks that must finish first ([] for an independent task)."
+                    },
+                    steps: {
+                        type: "array",
+                        items: EXECUTE_PLAN_STEP_SCHEMA,
+                        description: "The task's steps, forming their own DAG."
+                    }
+                },
+                required: ["id", "title", "steps"]
+            }
+        }
+    },
+    required: ["title", "tasks"]
+};
+export const executePlanSpec = {
+    name: "execute_plan",
+    description: EXECUTE_PLAN_DESCRIPTION,
+    inputSchema: EXECUTE_PLAN_SCHEMA,
+    // Running a plan is the opposite of planning: every step acts, with whatever
+    // the belt offers. `external` is what blocks it in plan mode and asks once
+    // everywhere else — the confirmation for the whole plan. Each step's own
+    // tool calls stay gated inside the child loops.
+    category: "external",
+    userMessage: (params) => {
+        const title = isString(params["title"]) ? params["title"].trim() : "";
+        const tasks = Array.isArray(params["tasks"]) ? params["tasks"].length : 0;
+        const scope = tasks === 1 ? "1 task" : `${tasks} tasks`;
+        return title ? `Running plan: ${title} (${scope})` : `Running plan (${scope})`;
+    }
+};
+/** Every spec this module declares, in declaration order. */
+export const agentsSpecs = [
+    runSubtaskSpec,
+    runSearchSpec,
+    startSubtaskSpec,
+    waitSubtasksSpec,
+    createPlanSpec,
+    executePlanSpec
+];
+//# sourceMappingURL=agents.specs.js.map

package/dist/capabilities/agents.specs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.specs.js","sourceRoot":"","sources":["../../src/capabilities/agents.specs.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/analysis.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The `analysis` capability module — measuring media instead of generating it.
+ *
+ * `understand_video` asks a model what a clip is about; these answer what it
+ * *is*. Duration, sample rate, resolution and frame rate, but also where the
+ * energy sits over time, what frequencies are in it, where the silences and
+ * onsets are, how the picture moves, and where the cuts fall. A model cannot
+ * derive any of that from watching, and until now an agent could only get at
+ * it by shelling out to `ffprobe` and parsing text, or by authoring a workflow
+ * around `nodetool.audio.GetAudioInfo` — which reports four fields and needs
+ * the file to be a WAV to report duration at all.
+ *
+ * Decoding is Mediabunny's, so none of this needs ffmpeg on the host. That is
+ * the difference between a capability an agent can rely on and one that
+ * returns zeros when a managed runtime tool was never installed.
+ *
+ * The math is in `../analysis/`: `audio-dsp.ts` and `video-frames.ts` are pure
+ * functions over samples and pixels, tested against signals whose answers are
+ * known analytically. This file resolves the media, chooses the analysis
+ * parameters, and shapes the answer.
+ *
+ * Every answer is bounded. A model asking about a feature film should get a
+ * few hundred numbers describing it, not a hundred thousand — series are
+ * decimated to a point budget, decoding stops at a duration cap, and both say
+ * so in the result rather than silently returning part of the truth.
+ */
+import { type DecodedAudio } from "../analysis/media-decode.js";
+import type { CapabilityModule } from "./types.js";
+/** One RMS reading at an absolute source-time offset. */
+export interface AudioFramePoint {
+    readonly timeMs: number;
+    readonly rms: number;
+    /** Sample peak within the same window — carried for callers (this file's
+     * own tools) that need it alongside rms; not part of the documented
+     * contract, so a caller outside this module should treat it as optional. */
+    readonly peak: number;
+}
+/** What was asked for versus what the decode cap actually let through. */
+export interface AudioFrameTruncation {
+    readonly requested: readonly [number, number];
+    readonly analyzed: readonly [number, number];
+}
+export interface AudioFrameEnvelope {
+    /** The frame hop, in milliseconds. */
+    readonly frameMs: number;
+    /** Undecimated RMS series over the requested (and analyzed) interval. */
+    readonly frames: readonly AudioFramePoint[];
+    readonly onsetsMs: readonly number[];
+    /** Tempo estimate, present only when `detectTempo` was not turned off. */
+    readonly bpm?: number;
+    readonly tempoConfidence?: number;
+    /** Non-null exactly when the decode cap cut the window short. */
+    readonly truncated: AudioFrameTruncation | null;
+}
+export interface AnalyzeAudioFramesOptions {
+    /** Source-ms window start (default 0). */
+    readonly fromMs?: number;
+    /** Source-ms window end (default: the end of the track). */
+    readonly toMs?: number;
+    /** Frame hop in milliseconds (default 20). */
+    readonly frameMs?: number;
+    /** Seconds of source, from time 0, the decode cap allows (default 600). */
+    readonly maxSeconds?: number;
+    /** Standard deviations above the local mean an onset must clear (default 1.5). */
+    readonly onsetSensitivity?: number;
+    /** Estimate tempo from the onset novelty curve (default true). */
+    readonly detectTempo?: boolean;
+}
+/**
+ * The frame-level audio envelope: decode, window to `[fromMs, toMs]` of
+ * *source* time, and compute an undecimated per-frame RMS series plus onsets
+ * and an optional tempo — everything `analyze_audio` and
+ * `detect_audio_events` need before they decimate and shape their own
+ * response.
+ *
+ * `input` may be raw bytes (this function decodes them, respecting the decode
+ * cap) or an already-decoded track — a caller that has already paid for a
+ * decode (both capabilities in this module have) passes that instead of
+ * paying for a second one. Decoding, windowing and the cap are all decided
+ * here, once; a caller that needs the same series with different framing asks
+ * again rather than reimplementing the slice.
+ *
+ * Windowing is against the *source*, not the decoded prefix: a clip trimmed
+ * to `[30_000, 35_000]` on a two-minute file analyzes only that five-second
+ * span, not the two minutes leading up to it (mod what the decode cap makes
+ * available — see `truncated`). The cap is applied the same way
+ * `max_seconds` always was: at most `maxSeconds` of source, measured from
+ * time 0, is ever decoded, so a window whose end falls past the cap comes
+ * back short and says so, rather than only logging it.
+ */
+export declare function analyzeAudioFrames(input: Uint8Array | DecodedAudio, options?: AnalyzeAudioFramesOptions): Promise<AudioFrameEnvelope>;
+export declare const module: CapabilityModule;
+//# sourceMappingURL=analysis.d.ts.map

package/dist/capabilities/analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../../src/capabilities/analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAuBH,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAC;AA8BrC,OAAO,KAAK,EAEV,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AA8HpB,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;gFAE4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,yBAAyB;IACxC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AA8BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,UAAU,GAAG,YAAY,EAChC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,kBAAkB,CAAC,CAkF7B;AA+tBD,eAAO,MAAM,MAAM,EAAE,gBASpB,CAAC"}