veryfront 0.1.1237 → 0.1.1239

package/esm/src/transforms/mdx/esm-module-loader/utils/stub-module.d.ts

@@ -1,4 +1,14 @@
 export declare function extractNamedImports(code: string, importStatement: string): string[];
 export declare function generateStubCode(modulePath: string, namedImports?: string[]): string;
-export declare function createStubModule(modulePath: string, code: string, importStatement: string, esmCacheDir: string): Promise<string | null>;
+export interface DeferredImportErrorDescriptor {
+    name: string;
+    message: string;
+}
+export interface CreateStubModuleOptions {
+    /** Reject a dynamic import when it executes instead of exporting fallback values. */
+    failOnImport?: boolean;
+    /** Sanitized typed error to throw when a strict dynamic import executes. */
+    deferredError?: DeferredImportErrorDescriptor;
+}
+export declare function createStubModule(modulePath: string, code: string, importStatement: string, esmCacheDir: string, options?: CreateStubModuleOptions): Promise<string | null>;
 //# sourceMappingURL=stub-module.d.ts.map

package/esm/src/transforms/mdx/esm-module-loader/utils/stub-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stub-module.d.ts","sourceRoot":"","sources":["../../../../../../src/src/transforms/mdx/esm-module-loader/utils/stub-module.ts"],"names":[],"mappings":"AAOA,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GACtB,MAAM,EAAE,CAcV;AAgBD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,YAAY,GAAE,MAAM,EAAO,GAC1B,MAAM,CA0BR;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkCxB"}
+{"version":3,"file":"stub-module.d.ts","sourceRoot":"","sources":["../../../../../../src/src/transforms/mdx/esm-module-loader/utils/stub-module.ts"],"names":[],"mappings":"AAOA,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GACtB,MAAM,EAAE,CAcV;AAgBD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,YAAY,GAAE,MAAM,EAAO,GAC1B,MAAM,CA0BR;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAiBD,MAAM,WAAW,uBAAuB;IACtC,qFAAqF;IACrF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,6BAA6B,CAAC;CAC/C;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4CxB"}

package/esm/src/transforms/mdx/esm-module-loader/utils/stub-module.js

@@ -52,28 +52,45 @@ export default new Proxy(function(){}, handler);
 ${namedExports}
 `;
 }
-export async function createStubModule(modulePath, code, importStatement, esmCacheDir) {
+function generateDeferredImportFailureCode(modulePath, deferredError) {
+    const message = JSON.stringify(deferredError?.message ??
+        `[Veryfront] Missing module: ${modulePath}. This module or file does not exist in your project.`);
+    const name = JSON.stringify(deferredError?.name ?? "MissingModuleError");
+    return `const error = new Error(${message});
+error.name = ${name};
+throw error;
+`;
+}
+export async function createStubModule(modulePath, code, importStatement, esmCacheDir, options = {}) {
     const namedImports = extractNamedImports(code, importStatement);
-    const stubHash = hashString(`stub:${modulePath}:${namedImports.join(",")}`);
+    const behavior = options.failOnImport ? "fail-on-import" : "fallback";
+    const deferredIdentity = options.deferredError
+        ? `${options.deferredError.name}:${options.deferredError.message}`
+        : "";
+    const stubHash = hashString(`stub:${behavior}:${modulePath}:${namedImports.join(",")}:${deferredIdentity}`);
     const stubPath = join(esmCacheDir, `stub-${stubHash}.mjs`);
-    const stubCode = generateStubCode(modulePath, namedImports);
+    const stubCode = options.failOnImport
+        ? generateDeferredImportFailureCode(modulePath, options.deferredError)
+        : generateStubCode(modulePath, namedImports);
     try {
         await getLocalFs().writeTextFile(stubPath, stubCode);
-        const errorMessage = namedImports.length
-            ? `Missing module: ${modulePath} (imports: ${namedImports.join(", ")})`
-            : `Missing module: ${modulePath}`;
-        try {
-            getErrorCollector().addModuleError(errorMessage, modulePath, {
+        if (!options.failOnImport) {
+            const errorMessage = namedImports.length
+                ? `Missing module: ${modulePath} (imports: ${namedImports.join(", ")})`
+                : `Missing module: ${modulePath}`;
+            try {
+                getErrorCollector().addModuleError(errorMessage, modulePath, {
+                    namedImports,
+                    importStatement,
+                });
+            }
+            catch (_) {
+                /* expected: error collector may not be initialized in all contexts */
+            }
+            logger.error(`${LOG_PREFIX_MDX_LOADER} Missing module: ${modulePath}`, {
                 namedImports,
-                importStatement,
             });
         }
-        catch (_) {
-            /* expected: error collector may not be initialized in all contexts */
-        }
-        logger.error(`${LOG_PREFIX_MDX_LOADER} Missing module: ${modulePath}`, {
-            namedImports,
-        });
         return stubPath;
     }
     catch (error) {

package/esm/src/transforms/pipeline/stages/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../../../src/src/transforms/pipeline/stages/compile.ts"],"names":[],"mappings":"AAMA,OAAO,EAAyB,KAAK,eAAe,EAAkB,MAAM,aAAa,CAAC;AAI1F,eAAO,MAAM,aAAa,EAAE,eAiE3B,CAAC"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../../../src/src/transforms/pipeline/stages/compile.ts"],"names":[],"mappings":"AAMA,OAAO,EAAyB,KAAK,eAAe,EAAkB,MAAM,aAAa,CAAC;AAoD1F,eAAO,MAAM,aAAa,EAAE,eAqE3B,CAAC"}

package/esm/src/transforms/pipeline/stages/compile.js

@@ -6,6 +6,46 @@ import { upgradeImportAssertions } from "../../esm/import-attributes.js";
 import { ESBUILD_SUPPORTED_FEATURES, getLoaderFromPath } from "../../esm/transform-utils.js";
 import { TransformStage } from "../types.js";
 const logger = rendererLogger.component("esm-transform");
+const ESBUILD_SOURCE_DIAGNOSTIC = Symbol.for("veryfront.bundler.esbuild-source-diagnostic");
+const ObjectPrototypeHasOwnProperty = Object.prototype.hasOwnProperty;
+const ReflectApply = Reflect.apply;
+const ReflectGetOwnPropertyDescriptor = Reflect.getOwnPropertyDescriptor;
+function readOwnDataProperty(value, key) {
+    if (value === null ||
+        (typeof value !== "object" && typeof value !== "function")) {
+        return undefined;
+    }
+    try {
+        const descriptor = ReflectGetOwnPropertyDescriptor(value, key);
+        if (descriptor !== undefined &&
+            ReflectApply(ObjectPrototypeHasOwnProperty, descriptor, ["value"]) === true) {
+            return descriptor.value;
+        }
+    }
+    catch {
+        // A hostile proxy cannot provide trusted source-diagnostic evidence.
+    }
+    return undefined;
+}
+function isEsbuildSourceDiagnostic(error) {
+    return readOwnDataProperty(error, ESBUILD_SOURCE_DIAGNOSTIC) === true;
+}
+/**
+ * `.mdx` and `.md` reach this stage as *generated* JSX: PARSE has already run
+ * the MDX compiler over the tenant's source, so `ctx.code` here is framework
+ * output. A diagnostic with a location points into that generated code, not
+ * into anything the project wrote, so it must not claim tenant ownership — a
+ * remark/rehype/recma plugin emitting broken JSX is a framework fault that has
+ * to page someone.
+ *
+ * Nothing is lost by refusing to infer ownership for these two extensions:
+ * genuine MDX and Markdown *source* errors are classified upstream at PARSE as
+ * `mdx-compile-error` / `markdown-compile-error`, both of which the shared
+ * tenant classifier already recognizes.
+ */
+function isGeneratedContentOutput(filePath) {
+    return filePath.endsWith(".mdx") || filePath.endsWith(".md");
+}
 export const compilePlugin = {
     name: "esbuild-compile",
     stage: TransformStage.COMPILE,
@@ -58,6 +98,10 @@ export const compilePlugin = {
             throw COMPILATION_ERROR.create({
                 detail: `ESM transform failed for ${ctx.filePath} (loader: ${loader}): ${errorMsg}`,
                 cause: err,
+                context: {
+                    tenantBuildFailure: !isGeneratedContentOutput(ctx.filePath) &&
+                        isEsbuildSourceDiagnostic(err),
+                },
             });
         }
     },

package/esm/src/transforms/shared/specifier-suffix.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Import specifier query/hash suffix splitting.
+ *
+ * @module transforms/shared/specifier-suffix
+ */
+/** A specifier split into its path and its trailing `?query` / `#hash`. */
+export interface SplitSpecifier {
+    readonly path: string;
+    readonly suffix: string;
+}
+/**
+ * Split an import specifier into the path and everything from the first `?` or
+ * `#` onward, whichever comes first.
+ *
+ * The cut is at whichever delimiter appears first, not at `?` by preference:
+ * `@/a#b?c` is a hash whose fragment happens to contain a `?`, so the suffix is
+ * `#b?c` and the path is `@/a`. Splitting on `?` there would leave `#b` stuck
+ * on the path and no file would resolve.
+ *
+ * This is the single definition of that rule. It previously existed as three
+ * separate copies across the alias, nested-import and HTTP-cache resolvers,
+ * which agreed only by coincidence.
+ */
+export declare function splitSpecifierSuffix(specifier: string): SplitSpecifier;
+//# sourceMappingURL=specifier-suffix.d.ts.map

package/esm/src/transforms/shared/specifier-suffix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specifier-suffix.d.ts","sourceRoot":"","sources":["../../../../src/src/transforms/shared/specifier-suffix.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CActE"}

package/esm/src/transforms/shared/specifier-suffix.js

@@ -0,0 +1,43 @@
+/**
+ * Import specifier query/hash suffix splitting.
+ *
+ * @module transforms/shared/specifier-suffix
+ */
+const ReflectApply = Reflect.apply;
+const MathMin = Math.min;
+const StringIndexOf = String.prototype.indexOf;
+const StringSlice = String.prototype.slice;
+function stringIndexOf(value, search) {
+    return ReflectApply(StringIndexOf, value, [search]);
+}
+function stringSlice(value, start, end) {
+    return ReflectApply(StringSlice, value, end === undefined ? [start] : [start, end]);
+}
+/**
+ * Split an import specifier into the path and everything from the first `?` or
+ * `#` onward, whichever comes first.
+ *
+ * The cut is at whichever delimiter appears first, not at `?` by preference:
+ * `@/a#b?c` is a hash whose fragment happens to contain a `?`, so the suffix is
+ * `#b?c` and the path is `@/a`. Splitting on `?` there would leave `#b` stuck
+ * on the path and no file would resolve.
+ *
+ * This is the single definition of that rule. It previously existed as three
+ * separate copies across the alias, nested-import and HTTP-cache resolvers,
+ * which agreed only by coincidence.
+ */
+export function splitSpecifierSuffix(specifier) {
+    const queryStart = stringIndexOf(specifier, "?");
+    const hashStart = stringIndexOf(specifier, "#");
+    const suffixStart = queryStart === -1
+        ? hashStart
+        : hashStart === -1
+            ? queryStart
+            : MathMin(queryStart, hashStart);
+    if (suffixStart === -1)
+        return { path: specifier, suffix: "" };
+    return {
+        path: stringSlice(specifier, 0, suffixStart),
+        suffix: stringSlice(specifier, suffixStart),
+    };
+}

package/esm/src/trigger/index.d.ts

@@ -24,9 +24,9 @@
 import "../../_dnt.polyfills.js";
 export { discoverSourceTriggers } from "./discovery.js";
 export { runTriggerTarget } from "./local-runner.js";
-export { isTriggerTarget } from "./target.js";
+export { conversationConflictDiagnostic, declarationConflictDiagnostic, isTriggerTarget, } from "./target.js";
 export { isTriggerId } from "./validation.js";
 export type { SourceTriggerDiscoveryError, SourceTriggerDiscoveryErrorCode, SourceTriggerDiscoveryOptions, SourceTriggerDiscoveryResult, SourceTriggerKind, TriggerDefinitionWithId, TriggerDiscoveryOptions, } from "./discovery.js";
 export type { RunTriggerTargetOptions, TriggerTargetRunResult } from "./local-runner.js";
-export type { TriggerTarget, TriggerTargetKind } from "./target.js";
+export type { AgentConversationMode, AgentTriggerTarget, ResolvedTriggerTarget, TaskTriggerTarget, TriggerTarget, TriggerTargetConfig, TriggerTargetKind, WorkflowTriggerTarget, } from "./target.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/src/trigger/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/trigger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EACV,2BAA2B,EAC3B,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACzF,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/trigger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,YAAY,EACV,2BAA2B,EAC3B,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,EAC5B,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACzF,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/esm/src/trigger/index.js

@@ -24,5 +24,5 @@
 import "../../_dnt.polyfills.js";
 export { discoverSourceTriggers } from "./discovery.js";
 export { runTriggerTarget } from "./local-runner.js";
-export { isTriggerTarget } from "./target.js";
+export { conversationConflictDiagnostic, declarationConflictDiagnostic, isTriggerTarget, } from "./target.js";
 export { isTriggerId } from "./validation.js";

package/esm/src/trigger/local-runner.d.ts

@@ -1,6 +1,6 @@
 import type { RuntimeAdapter } from "../platform/index.js";
 import type { VeryfrontConfig } from "../config/index.js";
-import { type TriggerTarget } from "./target.js";
+import { type TriggerTarget, type TriggerTargetConfig } from "./target.js";
 /** Options for one local trigger target execution. */
 export interface RunTriggerTargetOptions {
     /** Project root used by unified runtime discovery. */
@@ -14,7 +14,7 @@ export interface RunTriggerTargetOptions {
     /** Project identifier exposed to task execution context. */
     projectId?: string;
     /** Canonical task, workflow, or agent reference to execute. */
-    target: TriggerTarget;
+    target: TriggerTargetConfig;
     /** Bounded JSON input supplied to tasks and workflows. */
     input?: unknown;
     /** Required prompt input for agent targets. */

package/esm/src/trigger/local-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-runner.d.ts","sourceRoot":"","sources":["../../../src/src/trigger/local-runner.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAU1D,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAKxE,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,cAAc,CAAC;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,aAAa,CAAC;IACtB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;CACpB;AAuSD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAwBjC"}
+{"version":3,"file":"local-runner.d.ts","sourceRoot":"","sources":["../../../src/src/trigger/local-runner.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAU1D,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAC;AAKrB,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,cAAc,CAAC;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,mBAAmB,CAAC;IAC5B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;CACpB;AAuSD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CA+BjC"}

package/esm/src/trigger/local-runner.js

@@ -6,7 +6,7 @@ import { createWorkflowClient } from "../workflow/api/workflow-client.js";
 import { discoverProjectTaskRuntime, findProjectRuntimeTask, } from "../task/project-runtime.js";
 import { runTask } from "../task/runner.js";
 import { sleep } from "../utils/sleep.js";
-import { snapshotTriggerTarget } from "./target.js";
+import { resolveTriggerTarget, } from "./target.js";
 import { snapshotSerializable } from "./validation.js";
 const WORKFLOW_STATUS_POLL_INTERVAL_MS = 1_000;
 function invalidTriggerConfiguration(detail) {
@@ -257,9 +257,16 @@ async function runAgentTarget(options) {
 export async function runTriggerTarget(options) {
     const start = performance.now();
     options.signal?.throwIfAborted();
-    const target = snapshotTriggerTarget(options.target);
-    if (target === null) {
-        invalidTriggerConfiguration("Trigger target must specify a canonical task, workflow, or agent id.");
+    const resolution = resolveTriggerTarget("Trigger target", options.target);
+    if (resolution.target === undefined) {
+        invalidTriggerConfiguration(resolution.detail);
+    }
+    const target = resolution.target;
+    // A local run never reaches the hosted conversation store, so only
+    // `existing` is refusable: `create_new` and `none` both mean "run
+    // standalone here" and need no local handling.
+    if (target.kind === "agent" && target.conversationMode === "existing") {
+        invalidTriggerConfiguration("Local agent trigger runs cannot attach to an existing cloud conversation.");
     }
     const normalizedOptions = {
         ...options,

package/esm/src/trigger/target.d.ts

@@ -1,16 +1,108 @@
-/** Supported local trigger target kinds. */
-export type TriggerTargetKind = "task" | "workflow" | "agent";
+/** Hosted conversation behavior for an agent trigger target. */
+export type AgentConversationMode = "create_new" | "existing" | "none";
+/** Trigger target addressing a task definition. */
+export interface TaskTriggerTarget extends TriggerTarget {
+    /** Definition kind resolved by project runtime discovery. */
+    kind: "task";
+    /** Canonical slash-separated definition identifier. */
+    id: string;
+    /** Task targets do not carry hosted conversation behavior. */
+    conversationMode?: never;
+    /** Task targets do not carry hosted conversation identifiers. */
+    conversationId?: never;
+}
+/** Trigger target addressing a workflow definition. */
+export interface WorkflowTriggerTarget extends TriggerTarget {
+    /** Definition kind resolved by project runtime discovery. */
+    kind: "workflow";
+    /** Canonical slash-separated definition identifier. */
+    id: string;
+    /** Workflow targets do not carry hosted conversation behavior. */
+    conversationMode?: never;
+    /** Workflow targets do not carry hosted conversation identifiers. */
+    conversationId?: never;
+}
+/** Trigger target addressing an agent definition and its hosted conversation. */
+export interface AgentTriggerTarget extends TriggerTarget {
+    /** Definition kind resolved by project runtime discovery. */
+    kind: "agent";
+    /** Canonical slash-separated definition identifier. */
+    id: string;
+    /** Hosted conversation behavior; defaults to `none`. */
+    conversationMode?: AgentConversationMode | undefined;
+    /** Existing conversation UUID; required only with `conversationMode: "existing"`. */
+    conversationId?: string | null | undefined;
+}
 /** Canonical reference to a runnable project definition. */
 export interface TriggerTarget {
     /** Definition kind resolved by project runtime discovery. */
-    kind: TriggerTargetKind;
+    kind: "task" | "workflow" | "agent";
     /** Canonical slash-separated definition identifier. */
     id: string;
 }
+/** Author-facing target shape accepting stored base values and kind-specific literals. */
+export type TriggerTargetConfig = (TriggerTarget & {
+    conversationMode?: never;
+    conversationId?: never;
+}) | TaskTriggerTarget | WorkflowTriggerTarget | AgentTriggerTarget;
+/** Validated target value that narrows conversation fields by `kind`. */
+export type ResolvedTriggerTarget = TaskTriggerTarget | WorkflowTriggerTarget | AgentTriggerTarget;
+/** Supported local trigger target kinds. */
+export type TriggerTargetKind = TriggerTarget["kind"];
+/**
+ * Own keys a trigger target may declare, widened for agent targets.
+ *
+ * TypeScript without `exactOptionalPropertyTypes` accepts an explicitly
+ * undefined value for an optional `never` property. Keep that authoring shape
+ * aligned with runtime normalization while still rejecting accessors and every
+ * defined conversation value on non-agent targets.
+ */
+export declare function triggerTargetKeys(value: unknown): readonly string[];
+/**
+ * Describe why agent conversation addressing is invalid, or return `null`.
+ *
+ * `label` prefixes the diagnostic so schedules, webhooks, and targets report
+ * the same invariant with their own field path.
+ */
+export declare function agentConversationDiagnostic(label: string, conversationMode: unknown, conversationId: unknown): string | null;
+/**
+ * Describe one value declared in two places with disagreeing content.
+ *
+ * Repeating a value is redundant, not wrong: an author spanning a platform
+ * upgrade must be able to write a single definition that both the old and the
+ * new platform read correctly. Only a disagreement is unresolvable, because
+ * honoring one copy would detach the deployed trigger from what the other copy
+ * names.
+ */
+export declare function declarationConflictDiagnostic(label: string, path: string, legacyPath: string, value: unknown, legacyValue: unknown): string | null;
+/**
+ * Describe a conversation pair that disagrees across two locations.
+ *
+ * `legacyLabel` names the other location so the message spells out both real
+ * field paths without ranking them: which one a given platform reads depends
+ * on its version, so neither can be called authoritative here.
+ */
+export declare function conversationConflictDiagnostic(label: string, legacyLabel: string, target: ResolvedTriggerTarget, legacyConversationMode: unknown, legacyConversationId: unknown): string | null;
+/** A canonical target, or the reason the value is not one. */
+export type TriggerTargetResolution = {
+    readonly target: ResolvedTriggerTarget;
+    readonly detail?: undefined;
+} | {
+    readonly target?: undefined;
+    readonly detail: string;
+};
+/**
+ * Validate and copy the canonical fields of a trigger target.
+ *
+ * Public `TriggerTarget` interfaces are intentionally extendable, so this
+ * generic helper ignores caller-owned extension fields. Schedule and webhook
+ * authoring validators apply strict key checks before calling this helper.
+ */
+export declare function resolveTriggerTarget(label: string, value: unknown): TriggerTargetResolution;
 /**
  * Validate and copy a trigger target without retaining caller-owned state.
  */
-export declare function snapshotTriggerTarget(value: unknown): TriggerTarget | null;
+export declare function snapshotTriggerTarget(value: unknown): ResolvedTriggerTarget | null;
 /** Return true only for canonical targets stored in own data properties. */
-export declare function isTriggerTarget(value: unknown): value is TriggerTarget;
+export declare function isTriggerTarget(value: unknown): value is ResolvedTriggerTarget;
 //# sourceMappingURL=target.d.ts.map

package/esm/src/trigger/target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../../src/src/trigger/target.ts"],"names":[],"mappings":"AAEA,4CAA4C;AAC5C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAE9D,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,IAAI,EAAE,iBAAiB,CAAC;IACxB,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;CACZ;AAOD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAgB1E;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE"}
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../../src/src/trigger/target.ts"],"names":[],"mappings":"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"}

package/esm/src/trigger/target.js

@@ -1,27 +1,197 @@
 import { isTriggerId } from "./validation.js";
+const AGENT_CONVERSATION_MODES = new Set([
+    "create_new",
+    "existing",
+    "none",
+]);
+const CONVERSATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAX_DIAGNOSTIC_KEY_LENGTH = 80;
+const SIMPLE_DIAGNOSTIC_KEY_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$-]*$/;
+const TARGET_KEYS = ["kind", "id"];
+const CONVERSATION_TARGET_KEYS = ["conversationMode", "conversationId"];
+const AGENT_TARGET_KEYS = [
+    ...TARGET_KEYS,
+    ...CONVERSATION_TARGET_KEYS,
+];
 function readOwnDataProperty(value, key) {
     const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
     return descriptor && "value" in descriptor ? descriptor.value : undefined;
 }
 /**
- * Validate and copy a trigger target without retaining caller-owned state.
+ * Own keys a trigger target may declare, widened for agent targets.
+ *
+ * TypeScript without `exactOptionalPropertyTypes` accepts an explicitly
+ * undefined value for an optional `never` property. Keep that authoring shape
+ * aligned with runtime normalization while still rejecting accessors and every
+ * defined conversation value on non-agent targets.
  */
-export function snapshotTriggerTarget(value) {
+export function triggerTargetKeys(value) {
     if (typeof value !== "object" || value === null)
+        return TARGET_KEYS;
+    try {
+        if (readOwnDataProperty(value, "kind") === "agent")
+            return AGENT_TARGET_KEYS;
+        const keys = [...TARGET_KEYS];
+        for (const key of CONVERSATION_TARGET_KEYS) {
+            const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+            if (descriptor !== undefined && "value" in descriptor && descriptor.value === undefined) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    }
+    catch {
+        return TARGET_KEYS;
+    }
+}
+/**
+ * Describe why agent conversation addressing is invalid, or return `null`.
+ *
+ * `label` prefixes the diagnostic so schedules, webhooks, and targets report
+ * the same invariant with their own field path.
+ */
+export function agentConversationDiagnostic(label, conversationMode, conversationId) {
+    if (conversationMode !== undefined &&
+        !AGENT_CONVERSATION_MODES.has(conversationMode)) {
+        return `${label}.conversationMode must be create_new, existing, or none.`;
+    }
+    if (conversationId !== undefined && conversationId !== null &&
+        (typeof conversationId !== "string" ||
+            !CONVERSATION_ID_PATTERN.test(conversationId))) {
+        return `${label}.conversationId must be a UUID or null.`;
+    }
+    const effectiveMode = conversationMode ?? "none";
+    if (effectiveMode === "existing" && typeof conversationId !== "string") {
+        return `${label}.conversationId is required when conversationMode is existing.`;
+    }
+    if (effectiveMode !== "existing" && typeof conversationId === "string") {
+        return `${label}.conversationId is allowed only when conversationMode is existing.`;
+    }
+    return null;
+}
+/**
+ * Describe one value declared in two places with disagreeing content.
+ *
+ * Repeating a value is redundant, not wrong: an author spanning a platform
+ * upgrade must be able to write a single definition that both the old and the
+ * new platform read correctly. Only a disagreement is unresolvable, because
+ * honoring one copy would detach the deployed trigger from what the other copy
+ * names.
+ */
+export function declarationConflictDiagnostic(label, path, legacyPath, value, legacyValue) {
+    if (value === undefined || legacyValue === undefined)
+        return null;
+    if (value === legacyValue)
+        return null;
+    return `${label} ${path} and ${legacyPath} are both set to different values. Declare it in one place.`;
+}
+/**
+ * Describe a conversation pair that disagrees across two locations.
+ *
+ * `legacyLabel` names the other location so the message spells out both real
+ * field paths without ranking them: which one a given platform reads depends
+ * on its version, so neither can be called authoritative here.
+ */
+export function conversationConflictDiagnostic(label, legacyLabel, target, legacyConversationMode, legacyConversationId) {
+    if (target.kind !== "agent")
+        return null;
+    for (const [field, targetValue, legacyValue] of [
+        ["conversationMode", target.conversationMode, legacyConversationMode],
+        ["conversationId", target.conversationId, legacyConversationId],
+    ]) {
+        const detail = declarationConflictDiagnostic(label, `target.${field}`, `${legacyLabel}.${field}`, targetValue, legacyValue);
+        if (detail !== null)
+            return detail;
+    }
+    return null;
+}
+function truncateDiagnosticKey(key) {
+    if (key.length <= MAX_DIAGNOSTIC_KEY_LENGTH)
+        return key;
+    let prefix = key.slice(0, MAX_DIAGNOSTIC_KEY_LENGTH);
+    const finalCodeUnit = prefix.charCodeAt(prefix.length - 1);
+    if (finalCodeUnit >= 0xd800 && finalCodeUnit <= 0xdbff) {
+        prefix = prefix.slice(0, -1);
+    }
+    return `${prefix}…`;
+}
+function formatDiagnosticProperty(label, key) {
+    const boundedKey = truncateDiagnosticKey(key);
+    return SIMPLE_DIAGNOSTIC_KEY_PATTERN.test(boundedKey)
+        ? `${label}.${boundedKey}`
+        : `${label}[${JSON.stringify(boundedKey)}]`;
+}
+function requireOwnDataField(label, value, key) {
+    const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined || "value" in descriptor)
         return null;
+    return {
+        detail: `${formatDiagnosticProperty(label, key)} must be an own data property.`,
+    };
+}
+/**
+ * Validate and copy the canonical fields of a trigger target.
+ *
+ * Public `TriggerTarget` interfaces are intentionally extendable, so this
+ * generic helper ignores caller-owned extension fields. Schedule and webhook
+ * authoring validators apply strict key checks before calling this helper.
+ */
+export function resolveTriggerTarget(label, value) {
+    const notATarget = {
+        detail: `${label} must specify a canonical task, workflow, or agent id.`,
+    };
+    if (typeof value !== "object" || value === null)
+        return notATarget;
     try {
         const kind = readOwnDataProperty(value, "kind");
         const id = readOwnDataProperty(value, "id");
         if ((kind !== "task" && kind !== "workflow" && kind !== "agent") ||
             !isTriggerId(id)) {
-            return null;
+            return notATarget;
         }
-        return { kind, id };
+        const conversationModeField = requireOwnDataField(label, value, "conversationMode");
+        if (conversationModeField !== null)
+            return conversationModeField;
+        const conversationIdField = requireOwnDataField(label, value, "conversationId");
+        if (conversationIdField !== null)
+            return conversationIdField;
+        const conversationMode = readOwnDataProperty(value, "conversationMode");
+        const conversationId = readOwnDataProperty(value, "conversationId");
+        if (kind !== "agent") {
+            if (conversationMode !== undefined) {
+                return { detail: `${label}.conversationMode is supported only for agent targets.` };
+            }
+            if (conversationId !== undefined) {
+                return { detail: `${label}.conversationId is supported only for agent targets.` };
+            }
+            return { target: { kind, id } };
+        }
+        const conversationDetail = agentConversationDiagnostic(label, conversationMode, conversationId);
+        if (conversationDetail !== null)
+            return { detail: conversationDetail };
+        return {
+            target: {
+                kind,
+                id,
+                ...(conversationMode === undefined
+                    ? {}
+                    : { conversationMode: conversationMode }),
+                ...(conversationId === undefined
+                    ? {}
+                    : { conversationId: conversationId }),
+            },
+        };
     }
     catch {
-        return null;
+        return notATarget;
     }
 }
+/**
+ * Validate and copy a trigger target without retaining caller-owned state.
+ */
+export function snapshotTriggerTarget(value) {
+    return resolveTriggerTarget("Trigger target", value).target ?? null;
+}
 /** Return true only for canonical targets stored in own data properties. */
 export function isTriggerTarget(value) {
     return snapshotTriggerTarget(value) !== null;

package/esm/src/utils/version-constant.d.ts

@@ -1,3 +1,3 @@
 /** Shared version value. */
-export declare const VERSION = "0.1.1237";
+export declare const VERSION = "0.1.1239";
 //# sourceMappingURL=version-constant.d.ts.map

package/esm/src/utils/version-constant.js

@@ -1,4 +1,4 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
 /** Shared version value. */
-export const VERSION = "0.1.1237";
+export const VERSION = "0.1.1239";