@nodetool-ai/agents 0.8.1 → 0.8.3

package/dist/capabilities/agent-activity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What an agent loop inside a capability reports while it runs.
+ *
+ * A capability that drives `provider.generateLoop` answers with one value when
+ * the loop ends. A mini app waiting on that value showed a spinner for minutes.
+ * The reporter puts the loop's text and tool calls on the run's context as the
+ * standard processing messages (`chunk`, `tool_call_update`,
+ * `tool_result_update`), so every host that listens to the context shows the
+ * work while it happens: the script run route streams them, a workflow run
+ * forwards them.
+ */
+import type { ProcessingContext, ProviderStreamItem } from "@nodetool-ai/runtime";
+export interface AgentActivityReporter {
+    /** Report one provider stream item: a text chunk or a tool call announcement. */
+    event(item: ProviderStreamItem): void;
+    /** Report how one tool call settled. */
+    toolResult(call: {
+        id: string;
+        name: string;
+    }, result: unknown, isError: boolean): void;
+}
+/**
+ * A reporter that emits on `context`. `nodeId` names the loop in each message,
+ * so a host can tell two loops of one run apart.
+ */
+export declare function agentActivityReporter(context: ProcessingContext, nodeId: string): AgentActivityReporter;
+//# sourceMappingURL=agent-activity.d.ts.map

package/dist/capabilities/agent-activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-activity.d.ts","sourceRoot":"","sources":["../../src/capabilities/agent-activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAUlF,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtC,wCAAwC;IACxC,UAAU,CACR,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAClC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,GACf,IAAI,CAAC;CACT;AAkBD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,GACb,qBAAqB,CA4DvB"}

package/dist/capabilities/agent-activity.js

@@ -0,0 +1,103 @@
+/**
+ * What an agent loop inside a capability reports while it runs.
+ *
+ * A capability that drives `provider.generateLoop` answers with one value when
+ * the loop ends. A mini app waiting on that value showed a spinner for minutes.
+ * The reporter puts the loop's text and tool calls on the run's context as the
+ * standard processing messages (`chunk`, `tool_call_update`,
+ * `tool_result_update`), so every host that listens to the context shows the
+ * work while it happens: the script run route streams them, a workflow run
+ * forwards them.
+ */
+import { randomUUID } from "node:crypto";
+import { trace } from "@opentelemetry/api";
+import { getRunTraceScope, withRunTrace, recordTraceEvent, getProviderStreamTrace, stringifyTraceContent } from "@nodetool-ai/runtime";
+import { isChunk, isToolCall } from "@nodetool-ai/runtime";
+import { capabilitySpec } from "./metadata.js";
+import { isString } from "../utils/type-guards.js";
+/** The longest tool result summary one message carries. */
+const RESULT_SUMMARY_CHARS = 400;
+const summarize = (result) => {
+    const text = isString(result) ? result : JSON.stringify(result) ?? "";
+    return text.length > RESULT_SUMMARY_CHARS
+        ? `${text.slice(0, RESULT_SUMMARY_CHARS)}…`
+        : text;
+};
+/** The label a person reads for one tool call: the capability's own message, or its name. */
+const callLabel = (name, args) => {
+    try {
+        return capabilitySpec(name)?.userMessage?.(args) ?? name;
+    }
+    catch {
+        return name;
+    }
+};
+/**
+ * A reporter that emits on `context`. `nodeId` names the loop in each message,
+ * so a host can tell two loops of one run apart.
+ */
+export function agentActivityReporter(context, nodeId) {
+    const createdScope = context.runTraceContext ?? getRunTraceScope();
+    const createdSpan = trace.getActiveSpan();
+    const activityId = randomUUID();
+    return {
+        event(item) {
+            const attribution = getProviderStreamTrace(item);
+            const scope = attribution?.scope ?? createdScope;
+            if (scope) {
+                const attributes = {
+                    "node.id": nodeId, "agent.activity_id": activityId, "log.source": "agent", "log.level": "info"
+                };
+                if (isChunk(item) && !item.thinking && item.content_type !== "audio") {
+                    attributes["log.message"] = item.content;
+                }
+                if (isToolCall(item)) {
+                    attributes["tool.name"] = item.name;
+                    attributes["tool.call_id"] = item.id;
+                }
+                withRunTrace(scope, () => recordTraceEvent("agent.activity", attributes, attribution?.span ?? createdSpan));
+            }
+            if (isToolCall(item)) {
+                context.emit({
+                    type: "tool_call_update",
+                    node_id: nodeId,
+                    tool_call_id: item.id,
+                    name: item.name,
+                    args: item.args ?? {},
+                    message: callLabel(item.name, item.args ?? {})
+                });
+                return;
+            }
+            if (isChunk(item) && !item.thinking && item.content_type !== "audio") {
+                if (item.content.length === 0)
+                    return;
+                context.emit({
+                    type: "chunk",
+                    node_id: nodeId,
+                    content: item.content,
+                    content_type: "text",
+                    done: false
+                });
+            }
+        },
+        toolResult(call, result, isError) {
+            const scope = context.runTraceContext ?? getRunTraceScope() ?? createdScope;
+            if (scope) {
+                withRunTrace(scope, () => recordTraceEvent("tool.result", {
+                    "node.id": nodeId, "agent.activity_id": activityId, "tool.name": call.name, "tool.call_id": call.id,
+                    "log.source": "agent", "log.level": isError ? "error" : "info",
+                    "tool.result": stringifyTraceContent(result).slice(0, RESULT_SUMMARY_CHARS)
+                }, trace.getActiveSpan() ?? createdSpan));
+            }
+            context.emit({
+                type: "tool_result_update",
+                node_id: nodeId,
+                tool_call_id: call.id,
+                name: call.name,
+                result: { summary: summarize(result) },
+                is_error: isError
+            });
+        }
+    };
+}
+//# sourceMappingURL=agent-activity.js.map

package/dist/capabilities/agent-activity.js.map

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

package/dist/capabilities/agentic-storyboard-finish.d.ts

@@ -0,0 +1,67 @@
+import type { StoryboardDocument, TimelineSequence } from "@nodetool-ai/models";
+import { type BaseProvider, type TurnBudget, type RunBudget } from "@nodetool-ai/runtime";
+import { type FinishStoryboardInput, type FinishedStoryboardDocument } from "@nodetool-ai/timeline";
+import type { CapabilityRun } from "./types.js";
+export interface FinishedCutRuntime {
+    readonly provider: BaseProvider;
+    readonly model: string;
+    readonly budget?: TurnBudget | RunBudget;
+}
+/**
+ * What one agentic pass authors. "layout" composes the static frame of every
+ * shot and may generate decoration; "finish" authors the motion.
+ */
+export interface FinishedCutOptions {
+    readonly phase?: "layout" | "finish";
+    /** The image model a layout pass generates backgrounds and decoration with. */
+    readonly imageModel?: {
+        readonly provider: string;
+        readonly id: string;
+    };
+}
+/** A generated image the layout pass added to a shot as a decorative element. */
+export interface StoryboardDecoration {
+    readonly shotId: string;
+    readonly element: {
+        id: string;
+        kind: "asset";
+        role: "decorative";
+        asset_id: string;
+        direction: string;
+        origin: "layout_agent";
+    };
+}
+export interface FinishedCutReview {
+    readonly round: number;
+    readonly passed: boolean;
+    readonly findings: readonly string[];
+    readonly summary: string;
+    readonly frameReviews?: readonly {
+        readonly timeMs: number;
+        readonly passed: boolean;
+        readonly findings: readonly string[];
+    }[];
+    readonly referenceFrames: readonly {
+        shotId: string;
+        fingerprint: string;
+        sha256: string;
+        timeMs: number;
+    }[];
+    readonly frames: readonly {
+        timeMs: number;
+        sha256: string;
+        width: number;
+        height: number;
+    }[];
+}
+/** A child authors only an in-memory draft. Existing CAS is the sole write. */
+export declare function finishStoryboardAgentically(run: CapabilityRun, input: FinishStoryboardInput, board: StoryboardDocument, sequence: TimelineSequence, scaffold: FinishedStoryboardDocument, runtime: FinishedCutRuntime, options?: FinishedCutOptions): Promise<{
+    document: FinishedStoryboardDocument;
+    reviews: FinishedCutReview[];
+    costUsd: number;
+    decorations: StoryboardDecoration[];
+    /** Layout only: every hard check passed, the visual review still has findings. */
+    needsReview?: boolean;
+    findings?: string[];
+}>;
+//# sourceMappingURL=agentic-storyboard-finish.d.ts.map

package/dist/capabilities/agentic-storyboard-finish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-storyboard-finish.d.ts","sourceRoot":"","sources":["../../src/capabilities/agentic-storyboard-finish.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAOL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EAYL,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAEhC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAmBhD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,OAAO,CAAC;QACd,IAAI,EAAE,YAAY,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,cAAc,CAAC;KACxB,CAAC;CACH;AAwBD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS;QAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;KACtC,EAAE,CAAC;IACJ,QAAQ,CAAC,eAAe,EAAE,SAAS;QACjC,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,EAAE,CAAC;IACJ,QAAQ,CAAC,MAAM,EAAE,SAAS;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,EAAE,CAAC;CACL;AAiTD,+EAA+E;AAC/E,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,qBAAqB,EAC5B,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,0BAA0B,EACpC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC;IACT,QAAQ,EAAE,0BAA0B,CAAC;IACrC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,kFAAkF;IAClF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC,CAmuCD"}