@uipath/maestro-builder-sdk 6.41.2 → 6.43.0

package/dist/core/agent-sidecar.js

@@ -0,0 +1,409 @@
+/**
+ * The `agent.json` sidecar every agent step writes beside the `.flow` — the
+ * inline, conversational and voice agents' writers, the input plan they share
+ * with the node's `agentInputVariables`, and the prompt tokens the designer
+ * renders — and the reader decompile recovers an agent's configuration with.
+ * Moved from serialize.ts and decompile.ts so the agent node types, the
+ * serializer and the decompiler share one format.
+ */
+import { flatNameOf } from './expr.js';
+/**
+ * Classify a RENDERED input value (as serialize renders it).
+ *
+ * A rendered value is an expression exactly when it starts with `=js:` — the
+ * same test the rest of the serializer applies, so a literal string that
+ * happens to begin with `=js:` is treated as one everywhere.
+ */
+function classifyAgentInput(rendered) {
+    if (typeof rendered !== 'string' || !rendered.startsWith('=js:')) {
+        return { kind: 'literal', text: String(rendered) };
+    }
+    const flatName = flatNameOf(rendered);
+    return flatName === undefined
+        ? { kind: 'expression', binding: rendered }
+        : { kind: 'ref', flatName, binding: rendered };
+}
+/**
+ * The platform-facing plan for one inline agent's declared inputs.
+ *
+ * Built once and used by all three agent-facing sites (the node's
+ * `agentInputVariables`, the sidecar's `inputSchema`, and both prompts), so they
+ * cannot drift apart.
+ *
+ * `refs` is DEDUPED BY FLAT NAME and keeps author order. Two logical names bound
+ * to the same reference are one JobArgument on the platform (v1 dedupes on a
+ * seen-set, `:490-522`), so emitting two descriptors would claim an argument that
+ * will not exist.
+ */
+export function agentInputPlan(inputs, render) {
+    const byName = new Map();
+    const refs = [];
+    const seen = new Set();
+    for (const [name, val] of Object.entries(inputs)) {
+        const b = classifyAgentInput(render(val));
+        byName.set(name, b);
+        if (b.kind === 'ref' && !seen.has(b.flatName)) {
+            seen.add(b.flatName);
+            refs.push({ flatName: b.flatName, binding: b.binding });
+        }
+    }
+    return { byName, refs };
+}
+/**
+ * Render an agent prompt for the SIDECAR — the author's placeholders rewritten to
+ * the names the runtime will actually have.
+ *
+ * The three cases mirror {@link AgentInputBinding}; the fourth (a placeholder
+ * naming nothing `inputs` declares) is left ALONE rather than deleted, exactly as
+ * the node's renderer leaves it, so it reaches the model as visible literal text
+ * and `check`'s `INLINE_AGENT_UNDECLARED_PLACEHOLDER` can name it.
+ *
+ * `contentTokens` is NOT rewritten separately — {@link promptTokens} runs over the
+ * rewritten string, so the designer's chips and the runtime's template can't
+ * disagree about a name.
+ */
+function renderAgentSidecarPrompt(template, plan) {
+    return template.replace(INPUT_PLACEHOLDER, (whole, name) => {
+        const b = plan.get(name);
+        if (!b)
+            return whole;
+        if (b.kind === 'literal')
+            return b.text;
+        if (b.kind === 'ref')
+            return `{{input.${b.flatName}}}`;
+        return whole;
+    });
+}
+/**
+ * The `version` every `agent.json` sidecar declares — the agent tool's
+ * `AGENT_SCHEMA_VERSION` (uipath-cli `packages/agent-tool/src/templates/agent-template.ts`).
+ *
+ * It is not a free label. The agents backend reads an on-file `outputSchema`
+ * only at `version >= 1.2.0` (UiPath/Agents#5705), and since uipath-cli#3753
+ * `uip agent init` writes `1.2.0` and `uip agent validate` refuses anything else
+ * with `AgentValidationOutdated` ("Agent version "1.1.0" is outdated; latest is
+ * "1.2.0""). The bump is a version change only: `uip agent refresh` rewrites
+ * the field and nothing else. All three writers below share this one constant
+ * so they cannot fall behind separately (flow-builder-sdk#962).
+ */
+const AGENT_DEFINITION_VERSION = '1.2.0';
+/**
+ * The `agent.json` sidecar for a text CONVERSATIONAL agent.
+ *
+ * The inline agent's shape minus the argument plumbing: the turn arrives as the
+ * conversation transcript, so there is no `inputSchema` keyed by flat names and
+ * no `outputSchema` (the definition declares
+ * `uipath__agent_response_messages`). `metadata.isConversational` is what tells
+ * the platform's own storage layer which kind of agent this is.
+ */
+export function conversationalAgentJson(spec) {
+    return {
+        version: AGENT_DEFINITION_VERSION,
+        settings: {
+            model: spec.model,
+            // Required by the platform's agent.json schema, same as the inline
+            // agent's — a debug run without both is refused before it starts.
+            maxTokens: spec.maxTokenPerResponse ?? 16384,
+            temperature: spec.temperature ?? 0,
+            // `basic-v2` is the NON-conversational inline agent's engine (the other
+            // `agent.json` writer in this file, 100 lines down), and it was copied in
+            // with the rest of that shape. Every instance of THIS node is
+            // conversational — `metadata.isConversational` below says so
+            // unconditionally — and `voiceAgentJson`, the sibling conversational
+            // family, already spells it the other way. Measured across the 2026-09-23
+            // A/B run: every product-written `agent.json` with `isConversational: true`
+            // carries `conversational-v1` (3 of 3) and every one with `false` carries
+            // `basic-v2` (6 of 6). The SDK's own voice path agreed (2 of 2); only this
+            // path disagreed, and its task graded the sidecar as not conversational.
+            engine: 'conversational-v1',
+            ...(spec.maxIterations === undefined ? {} : { maxIterations: spec.maxIterations }),
+            mode: 'standard',
+        },
+        projectId: spec.source,
+        id: spec.source,
+        name: spec.name,
+        metadata: { storageVersion: '50.0.0', isConversational: true, showProjectCreationExperience: false },
+        type: 'lowCode',
+        guardrails: spec.guardrails ?? [],
+        messages: [
+            { role: 'system', content: spec.systemPrompt, contentTokens: promptTokens(spec.systemPrompt) },
+        ],
+    };
+}
+/**
+ * The `agent.json` sidecar for a VOICE agent.
+ *
+ * The text agent's shape with voice-specific settings. The turn arrives as
+ * audio, while optional flow context is delivered through `inputSchema` and
+ * `{{input.…}}` system-prompt placeholders. There is no `outputSchema` (the
+ * definition declares what comes back), and `settings.voice` carries the
+ * audio configuration in the storage layer's own `StoredVoiceSettings` shape
+ * (`model` / `maxTokens` / `temperature` / `persona`) — with the platform's
+ * catalog defaults filled in, because its own writer treats a partial voice
+ * block as incomplete.
+ */
+export function voiceAgentJson(spec) {
+    // The platform's catalog default (`DEFAULT_CONVERSATIONAL_VOICE_SETTINGS`):
+    // the live Gemini model, its first persona, temperature 0.
+    const DEFAULT_MODEL = 'gemini-3.1-flash-live-preview';
+    const DEFAULT_MAX_TOKENS = 65536;
+    const DEFAULT_PERSONA = 'Aoede';
+    const v = spec.voice ?? {};
+    return {
+        version: AGENT_DEFINITION_VERSION,
+        settings: {
+            engine: 'conversational-v1',
+            mode: 'voice',
+            voice: {
+                model: v.model ?? DEFAULT_MODEL,
+                maxTokens: v.maxTokens ?? DEFAULT_MAX_TOKENS,
+                temperature: v.temperature ?? 0,
+                persona: v.persona ?? DEFAULT_PERSONA,
+            },
+            ...(spec.maxIterations === undefined ? {} : { maxIterations: spec.maxIterations }),
+        },
+        projectId: spec.source,
+        id: spec.source,
+        name: spec.name,
+        ...(spec.plan.refs.length === 0 ? {} : {
+            inputSchema: {
+                type: 'object',
+                properties: Object.fromEntries(spec.plan.refs.map((r) => [r.flatName, {}])),
+            },
+        }),
+        metadata: { storageVersion: '50.0.0', isConversational: true, showProjectCreationExperience: false },
+        type: 'lowCode',
+        guardrails: [],
+        messages: (() => {
+            const system = renderAgentSidecarPrompt(spec.systemPrompt, spec.plan.byName);
+            return [{ role: 'system', content: system, contentTokens: promptTokens(system) }];
+        })(),
+    };
+}
+/**
+ * The `agent.json` an inline agent's `source` directory must hold.
+ *
+ * The node is only half of an inline agent. flow-v1's `handleInlineAgentJob` emits
+ * `entryPoint: "<source>/agent.json"` into the BPMN context, and the runtime
+ * resolves the agent's real configuration — model settings, the message list, the
+ * input/output schemas — from that file relative to the project. A `.flow` with an
+ * inline-agent node and no such file references a definition that is not there.
+ *
+ * Shape transcribed from deployed agents under `runs/` (e.g. the four DevCon
+ * billing agents, `type: 'lowCode'`), which is also what
+ * `uip agent init --inline-in-flow` scaffolds. The `version` is
+ * {@link AGENT_DEFINITION_VERSION}, not the `1.1.0` those older agents carry. `contentTokens` mirrors `content` as
+ * one `simpleText` run: the designer uses those tokens to render a prompt with
+ * inline variable chips, and a single run is the faithful encoding of a plain
+ * string.
+ */
+export function inlineAgentJson(spec) {
+    return {
+        version: AGENT_DEFINITION_VERSION,
+        settings: {
+            model: spec.model,
+            // `maxTokens` and `temperature` are REQUIRED by the platform's own
+            // agent.json schema, not optional as this used to treat them: a debug run of
+            // an agent without both is refused before it starts —
+            //   settings.maxTokens   → "expected number, received undefined"
+            //   settings.temperature → "expected number, received undefined"
+            // (measured on the product runtime, GA row 7's port). Every SDK-authored
+            // inline agent hit it, and no local rung could: an offline runner calls no
+            // model and never reads agent.json, so the sidecar's platform contract had
+            // never been exercised.
+            //
+            // The defaults are what `uip agent init --inline-in-flow` writes and what
+            // v1's own reference agents for this scenario carry.
+            maxTokens: spec.maxTokenPerResponse ?? 16384,
+            temperature: spec.temperature ?? 0,
+            engine: 'basic-v2',
+            ...(spec.maxIterations === undefined ? {} : { maxIterations: spec.maxIterations }),
+            mode: spec.mode ?? 'standard',
+        },
+        // Also required, and also derived rather than authored: the agent's own
+        // directory uuid is its `projectId` and `id` (v1's scaffold writes the same
+        // value in all three places, and it is the node's `inputs.source`).
+        projectId: spec.source,
+        id: spec.source,
+        name: spec.name,
+        // Keyed by FLAT NAME, because that is what the runtime's JobArguments are
+        // keyed by (see the dialect note above). Literal- and expression-bound
+        // inputs are absent on purpose: neither has a JobArgument, so declaring one
+        // would promise an argument that never arrives.
+        //
+        // Each property is left EMPTY here and typed once the scope closes — see
+        // `typeAgentInputSchemas`, which also explains why a wrong type is fatal
+        // rather than untidy.
+        inputSchema: {
+            type: 'object',
+            properties: Object.fromEntries(spec.plan.refs.map((r) => [r.flatName, {}])),
+        },
+        outputSchema: {
+            type: 'object',
+            properties: Object.fromEntries(Object.entries(spec.returns).map(([k, t]) => [k, { type: t }])),
+            required: Object.keys(spec.returns),
+        },
+        metadata: { storageVersion: '50.0.0', isConversational: false, showProjectCreationExperience: false },
+        type: 'lowCode',
+        guardrails: spec.guardrails ?? [],
+        // `content` and `contentTokens` are the half the platform keeps EXACTLY as
+        // authored (the CLI regenerates neither), so this is where the flatName
+        // rewrite has to land. Tokens are derived from the rewritten string rather
+        // than rewritten in parallel — the designer renders from the tokens and the
+        // runtime templates the content, and the two must name the same thing.
+        messages: (() => {
+            const system = renderAgentSidecarPrompt(spec.systemPrompt, spec.plan.byName);
+            const user = renderAgentSidecarPrompt(spec.userPrompt, spec.plan.byName);
+            return [
+                { role: 'system', content: system, contentTokens: promptTokens(system) },
+                { role: 'user', content: user, contentTokens: promptTokens(user) },
+            ];
+        })(),
+    };
+}
+/** `{{input.<name>}}` — the agent-template placeholder, in both prompt directions. */
+const INPUT_PLACEHOLDER = /\{\{\s*input\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\}\}/g;
+/**
+ * Split an agent prompt into the `contentTokens` the designer renders it from.
+ *
+ * The designer shows a prompt as prose with inline variable CHIPS, and `contentTokens`
+ * is that structure: alternating `simpleText` runs and `variable` entries whose
+ * `rawString` is `input.<name>`. Transcribed from deployed agents under `runs/` (the
+ * DevCon billing agents), where a prompt reading
+ * `"…Customer Name: {{input.customerName}}\nInvoice Number: {{input.invoiceNumber}}"`
+ * carries exactly that alternation.
+ *
+ * A prompt with no placeholders is one `simpleText` run, which is what a
+ * variable-free prompt looks like there too.
+ */
+function promptTokens(content) {
+    const tokens = [];
+    let last = 0;
+    for (const m of content.matchAll(INPUT_PLACEHOLDER)) {
+        const at = m.index ?? 0;
+        if (at > last)
+            tokens.push({ type: 'simpleText', rawString: content.slice(last, at) });
+        tokens.push({ type: 'variable', rawString: `input.${m[1]}` });
+        last = at + m[0].length;
+    }
+    if (last < content.length)
+        tokens.push({ type: 'simpleText', rawString: content.slice(last) });
+    return tokens.length ? tokens : [{ type: 'simpleText', rawString: content }];
+}
+/** The `maxIterations` Studio Web writes into every inline agent's `agent.json` (flow-workbench `getDefaultAgentContent()`). */
+const STUDIO_WEB_DEFAULT_MAX_ITERATIONS = 25;
+/**
+ * The agent configuration a SHELL agent node keeps in its sidecar, read from
+ * `<source>/agent.json` in the node's own input names: the prompts, the model,
+ * the run settings (`temperature`, `maxTokenPerResponse`, `maxIterations`,
+ * `mode`), the `guardrails` and (voice) the `voice` settings. Empty when the
+ * node carries prompts itself (an embedded node, e.g. a `.flow` saved by Studio
+ * Web with the self-contained flag on), or when no sidecar can be read.
+ *
+ * A run setting equal to the default a sidecar writer fills in (`temperature`
+ * 0, `maxTokens` 16384, `mode` `'standard'`) is not recovered: recompiling
+ * without it writes the same sidecar, and recovering it would add an argument
+ * the author never wrote to every agent. `mode: 'standard'` is the exception on
+ * a 1.3 node, where naming it is what selected that definition. The same goes
+ * for the inline agent's `maxIterations` 25: the SDK omits it when unset, but
+ * Studio Web always writes it (its `getDefaultAgentContent()` default), so
+ * every Studio Web-saved agent would otherwise decompile with `maxIterations: 25`.
+ */
+export function agentSidecarInputs(o) {
+    const { inputs, source, dialect } = o;
+    if (typeof inputs.systemPrompt === 'string' || typeof inputs.userPrompt === 'string')
+        return {};
+    if (!source)
+        return {};
+    const path = `${source}/agent.json`;
+    const raw = o.read?.(path);
+    if (raw === undefined) {
+        o.warn(`agent step "${o.nodeId}" carries no prompts and ${path} was not found beside the .flow, `
+            + 'so its prompts, model and run settings decompile empty. Keep <source>/agent.json beside the .flow '
+            + '(download the whole project, not just the .flow).');
+        return {};
+    }
+    let agent;
+    try {
+        agent = JSON.parse(raw);
+    }
+    catch {
+        o.warn(`agent step "${o.nodeId}": ${path} is not valid JSON, so its prompts, model and run settings decompile empty.`);
+        return {};
+    }
+    const messages = (Array.isArray(agent?.messages) ? agent.messages : []);
+    const content = (role) => {
+        const c = messages.find((m) => m.role === role)?.content;
+        return typeof c === 'string' ? c : undefined;
+    };
+    const settings = (agent?.settings ?? {});
+    const system = content('system');
+    const user = content('user');
+    const isVoice = dialect === 'voice';
+    const numberUnless = (v, dflt) => typeof v === 'number' && v !== dflt ? v : undefined;
+    // The voice agent's temperature and token cap live in `settings.voice`, not here.
+    const temperature = isVoice ? undefined : numberUnless(settings.temperature, 0);
+    const maxTokenPerResponse = isVoice ? undefined : numberUnless(settings.maxTokens, 16384);
+    // Studio Web's default for the inline agent; the other families keep any value.
+    const maxIterations = dialect === 'inline'
+        ? numberUnless(settings.maxIterations, STUDIO_WEB_DEFAULT_MAX_ITERATIONS)
+        : typeof settings.maxIterations === 'number' ? settings.maxIterations : undefined;
+    // `mode` is a harness choice on the inline agent only; the conversational and
+    // voice sidecars always carry their family's fixed value. `'standard'` is the
+    // sidecar's default, so only another value is the author's. (Naming it no
+    // longer selects a definition version — the node's `{ version }` carries that,
+    // flow-builder-sdk#956.)
+    const mode = dialect === 'inline' && typeof settings.mode === 'string'
+        && settings.mode !== 'standard'
+        ? settings.mode : undefined;
+    return {
+        ...(system === undefined ? {} : { systemPrompt: system }),
+        ...(user === undefined ? {} : { userPrompt: user }),
+        ...(typeof settings.model === 'string' ? { model: settings.model } : {}),
+        ...(temperature === undefined ? {} : { temperature }),
+        ...(maxTokenPerResponse === undefined ? {} : { maxTokenPerResponse }),
+        ...(maxIterations === undefined ? {} : { maxIterations }),
+        ...(mode === undefined ? {} : { mode }),
+        ...(Array.isArray(agent?.guardrails) && agent.guardrails.length > 0 ? { guardrails: agent.guardrails } : {}),
+        ...(isVoice && settings.voice && typeof settings.voice === 'object' ? { voice: settings.voice } : {}),
+    };
+}
+/**
+ * Where an agent schema property points to declare "this is a FILE":
+ * `{ $ref: JOB_ATTACHMENT_REF }`, with {@link jobAttachmentDefinition} under the
+ * same schema's `definitions['job-attachment']`.
+ */
+export const JOB_ATTACHMENT_REF = '#/definitions/job-attachment';
+/**
+ * The canonical `job-attachment` definition an agent schema's file field
+ * `$ref`s into — the uipath-agents skill's `agent-definition.md` § File
+ * Attachments ("Schema is fixed — copy verbatim"), and the same block the
+ * platform's own analyze-attachments tool contract carries.
+ *
+ * It tells the agent runtime that an input is an Orchestrator attachment, so a
+ * file tool (Analyze Files) can resolve the attachment's `ID`.
+ *
+ * A function, not a shared object: each schema gets its own copy, so an edit
+ * to one emitted file cannot reach another.
+ *
+ * (The case serializer keeps its own copy in `case/entry-points.ts`: that one
+ * mirrors the platform's `entry-points.json` packager byte for byte, and its
+ * `MimeType` description differs.)
+ */
+export function jobAttachmentDefinition() {
+    return {
+        type: 'object',
+        properties: {
+            ID: { type: 'string', description: 'Orchestrator attachment key' },
+            FullName: { type: 'string', description: 'File name' },
+            MimeType: { type: 'string', description: 'MIME type, e.g. "application/pdf", "image/png"' },
+            Metadata: {
+                type: 'object',
+                description: 'Dictionary<string, string> of metadata',
+                additionalProperties: { type: 'string' },
+            },
+        },
+        required: ['ID'],
+        'x-uipath-resource-kind': 'JobAttachment',
+    };
+}

package/dist/core/agent-tool-resources.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Which `resources/<id>/resource.json` files an agent's tools write, by their
+ * resource `type`, and whether `compile` owns one (so a file it did not write
+ * this time is stale). Shared by the agents family, which writes the files, and
+ * `compile-cli.ts`, which prunes them; moved from serialize.ts.
+ */
+/**
+ * The resource `type` each deployed-resource tool kind carries in the agent
+ * project, which is NOT its node-type namespace: `maestro` mints
+ * `…tool.processorchestration.*` and its resource type is `processOrchestration`.
+ * Read off the platform's `currentResourceStorageSchema`; flow-workbench's
+ * `CANVAS_TO_STORAGE_TOOL_TYPE` maps them the same way.
+ */
+export declare const TOOL_RESOURCE_TYPE: Record<string, string>;
+/** The resource `type` of a connector tool's file ({@link connectorToolResourceJson}). */
+export declare const CONNECTOR_TOOL_RESOURCE_TYPE = "integration";
+/**
+ * The resource `type` of every platform built-in tool. Shared with tools the
+ * DESIGNER writes and the SDK cannot (`load-attachments`, `create-file`, …), so
+ * on its own it says nothing about who owns a file: `properties.toolType` does.
+ */
+export declare const INTERNAL_TOOL_RESOURCE_TYPE = "internal";
+/** The `properties.toolType` of the built-in HTTP-request tool's file (#935). */
+export declare const HTTP_REQUEST_TOOL_TYPE = "http-request";
+/**
+ * The `properties.toolType` each platform built-in tool carries in the agent
+ * project. Neither the node type nor the label: `analyzefiles` is the
+ * designer's "Analyze Files" and its resource is `analyze-attachments`;
+ * `summarize` is the designer's DeepRAG node (`manifest_node_deepRag_display_label:
+ * "Summarize"` in the vendored workbench strings) and its resource is `deep-rag`.
+ * Read off the platform's `builtInToolPropertiesSchemaV40` discriminated union
+ * (vendored `flow-to-bpmn.mjs`), which also lists `load-attachments` and
+ * `http-request`, and the uipath-agents skill's built-in-tools reference, which
+ * owns the file's body. The runtime ignores an unknown toolType silently, so
+ * this table is the whole contract — one that is wrong selects no tool at all.
+ */
+export declare const BUILTIN_TOOL_TYPE: Record<string, string>;
+/**
+ * Every tool resource identity `compile` writes, read off the tables its
+ * writers use — so a tool kind cannot be written without being owned, or owned
+ * without being written (#935: the #920 built-in files were written as
+ * `internal` and never pruned, because ownership was a hand-kept list in
+ * `compile-cli.ts` that did not have them).
+ *
+ *  * `types` — the resource `type`s compile owns OUTRIGHT: every deployed-resource
+ *    kind's, and `integration` (connector tools, since #867).
+ *  * `internalToolTypes` — `internal` is shared with designer-only built-ins
+ *    (`load-attachments`, `create-file`, `jev-classifier`), so for it ownership
+ *    is the `properties.toolType`, and only the ones compile writes.
+ */
+export declare const COMPILE_WRITTEN_TOOL_RESOURCES: {
+    readonly types: ReadonlySet<string>;
+    readonly internalToolTypes: ReadonlySet<string>;
+};
+/**
+ * Does `compile` own this `resources/<id>/resource.json` — would a compile have
+ * written it, so one this compile did not write is stale rather than someone
+ * else's? Everything it says no to belongs to the designer or to `uip agent
+ * refresh` (escalation, mcp, designer-only built-ins, the kinds the SDK cannot
+ * derive), and is never deleted.
+ */
+export declare function compileOwnsResource(body: Record<string, unknown> | undefined): boolean;

package/dist/core/agent-tool-resources.js

@@ -0,0 +1,81 @@
+/**
+ * Which `resources/<id>/resource.json` files an agent's tools write, by their
+ * resource `type`, and whether `compile` owns one (so a file it did not write
+ * this time is stale). Shared by the agents family, which writes the files, and
+ * `compile-cli.ts`, which prunes them; moved from serialize.ts.
+ */
+/**
+ * The resource `type` each deployed-resource tool kind carries in the agent
+ * project, which is NOT its node-type namespace: `maestro` mints
+ * `…tool.processorchestration.*` and its resource type is `processOrchestration`.
+ * Read off the platform's `currentResourceStorageSchema`; flow-workbench's
+ * `CANVAS_TO_STORAGE_TOOL_TYPE` maps them the same way.
+ */
+export const TOOL_RESOURCE_TYPE = {
+    process: 'process', api: 'api', maestro: 'processOrchestration',
+    flow: 'flow', agent: 'agent', function: 'function',
+};
+/** The resource `type` of a connector tool's file ({@link connectorToolResourceJson}). */
+export const CONNECTOR_TOOL_RESOURCE_TYPE = 'integration';
+/**
+ * The resource `type` of every platform built-in tool. Shared with tools the
+ * DESIGNER writes and the SDK cannot (`load-attachments`, `create-file`, …), so
+ * on its own it says nothing about who owns a file: `properties.toolType` does.
+ */
+export const INTERNAL_TOOL_RESOURCE_TYPE = 'internal';
+/** The `properties.toolType` of the built-in HTTP-request tool's file (#935). */
+export const HTTP_REQUEST_TOOL_TYPE = 'http-request';
+/**
+ * The `properties.toolType` each platform built-in tool carries in the agent
+ * project. Neither the node type nor the label: `analyzefiles` is the
+ * designer's "Analyze Files" and its resource is `analyze-attachments`;
+ * `summarize` is the designer's DeepRAG node (`manifest_node_deepRag_display_label:
+ * "Summarize"` in the vendored workbench strings) and its resource is `deep-rag`.
+ * Read off the platform's `builtInToolPropertiesSchemaV40` discriminated union
+ * (vendored `flow-to-bpmn.mjs`), which also lists `load-attachments` and
+ * `http-request`, and the uipath-agents skill's built-in-tools reference, which
+ * owns the file's body. The runtime ignores an unknown toolType silently, so
+ * this table is the whole contract — one that is wrong selects no tool at all.
+ */
+export const BUILTIN_TOOL_TYPE = {
+    analyzefiles: 'analyze-attachments',
+    summarize: 'deep-rag',
+    batchtransform: 'batch-transform',
+};
+/**
+ * Every tool resource identity `compile` writes, read off the tables its
+ * writers use — so a tool kind cannot be written without being owned, or owned
+ * without being written (#935: the #920 built-in files were written as
+ * `internal` and never pruned, because ownership was a hand-kept list in
+ * `compile-cli.ts` that did not have them).
+ *
+ *  * `types` — the resource `type`s compile owns OUTRIGHT: every deployed-resource
+ *    kind's, and `integration` (connector tools, since #867).
+ *  * `internalToolTypes` — `internal` is shared with designer-only built-ins
+ *    (`load-attachments`, `create-file`, `jev-classifier`), so for it ownership
+ *    is the `properties.toolType`, and only the ones compile writes.
+ */
+export const COMPILE_WRITTEN_TOOL_RESOURCES = {
+    types: new Set([...Object.values(TOOL_RESOURCE_TYPE), CONNECTOR_TOOL_RESOURCE_TYPE]),
+    internalToolTypes: new Set([...Object.values(BUILTIN_TOOL_TYPE), HTTP_REQUEST_TOOL_TYPE]),
+};
+/**
+ * Does `compile` own this `resources/<id>/resource.json` — would a compile have
+ * written it, so one this compile did not write is stale rather than someone
+ * else's? Everything it says no to belongs to the designer or to `uip agent
+ * refresh` (escalation, mcp, designer-only built-ins, the kinds the SDK cannot
+ * derive), and is never deleted.
+ */
+export function compileOwnsResource(body) {
+    const kind = body?.$resourceType;
+    if (kind === 'context')
+        return true;
+    if (kind !== 'tool')
+        return false;
+    const type = String(body?.type);
+    if (type === INTERNAL_TOOL_RESOURCE_TYPE) {
+        const toolType = body?.properties?.toolType;
+        return COMPILE_WRITTEN_TOOL_RESOURCES.internalToolTypes.has(String(toolType));
+    }
+    return COMPILE_WRITTEN_TOOL_RESOURCES.types.has(type);
+}

package/dist/core/cli-spelling.d.ts

@@ -49,3 +49,12 @@ export declare function prepareCommand(connectorKey?: string, action?: string, .
  * @returns `channel:profile.email=d@x.com` as is; `'users[*]:profile.real_name=Coder Evals'` quoted.
  */
 export declare function resolveFlagArg(field: string, by: string, value: string): string;
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export declare const PULL_COMMAND = "uip maestro registry pull";

package/dist/core/cli-spelling.js

@@ -88,3 +88,12 @@ export function resolveFlagArg(field, by, value) {
         return arg;
     return `'${arg.replaceAll("'", `'\\''`)}'`;
 }
+/**
+ * The command a message tells a person or agent to run when the cache is
+ * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
+ * pull` runs this package's pull and fills the same cache, and it is the one
+ * command the authoring skill teaches. Each message used to spell the command
+ * out by hand, so they kept naming the SDK's own entry point after the skill
+ * moved to `uip`. Name it here once.
+ */
+export const PULL_COMMAND = 'uip maestro registry pull';

package/dist/{config.js → core/connector-configuration.js}

@@ -9,8 +9,8 @@
  * nodes already store. See {@link buildConfiguration} for why the split form
  * broke the designer (flow-builder-sdk#936).
  */
-import { parseCeql } from './core/ceql.js';
-import { transportHttpMethod } from './core/connector-inputs.js';
+import { parseCeql } from './ceql.js';
+import { transportHttpMethod } from './connector-inputs.js';
 /**
  * Defaults for the essential keys a library entry does not set. These are the
  * values Studio Web's own constructors give a new connector activity.

package/dist/core/library-cache.d.ts

@@ -21,15 +21,6 @@
 export declare const LIBRARY_JSON_DIR = "library-json";
 export declare const LIBRARY_MARKDOWN_DIR = "library-md";
 export declare const CURRENT_LINK = "current";
-/**
- * The command a message tells a person or agent to run when the cache is
- * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
- * pull` runs this package's pull and fills the same cache, and it is the one
- * command the authoring skill teaches. Each message used to spell the command
- * out by hand, so they kept naming the SDK's own entry point after the skill
- * moved to `uip`. Name it here once.
- */
-export declare const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *

package/dist/core/library-cache.js

@@ -24,15 +24,6 @@ import { join } from "node:path";
 export const LIBRARY_JSON_DIR = "library-json";
 export const LIBRARY_MARKDOWN_DIR = "library-md";
 export const CURRENT_LINK = "current";
-/**
- * The command a message tells a person or agent to run when the cache is
- * empty. It is `uip`, not `npx flow-sdk registry pull`: `uip maestro registry
- * pull` runs this package's pull and fills the same cache, and it is the one
- * command the authoring skill teaches. Each message used to spell the command
- * out by hand, so they kept naming the SDK's own entry point after the skill
- * moved to `uip`. Name it here once.
- */
-export const PULL_COMMAND = "uip maestro registry pull";
 /**
  * Root of the library cache. `UIP_FLOW_SDK_LIBRARY_CACHE` overrides it.
  *