@trigger.dev/core 0.0.0-prerelease-20260508090504 → 0.0.0-prerelease-20260810145618

package/dist/esm/v3/realtimeStreams/streamsWriterV2.d.ts

@@ -1,4 +1,5 @@
-import { StreamsWriter } from "./types.js";
+import { ChatChunkTooLargeError } from "../errors.js";
+import type { StreamsWriter, StreamWriteResult } from "./types.js";
 export type StreamsWriterV2Options<T = any> = {
     basin: string;
     stream: string;
@@ -51,11 +52,31 @@ export declare class StreamsWriterV2<T = any> implements StreamsWriter {
     private readonly maxInflightBytes;
     private aborted;
     private sessionWritable;
+    private lastSeqNum;
     constructor(options: StreamsWriterV2Options<T>);
     private handleAbort;
     private initializeServerStream;
-    wait(): Promise<void>;
+    wait(): Promise<StreamWriteResult>;
     [Symbol.asyncIterator](): AsyncIterableIterator<T>;
     private log;
     private logError;
 }
+/**
+ * Encode a chunk as a JSON record body for S2, enforcing the per-record
+ * size cap. Exported so the size/discriminant logic can be unit-tested
+ * directly without spinning up an S2 client or mocking `@s2-dev/streamstore`.
+ *
+ * Returns `{ ok: true, body }` when the encoded chunk fits within
+ * `RECORD_BODY_MAX_BYTES`, or `{ ok: false, error }` carrying a
+ * `ChatChunkTooLargeError` annotated with the chunk's discriminant
+ * (`type` or `kind`, whichever is present) so the surfaced error is
+ * useful — "tool-output-available chunk too large" beats a bare
+ * "chunk too large" by a lot.
+ */
+export declare function encodeChunkOrError(chunk: unknown): {
+    ok: true;
+    body: string;
+} | {
+    ok: false;
+    error: ChatChunkTooLargeError;
+};

package/dist/esm/v3/realtimeStreams/streamsWriterV2.js

@@ -1,5 +1,12 @@
 import { S2, AppendRecord, BatchTransform } from "@s2-dev/streamstore";
+import { ChatChunkTooLargeError } from "../errors.js";
 import { nanoid } from "nanoid";
+// S2 caps a single record at 1 MiB of metered bytes (body + headers + 8 byte
+// overhead). We give ourselves ~1 KiB of headroom for the JSON envelope and
+// metering bytes so the check fires before the SDK's internal `BatchTransform`
+// rejects the record with an opaque `S2Error`.
+const RECORD_BODY_MAX_BYTES = 1024 * 1024 - 1024;
+const utf8Encoder = new TextEncoder();
 /**
  * StreamsWriterV2 writes metadata stream data directly to S2 (https://s2.dev).
  *
@@ -40,6 +47,7 @@ export class StreamsWriterV2 {
     maxInflightBytes;
     aborted = false;
     sessionWritable = null;
+    lastSeqNum;
     constructor(options) {
         this.options = options;
         this.debug = options.debug ?? false;
@@ -119,8 +127,12 @@ export class StreamsWriterV2 {
                         controller.error(new Error("Stream aborted"));
                         return;
                     }
-                    // Convert each chunk to JSON string and wrap in AppendRecord
-                    controller.enqueue(AppendRecord.string({ body: JSON.stringify({ data: chunk, id: nanoid(7) }) }));
+                    const encoded = encodeChunkOrError(chunk);
+                    if (!encoded.ok) {
+                        controller.error(encoded.error);
+                        return;
+                    }
+                    controller.enqueue(AppendRecord.string({ body: encoded.body }));
                 },
             }))
                 .pipeThrough(new BatchTransform({
@@ -131,8 +143,16 @@ export class StreamsWriterV2 {
             // Get final position to verify completion
             const lastAcked = session.lastAckedPosition();
             if (lastAcked?.end) {
-                const recordsWritten = lastAcked.end.seqNum;
-                this.log(`[S2MetadataStream] Written ${recordsWritten} records, ending at seqNum=${lastAcked.end.seqNum}`);
+                /**
+                 * S2's ack `end.seqNum` is exclusive: the seq AFTER the last record
+                 * written (equal to the tail). Report the last record's own seq
+                 * (`end - 1`) as `lastEventId` so a resume subscribe, which reads
+                 * from `lastEventId + 1`, lands on the next record instead of
+                 * skipping one. Matches the inclusive seq the one-shot control
+                 * writer returns.
+                 */
+                this.lastSeqNum = lastAcked.end.seqNum - 1;
+                this.log(`[S2MetadataStream] Wrote through seqNum=${this.lastSeqNum}`);
             }
         }
         catch (error) {
@@ -146,6 +166,7 @@ export class StreamsWriterV2 {
     }
     async wait() {
         await this.streamPromise;
+        return { lastEventId: this.lastSeqNum?.toString() };
     }
     [Symbol.asyncIterator]() {
         return streamToAsyncIterator(this.consumerStream);
@@ -180,6 +201,45 @@ function safeReleaseLock(reader) {
     try {
         reader.releaseLock();
     }
-    catch (error) { }
+    catch (_error) { }
+}
+// chat.agent emits two chunk shapes through this writer:
+//   - UIMessageChunks + custom data parts: `{ type: "tool-output-available" | "data-..." | ... }`
+//   - ChatInputChunks (mostly seen on `.in`, but reused as the discriminant
+//     elsewhere): `{ kind: "message" | "stop" | "action" }`
+// Surfacing whichever discriminant exists turns "chunk too large" into
+// "tool-output-available chunk too large", which is what users actually need.
+function extractChunkType(chunk) {
+    if (!chunk || typeof chunk !== "object")
+        return undefined;
+    const c = chunk;
+    if (typeof c.type === "string")
+        return c.type;
+    if (typeof c.kind === "string")
+        return c.kind;
+    return undefined;
+}
+/**
+ * Encode a chunk as a JSON record body for S2, enforcing the per-record
+ * size cap. Exported so the size/discriminant logic can be unit-tested
+ * directly without spinning up an S2 client or mocking `@s2-dev/streamstore`.
+ *
+ * Returns `{ ok: true, body }` when the encoded chunk fits within
+ * `RECORD_BODY_MAX_BYTES`, or `{ ok: false, error }` carrying a
+ * `ChatChunkTooLargeError` annotated with the chunk's discriminant
+ * (`type` or `kind`, whichever is present) so the surfaced error is
+ * useful — "tool-output-available chunk too large" beats a bare
+ * "chunk too large" by a lot.
+ */
+export function encodeChunkOrError(chunk) {
+    const body = JSON.stringify({ data: chunk, id: nanoid(7) });
+    const size = utf8Encoder.encode(body).length;
+    if (size > RECORD_BODY_MAX_BYTES) {
+        return {
+            ok: false,
+            error: new ChatChunkTooLargeError(size, RECORD_BODY_MAX_BYTES, extractChunkType(chunk)),
+        };
+    }
+    return { ok: true, body };
 }
 //# sourceMappingURL=streamsWriterV2.js.map

package/dist/esm/v3/realtimeStreams/streamsWriterV2.js.map

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

package/dist/esm/v3/realtimeStreams/streamsWriterV2.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/v3/realtimeStreams/streamsWriterV2.test.js

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { ChatChunkTooLargeError, isChatChunkTooLargeError } from "../errors.js";
+import { encodeChunkOrError } from "./streamsWriterV2.js";
+// The size cap and discriminant extraction are the only S2-independent bits
+// of `StreamsWriterV2` that benefit from unit coverage. Both live in the
+// `encodeChunkOrError` pure helper, so the tests exercise it directly — no
+// `vi.mock("@s2-dev/streamstore", ...)` shim needed.
+describe("encodeChunkOrError", () => {
+    it("flags oversize chunks and carries the chunk's `type` discriminant", () => {
+        const oversized = {
+            type: "tool-output-available",
+            output: { text: "x".repeat(2_000_000) },
+        };
+        const result = encodeChunkOrError(oversized);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return; // type guard
+        expect(isChatChunkTooLargeError(result.error)).toBe(true);
+        expect(result.error.chunkType).toBe("tool-output-available");
+        expect(result.error.chunkSize).toBeGreaterThan(1_000_000);
+        expect(result.error.maxSize).toBe(1024 * 1024 - 1024);
+        expect(result.error.message).toMatch(/tool-output-available/);
+        expect(result.error.message).toMatch(/chat\.agent chunk/);
+    });
+    it("falls back to chunk.kind when chunk.type is missing (ChatInputChunk-style)", () => {
+        const oversized = { kind: "action", payload: "x".repeat(2_000_000) };
+        const result = encodeChunkOrError(oversized);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.error.chunkType).toBe("action");
+    });
+    it("omits chunkType when the chunk has no discriminant", () => {
+        const oversized = "x".repeat(2_000_000);
+        const result = encodeChunkOrError(oversized);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.error.chunkType).toBeUndefined();
+    });
+    it("returns the encoded body for chunks under the cap", () => {
+        const small = { type: "text-delta", delta: "hello" };
+        const result = encodeChunkOrError(small);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        const parsed = JSON.parse(result.body);
+        expect(parsed.data).toEqual(small);
+        expect(parsed.id).toMatch(/^[A-Za-z0-9_-]{7}$/); // nanoid(7)
+    });
+});
+// Cross-check the ChatChunkTooLargeError type-guard helper itself. Trivial,
+// but keeps the test surface here exercising the public error helpers a
+// consumer would import from the same module.
+describe("isChatChunkTooLargeError", () => {
+    it("recognizes its own error class", () => {
+        const err = new ChatChunkTooLargeError(2_000_000, 1024 * 1024 - 1024, "x");
+        expect(isChatChunkTooLargeError(err)).toBe(true);
+    });
+    it("rejects unrelated errors", () => {
+        expect(isChatChunkTooLargeError(new Error("nope"))).toBe(false);
+        expect(isChatChunkTooLargeError("string")).toBe(false);
+        expect(isChatChunkTooLargeError(undefined)).toBe(false);
+    });
+});
+//# sourceMappingURL=streamsWriterV2.test.js.map

package/dist/esm/v3/realtimeStreams/streamsWriterV2.test.js.map

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

package/dist/esm/v3/realtimeStreams/types.d.ts

@@ -1,9 +1,9 @@
-import { AnyZodFetchOptions, ApiRequestOptions } from "../apiClient/core.js";
+import type { AnyZodFetchOptions, ApiRequestOptions } from "../apiClient/core.js";
 import type { InputStreamOncePromise } from "../inputStreams/types.js";
 export { InputStreamOncePromise, InputStreamTimeoutError } from "../inputStreams/types.js";
 export type { InputStreamOnceResult } from "../inputStreams/types.js";
-import { AsyncIterableStream } from "../streams/asyncIterableStream.js";
-import { Prettify } from "../types/utils.js";
+import type { AsyncIterableStream } from "../streams/asyncIterableStream.js";
+import type { Prettify } from "../types/utils.js";
 import type { ManualWaitpointPromise } from "../waitpoints/index.js";
 export type RealtimeStreamOperationOptions = {
     signal?: AbortSignal;
@@ -14,12 +14,15 @@ export interface RealtimeStreamsManager {
     pipe<T>(key: string, source: AsyncIterable<T> | ReadableStream<T>, options?: RealtimeStreamOperationOptions): RealtimeStreamInstance<T>;
     append<TPart extends BodyInit>(key: string, part: TPart, options?: RealtimeStreamOperationOptions): Promise<void>;
 }
+export type StreamWriteResult = {
+    lastEventId?: string;
+};
 export interface RealtimeStreamInstance<T> {
-    wait(): Promise<void>;
+    wait(): Promise<StreamWriteResult>;
     get stream(): AsyncIterableStream<T>;
 }
 export interface StreamsWriter {
-    wait(): Promise<void>;
+    wait(): Promise<StreamWriteResult>;
 }
 export type RealtimeDefinedStream<TPart> = {
     id: string;
@@ -52,6 +55,10 @@ export type PipeStreamOptions = {
      * Additional request options for the API call.
      */
     requestOptions?: ApiRequestOptions;
+    /** Override the default span name for this operation. */
+    spanName?: string;
+    /** When true, the span will be collapsed in the dashboard. */
+    collapsed?: boolean;
 };
 /**
  * The result of piping data to a realtime stream.
@@ -69,7 +76,7 @@ export type PipeStreamResult<T> = {
      * to the realtime stream. Use this to wait for the stream to complete before
      * finishing your task.
      */
-    waitUntilComplete: () => Promise<void>;
+    waitUntilComplete: () => Promise<StreamWriteResult>;
 };
 /**
  * Options for reading data from a realtime stream.
@@ -156,6 +163,20 @@ export type RealtimeDefinedInputStream<TData> = {
      * Uses a waitpoint token internally. Can only be called inside a task.run().
      */
     wait: (options?: InputStreamWaitOptions) => ManualWaitpointPromise<TData>;
+    /**
+     * Wait for data with an idle phase before suspending.
+     *
+     * Keeps the task active (using compute) for `idleTimeoutInSeconds`,
+     * then suspends via `.wait()` if no data arrives. If data arrives during
+     * the idle phase the task responds instantly without suspending.
+     */
+    waitWithIdleTimeout: (options: InputStreamWaitWithIdleTimeoutOptions) => Promise<{
+        ok: true;
+        output: TData;
+    } | {
+        ok: false;
+        error?: any;
+    }>;
     /**
      * Send data to this input stream on a specific run.
      * This is used from outside the task (e.g., from your backend or another task).
@@ -168,6 +189,8 @@ export type InputStreamSubscription = {
 export type InputStreamOnceOptions = {
     signal?: AbortSignal;
     timeoutMs?: number;
+    /** Override the default span name for this operation. */
+    spanName?: string;
 };
 export type SendInputStreamOptions = {
     requestOptions?: ApiRequestOptions;
@@ -198,6 +221,22 @@ export type InputStreamWaitOptions = {
      * and filtering waitpoints via `wait.listTokens()`.
      */
     tags?: string[];
+    /** Override the default span name for this operation. */
+    spanName?: string;
+};
+export type InputStreamWaitWithIdleTimeoutOptions = {
+    /** Seconds to keep the task idle (active, using compute) before suspending. */
+    idleTimeoutInSeconds: number;
+    /** Maximum time to wait after suspending (duration string, e.g. "1h"). */
+    timeout?: string;
+    /** Override the default span name for the outer operation. */
+    spanName?: string;
+    /** Called right before suspending (after idle phase times out). Not called if data arrives during idle. */
+    onSuspend?: () => void | Promise<void>;
+    /** Called right after resuming from suspension with data. Not called if data arrived during idle or on timeout. */
+    onResume?: () => void | Promise<void>;
+    /** When true, skip the suspend phase entirely. If idle times out, return `{ ok: false }` immediately. */
+    skipSuspend?: boolean;
 };
 export type InferInputStreamType<T> = T extends RealtimeDefinedInputStream<infer TData> ? TData : unknown;
 /**

package/dist/esm/v3/resource-catalog/catalog.d.ts

@@ -1,11 +1,15 @@
-import { PromptManifest, QueueManifest, TaskManifest, WorkerManifest } from "../schemas/index.js";
-import { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
+import type { PromptManifest, QueueManifest, SkillManifest, SkillMetadata, TaskManifest, WorkerManifest } from "../schemas/index.js";
+import type { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
 export interface ResourceCatalog {
     setCurrentFileContext(filePath: string, entryPoint: string): void;
     clearCurrentFileContext(): void;
     registerTaskMetadata(task: TaskMetadataWithFunctions): void;
     updateTaskMetadata(id: string, task: Partial<TaskMetadataWithFunctions>): void;
     listTaskManifests(): Array<TaskManifest>;
+    listTaskIdCollisions(): Array<{
+        id: string;
+        filePaths: string[];
+    }>;
     getTaskManifest(id: string): TaskManifest | undefined;
     getTask(id: string): TaskMetadataWithFunctions | undefined;
     taskExists(id: string): boolean;
@@ -17,4 +21,7 @@ export interface ResourceCatalog {
     listPromptManifests(): Array<PromptManifest>;
     getPrompt(id: string): PromptMetadataWithFunctions | undefined;
     getPromptSchema(id: string): TaskSchema | undefined;
+    registerSkillMetadata(skill: SkillMetadata): void;
+    listSkillManifests(): Array<SkillManifest>;
+    getSkillManifest(id: string): SkillManifest | undefined;
 }

package/dist/esm/v3/resource-catalog/index.d.ts

@@ -1,5 +1,5 @@
-import { PromptManifest, QueueManifest, TaskManifest, WorkerManifest } from "../schemas/index.js";
-import { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
+import type { PromptManifest, QueueManifest, SkillManifest, SkillMetadata, TaskManifest, WorkerManifest } from "../schemas/index.js";
+import type { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
 import { type ResourceCatalog } from "./catalog.js";
 export declare class ResourceCatalogAPI {
     #private;
@@ -15,6 +15,10 @@ export declare class ResourceCatalogAPI {
     clearCurrentFileContext(): void;
     registerWorkerManifest(workerManifest: WorkerManifest): void;
     listTaskManifests(): Array<TaskManifest>;
+    listTaskIdCollisions(): Array<{
+        id: string;
+        filePaths: string[];
+    }>;
     getTaskManifest(id: string): TaskManifest | undefined;
     getTask(id: string): TaskMetadataWithFunctions | undefined;
     getTaskSchema(id: string): TaskSchema | undefined;
@@ -24,4 +28,7 @@ export declare class ResourceCatalogAPI {
     listPromptManifests(): Array<PromptManifest>;
     getPrompt(id: string): PromptMetadataWithFunctions | undefined;
     getPromptSchema(id: string): TaskSchema | undefined;
+    registerSkillMetadata(skill: SkillMetadata): void;
+    listSkillManifests(): Array<SkillManifest>;
+    getSkillManifest(id: string): SkillManifest | undefined;
 }

package/dist/esm/v3/resource-catalog/index.js

@@ -38,6 +38,9 @@ export class ResourceCatalogAPI {
     listTaskManifests() {
         return this.#getCatalog().listTaskManifests();
     }
+    listTaskIdCollisions() {
+        return this.#getCatalog().listTaskIdCollisions();
+    }
     getTaskManifest(id) {
         return this.#getCatalog().getTaskManifest(id);
     }
@@ -65,6 +68,15 @@ export class ResourceCatalogAPI {
     getPromptSchema(id) {
         return this.#getCatalog().getPromptSchema(id);
     }
+    registerSkillMetadata(skill) {
+        this.#getCatalog().registerSkillMetadata(skill);
+    }
+    listSkillManifests() {
+        return this.#getCatalog().listSkillManifests();
+    }
+    getSkillManifest(id) {
+        return this.#getCatalog().getSkillManifest(id);
+    }
     #getCatalog() {
         return getGlobal(API_NAME) ?? NOOP_RESOURCE_CATALOG;
     }

package/dist/esm/v3/resource-catalog/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/v3/resource-catalog/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/v3/resource-catalog/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/v3/resource-catalog/noopResourceCatalog.d.ts

@@ -1,12 +1,16 @@
-import { PromptManifest, QueueManifest, TaskManifest, WorkerManifest } from "../schemas/index.js";
+import type { PromptManifest, QueueManifest, SkillManifest, SkillMetadata, TaskManifest, WorkerManifest } from "../schemas/index.js";
 import { type PromptMetadataWithFunctions, type TaskMetadataWithFunctions, type TaskSchema } from "../types/index.js";
-import { ResourceCatalog } from "./catalog.js";
+import type { ResourceCatalog } from "./catalog.js";
 export declare class NoopResourceCatalog implements ResourceCatalog {
     registerTaskMetadata(task: TaskMetadataWithFunctions): void;
     setCurrentFileContext(filePath: string, entryPoint: string): void;
     clearCurrentFileContext(): void;
     updateTaskMetadata(id: string, updates: Partial<TaskMetadataWithFunctions>): void;
     listTaskManifests(): Array<TaskManifest>;
+    listTaskIdCollisions(): Array<{
+        id: string;
+        filePaths: string[];
+    }>;
     getTaskManifest(id: string): TaskManifest | undefined;
     getTask(id: string): TaskMetadataWithFunctions | undefined;
     getTaskSchema(id: string): TaskSchema | undefined;
@@ -19,4 +23,7 @@ export declare class NoopResourceCatalog implements ResourceCatalog {
     listPromptManifests(): Array<PromptManifest>;
     getPrompt(id: string): PromptMetadataWithFunctions | undefined;
     getPromptSchema(id: string): TaskSchema | undefined;
+    registerSkillMetadata(skill: SkillMetadata): void;
+    listSkillManifests(): Array<SkillManifest>;
+    getSkillManifest(id: string): SkillManifest | undefined;
 }

package/dist/esm/v3/resource-catalog/noopResourceCatalog.js

@@ -14,6 +14,9 @@ export class NoopResourceCatalog {
     listTaskManifests() {
         return [];
     }
+    listTaskIdCollisions() {
+        return [];
+    }
     getTaskManifest(id) {
         return undefined;
     }
@@ -50,5 +53,14 @@ export class NoopResourceCatalog {
     getPromptSchema(id) {
         return undefined;
     }
+    registerSkillMetadata(skill) {
+        // noop
+    }
+    listSkillManifests() {
+        return [];
+    }
+    getSkillManifest(id) {
+        return undefined;
+    }
 }
 //# sourceMappingURL=noopResourceCatalog.js.map

package/dist/esm/v3/resource-catalog/noopResourceCatalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"noopResourceCatalog.js","sourceRoot":"","sources":["../../../../src/v3/resource-catalog/noopResourceCatalog.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,mBAAmB;IAC9B,oBAAoB,CAAC,IAA+B;QAClD,OAAO;IACT,CAAC;IAED,qBAAqB,CAAC,QAAgB,EAAE,UAAkB;QACxD,OAAO;IACT,CAAC;IAED,uBAAuB;QACrB,OAAO;IACT,CAAC;IAED,kBAAkB,CAAC,EAAU,EAAE,OAA2C;QACxE,OAAO;IACT,CAAC;IAED,iBAAiB;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,eAAe,CAAC,EAAU;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,aAAa,CAAC,EAAU;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO;QACL,OAAO;IACT,CAAC;IAED,sBAAsB,CAAC,cAA8B;QACnD,OAAO;IACT,CAAC;IAED,qBAAqB,CAAC,KAAoB;QACxC,OAAO;IACT,CAAC;IAED,kBAAkB;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,sBAAsB,CAAC,MAAmC;QACxD,OAAO;IACT,CAAC;IAED,mBAAmB;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,eAAe,CAAC,EAAU;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}
+{"version":3,"file":"noopResourceCatalog.js","sourceRoot":"","sources":["../../../../src/v3/resource-catalog/noopResourceCatalog.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,mBAAmB;IAC9B,oBAAoB,CAAC,IAA+B;QAClD,OAAO;IACT,CAAC;IAED,qBAAqB,CAAC,QAAgB,EAAE,UAAkB;QACxD,OAAO;IACT,CAAC;IAED,uBAAuB;QACrB,OAAO;IACT,CAAC;IAED,kBAAkB,CAAC,EAAU,EAAE,OAA2C;QACxE,OAAO;IACT,CAAC;IAED,iBAAiB;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,oBAAoB;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,eAAe,CAAC,EAAU;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,aAAa,CAAC,EAAU;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO;QACL,OAAO;IACT,CAAC;IAED,sBAAsB,CAAC,cAA8B;QACnD,OAAO;IACT,CAAC;IAED,qBAAqB,CAAC,KAAoB;QACxC,OAAO;IACT,CAAC;IAED,kBAAkB;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,sBAAsB,CAAC,MAAmC;QACxD,OAAO;IACT,CAAC;IAED,mBAAmB;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,eAAe,CAAC,EAAU;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,qBAAqB,CAAC,KAAoB;QACxC,OAAO;IACT,CAAC;IAED,kBAAkB;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,gBAAgB,CAAC,EAAU;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/esm/v3/resource-catalog/standardResourceCatalog.d.ts

@@ -1,6 +1,17 @@
-import { PromptManifest, TaskManifest, WorkerManifest, QueueManifest } from "../schemas/index.js";
-import { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
-import { ResourceCatalog } from "./catalog.js";
+import type { PromptManifest, SkillManifest, SkillMetadata, TaskManifest, WorkerManifest, QueueManifest } from "../schemas/index.js";
+import type { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
+import type { ResourceCatalog } from "./catalog.js";
+/**
+ * Sentinel file-context value the runtime workers set around task execution
+ * (via `TaskExecutor.execute`) so that `task()` calls firing during a run —
+ * e.g. as a side effect of `await import(...)` of a module containing a
+ * task definition — register normally instead of hitting the silent-drop
+ * guard in `registerTaskMetadata`. The catalog uses this exact string to
+ * detect "registered during execution" and emit a one-time warning per
+ * task id. The indexer never sets this context, so its behavior is
+ * unchanged.
+ */
+export declare const NO_FILE_CONTEXT = "<no-context>";
 export declare class StandardResourceCatalog implements ResourceCatalog {
     private _taskSchemas;
     private _taskMetadata;
@@ -12,8 +23,16 @@ export declare class StandardResourceCatalog implements ResourceCatalog {
     private _promptSchemas;
     private _currentFileContext?;
     private _queueMetadata;
+    private _skillMetadata;
+    private _skillFileMetadata;
+    private _sentinelContextWarned;
+    private _taskIdCollisions;
     setCurrentFileContext(filePath: string, entryPoint: string): void;
     clearCurrentFileContext(): void;
+    listTaskIdCollisions(): Array<{
+        id: string;
+        filePaths: string[];
+    }>;
     registerQueueMetadata(queue: QueueManifest): void;
     registerWorkerManifest(workerManifest: WorkerManifest): void;
     registerTaskMetadata(task: TaskMetadataWithFunctions): void;
@@ -28,5 +47,8 @@ export declare class StandardResourceCatalog implements ResourceCatalog {
     getPromptSchema(id: string): TaskSchema | undefined;
     listPromptManifests(): Array<PromptManifest>;
     getPrompt(id: string): PromptMetadataWithFunctions | undefined;
+    registerSkillMetadata(skill: SkillMetadata): void;
+    listSkillManifests(): Array<SkillManifest>;
+    getSkillManifest(id: string): SkillManifest | undefined;
     disable(): void;
 }