@abinnovision/nestjs-hatchet 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.3.0](https://github.com/abinnovision/nestjs-commons/compare/nestjs-hatchet-v0.2.4...nestjs-hatchet-v0.3.0) (2026-01-10)
+
+
+### Features
+
+* add execution wrapper support for tasks and workflows ([#54](https://github.com/abinnovision/nestjs-commons/issues/54)) ([8f96d3d](https://github.com/abinnovision/nestjs-commons/commit/8f96d3deb9ad40392a9d3328990c851947abf663))
+* add hatchet integration ([#44](https://github.com/abinnovision/nestjs-commons/issues/44)) ([59a2138](https://github.com/abinnovision/nestjs-commons/commit/59a2138788ea2a262ad70b3298429dd518345d1c))
+* allow event definitions to be used in onEvents from @Host(...) ([#80](https://github.com/abinnovision/nestjs-commons/issues/80)) ([2408228](https://github.com/abinnovision/nestjs-commons/commit/2408228f2aeb7a70ddc9e2119b5f1c1614a807c0))
+* normalize hatchet inputs depending on trigger source ([#78](https://github.com/abinnovision/nestjs-commons/issues/78)) ([3cf5485](https://github.com/abinnovision/nestjs-commons/commit/3cf5485800b3a4f64fb191d0a7335136cf24725c))
+* normalize hatchet inputs depending on trigger source ([#79](https://github.com/abinnovision/nestjs-commons/issues/79)) ([e91f113](https://github.com/abinnovision/nestjs-commons/commit/e91f11341fc5fdd02e9254c9671eabf0fddf49b1))
+* rename execution wrapper to interceptor and remove unused code ([#58](https://github.com/abinnovision/nestjs-commons/issues/58)) ([b9dacbd](https://github.com/abinnovision/nestjs-commons/commit/b9dacbdca8ad41312768a98ed559f4c030ca7b5a))
+* scope down the public api ([#81](https://github.com/abinnovision/nestjs-commons/issues/81)) ([4924861](https://github.com/abinnovision/nestjs-commons/commit/4924861c54cfceabf567565f704c52a1b75209a1))
+* support multiple interceptors ([#59](https://github.com/abinnovision/nestjs-commons/issues/59)) ([f686508](https://github.com/abinnovision/nestjs-commons/commit/f686508b6f4e61d03846173c061152e0481a2b48))
+* update worker configuration structure ([#56](https://github.com/abinnovision/nestjs-commons/issues/56)) ([3de8fb4](https://github.com/abinnovision/nestjs-commons/commit/3de8fb44e9814bb2a12d1a1b9081c03945f398cb))
+
+
+### Bug Fixes
+
+* align exports in package.json ([#70](https://github.com/abinnovision/nestjs-commons/issues/70)) ([58956c5](https://github.com/abinnovision/nestjs-commons/commit/58956c5ea55394b65c6af405f4c6ac45555dc94a))
+* remove dual registration of host providers ([#64](https://github.com/abinnovision/nestjs-commons/issues/64)) ([2c262f2](https://github.com/abinnovision/nestjs-commons/commit/2c262f2877a7676854324ac841ae5f58f9dbd97f))
+* resolve interceptor using ModuleRef ([#67](https://github.com/abinnovision/nestjs-commons/issues/67)) ([aedb022](https://github.com/abinnovision/nestjs-commons/commit/aedb0223d4b8aa99a967420bf211c176da04a293))
+* simplify ref types ([#60](https://github.com/abinnovision/nestjs-commons/issues/60)) ([79680d1](https://github.com/abinnovision/nestjs-commons/commit/79680d12c5b0aa2fc9201a574c36f743f5518c43))
+* streamline context and interaction exports for public api ([#61](https://github.com/abinnovision/nestjs-commons/issues/61)) ([529deb1](https://github.com/abinnovision/nestjs-commons/commit/529deb1a30577debc40f94a23eb1ad99e2aaf2ae))
+
 ## [0.2.3](https://github.com/abinnovision/nestjs-commons/compare/nestjs-hatchet-v0.2.2...nestjs-hatchet-v0.2.3) (2025-12-16)
 
 

package/dist/__fixtures__/test-hosts.d.ts

@@ -1,4 +1,4 @@
-import type { TaskCtx, WorkflowCtx } from "../context";
+import type { TaskCtx, WorkflowCtx } from "../execution";
 declare const TestTask_base: {
     new (): {
         readonly __task_host_brand: void;

package/dist/__fixtures__/test-hosts.js

@@ -13,7 +13,7 @@ exports.NoMethodsWorkflow = exports.TestWorkflow = exports.NoSchemaTask = export
 exports.setParamTypes = setParamTypes;
 const zod_1 = require("zod");
 const abstracts_1 = require("../abstracts");
-const decorators_1 = require("../decorators");
+const metadata_1 = require("../metadata");
 // ============ TaskHost Fixtures ============
 /** Standard TaskHost with string data schema */
 let TestTask = class TestTask extends (0, abstracts_1.taskHost)(zod_1.z.object({ data: zod_1.z.string() })) {
@@ -23,13 +23,13 @@ let TestTask = class TestTask extends (0, abstracts_1.taskHost)(zod_1.z.object({
 };
 exports.TestTask = TestTask;
 __decorate([
-    (0, decorators_1.Task)({}),
+    (0, metadata_1.Task)({}),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Object]),
     __metadata("design:returntype", void 0)
 ], TestTask.prototype, "execute", null);
 exports.TestTask = TestTask = __decorate([
-    (0, decorators_1.Host)({ name: "test-task" })
+    (0, metadata_1.Host)({ name: "test-task" })
 ], TestTask);
 /** TaskHost without any decorated methods (invalid) */
 let NoMethodsTask = class NoMethodsTask extends (0, abstracts_1.taskHost)() {
@@ -39,7 +39,7 @@ let NoMethodsTask = class NoMethodsTask extends (0, abstracts_1.taskHost)() {
 };
 exports.NoMethodsTask = NoMethodsTask;
 exports.NoMethodsTask = NoMethodsTask = __decorate([
-    (0, decorators_1.Host)({ name: "no-methods-task" })
+    (0, metadata_1.Host)({ name: "no-methods-task" })
 ], NoMethodsTask);
 /** TaskHost without input schema */
 let NoSchemaTask = class NoSchemaTask extends (0, abstracts_1.taskHost)() {
@@ -49,13 +49,13 @@ let NoSchemaTask = class NoSchemaTask extends (0, abstracts_1.taskHost)() {
 };
 exports.NoSchemaTask = NoSchemaTask;
 __decorate([
-    (0, decorators_1.Task)({}),
+    (0, metadata_1.Task)({}),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Object]),
     __metadata("design:returntype", void 0)
 ], NoSchemaTask.prototype, "execute", null);
 exports.NoSchemaTask = NoSchemaTask = __decorate([
-    (0, decorators_1.Host)({ name: "no-schema-task" })
+    (0, metadata_1.Host)({ name: "no-schema-task" })
 ], NoSchemaTask);
 // ============ WorkflowHost Fixtures ============
 /** Standard WorkflowHost with two-step DAG */
@@ -69,19 +69,19 @@ let TestWorkflow = class TestWorkflow extends (0, abstracts_1.workflowHost)(zod_
 };
 exports.TestWorkflow = TestWorkflow;
 __decorate([
-    (0, decorators_1.WorkflowTask)({ parents: [] }),
+    (0, metadata_1.WorkflowTask)({ parents: [] }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Object]),
     __metadata("design:returntype", void 0)
 ], TestWorkflow.prototype, "step1", null);
 __decorate([
-    (0, decorators_1.WorkflowTask)({ parents: ["step1"] }),
+    (0, metadata_1.WorkflowTask)({ parents: ["step1"] }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", [Object]),
     __metadata("design:returntype", void 0)
 ], TestWorkflow.prototype, "step2", null);
 exports.TestWorkflow = TestWorkflow = __decorate([
-    (0, decorators_1.Host)({ name: "test-workflow" })
+    (0, metadata_1.Host)({ name: "test-workflow" })
 ], TestWorkflow);
 /** WorkflowHost without any decorated methods (invalid) */
 let NoMethodsWorkflow = class NoMethodsWorkflow extends (0, abstracts_1.workflowHost)() {
@@ -91,7 +91,7 @@ let NoMethodsWorkflow = class NoMethodsWorkflow extends (0, abstracts_1.workflow
 };
 exports.NoMethodsWorkflow = NoMethodsWorkflow;
 exports.NoMethodsWorkflow = NoMethodsWorkflow = __decorate([
-    (0, decorators_1.Host)({ name: "no-methods-workflow" })
+    (0, metadata_1.Host)({ name: "no-methods-workflow" })
 ], NoMethodsWorkflow);
 // ============ Test Utilities ============
 /** Sets design:paramtypes metadata for a method (needed in vitest) */

package/dist/accessor/host-accessor.d.ts

@@ -1,12 +1,20 @@
+import type { SdkHostOpts } from "./opts-translator";
 import type { HostOpts, TaskOpts, WorkflowTaskOpts } from "../decorators";
-import type { AnyHost, AnyHostCtor } from "../ref";
+import type { AnyHost, AnyHostCtor } from "../ref/shared";
 /**
  * Accessor for host metadata and methods.
  */
 declare class HostAccessor {
     readonly ctor: AnyHostCtor;
     constructor(ctor: AnyHostCtor);
+    /**
+     * Returns raw enhanced metadata from @Host() decorator.
+     */
     get metadata(): HostOpts;
+    /**
+     * Returns SDK-compatible options for workflow declarations.
+     */
+    get sdkOpts(): SdkHostOpts;
     get name(): string;
     get isWorkflow(): boolean;
     get isTask(): boolean;

package/dist/accessor/host-accessor.js

@@ -5,6 +5,7 @@ exports.fromInstance = fromInstance;
 /* eslint-disable @typescript-eslint/no-unsafe-return,@typescript-eslint/no-unsafe-member-access,@typescript-eslint/no-unsafe-argument,@typescript-eslint/no-unsafe-assignment */
 const abstracts_1 = require("../abstracts");
 const internal_1 = require("../internal");
+const opts_translator_1 = require("./opts-translator");
 /**
  * Accessor for host metadata and methods.
  */
@@ -13,9 +14,18 @@ class HostAccessor {
     constructor(ctor) {
         this.ctor = ctor;
     }
+    /**
+     * Returns raw enhanced metadata from @Host() decorator.
+     */
     get metadata() {
         return Reflect.getMetadata(internal_1.METADATA_KEY_HOST_OPTS, this.ctor);
     }
+    /**
+     * Returns SDK-compatible options for workflow declarations.
+     */
+    get sdkOpts() {
+        return (0, opts_translator_1.translateHostOpts)(this.metadata);
+    }
     get name() {
         return this.metadata.name;
     }

package/dist/accessor/host-opts-translator.d.ts

@@ -0,0 +1,14 @@
+import type { HostOpts } from "../decorators";
+import type { CreateBaseWorkflowOpts } from "@hatchet-dev/typescript-sdk";
+/**
+ * SDK-compatible host options.
+ */
+export type SdkHostOpts = Omit<CreateBaseWorkflowOpts, "on">;
+/**
+ * Translates onEvents to SDK-compatible string array.
+ */
+export declare function translateOnEvents(onEvents: HostOpts["onEvents"] | undefined): string[] | undefined;
+/**
+ * Translates enhanced HostOpts to SDK-compatible SdkHostOpts.
+ */
+export declare function translateHostOpts(opts: HostOpts): SdkHostOpts;

package/dist/accessor/host-opts-translator.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateOnEvents = translateOnEvents;
+exports.translateHostOpts = translateHostOpts;
+/**
+ * Translates onEvents to SDK-compatible string array.
+ */
+function translateOnEvents(onEvents) {
+    if (!onEvents || onEvents.length === 0) {
+        return undefined;
+    }
+    return onEvents.map((e) => (typeof e === "string" ? e : e.name));
+}
+/**
+ * Translates enhanced HostOpts to SDK-compatible SdkHostOpts.
+ */
+function translateHostOpts(opts) {
+    const { onEvents, ...passthrough } = opts;
+    const translatedOnEvents = translateOnEvents(onEvents);
+    // Only include onEvents if it has values (exactOptionalPropertyTypes compliance)
+    if (translatedOnEvents) {
+        return { ...passthrough, onEvents: translatedOnEvents };
+    }
+    return passthrough;
+}

package/dist/accessor/host-opts.d.ts

@@ -0,0 +1,31 @@
+import type { CreateBaseWorkflowOpts } from "@hatchet-dev/typescript-sdk";
+import type { AnyEventDefinition } from "../events";
+/**
+ * SDK-compatible host options.
+ */
+export type SdkHostOpts = Omit<CreateBaseWorkflowOpts, "on">;
+/**
+ * Input type for onEvents - accepts strings or EventDefinitions.
+ */
+export type OnEventsInput = ReadonlyArray<string | AnyEventDefinition>;
+/**
+ * Properties we enhance beyond SDK types.
+ */
+interface EnhancedProperties {
+    name: string;
+    onEvents?: OnEventsInput;
+}
+type PassthroughProperties = Omit<CreateBaseWorkflowOpts, "on" | keyof EnhancedProperties>;
+/**
+ * Enhanced HostOpts for @Host() decorator.
+ */
+export type HostOpts = EnhancedProperties & PassthroughProperties;
+/**
+ * Translates onEvents to SDK-compatible string array.
+ */
+export declare function translateOnEvents(onEvents: OnEventsInput | undefined): string[] | undefined;
+/**
+ * Translates enhanced HostOpts to SDK-compatible SdkHostOpts.
+ */
+export declare function translateHostOpts(opts: HostOpts): SdkHostOpts;
+export {};

package/dist/accessor/host-opts.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateOnEvents = translateOnEvents;
+exports.translateHostOpts = translateHostOpts;
+/**
+ * Translates onEvents to SDK-compatible string array.
+ */
+function translateOnEvents(onEvents) {
+    if (!onEvents || onEvents.length === 0)
+        return undefined;
+    return onEvents.map((e) => (typeof e === "string" ? e : e.name));
+}
+/**
+ * Translates enhanced HostOpts to SDK-compatible SdkHostOpts.
+ */
+function translateHostOpts(opts) {
+    const { onEvents, ...passthrough } = opts;
+    const translatedOnEvents = translateOnEvents(onEvents);
+    // Only include onEvents if it has values (exactOptionalPropertyTypes compliance)
+    if (translatedOnEvents) {
+        return {
+            ...passthrough,
+            onEvents: translatedOnEvents,
+        };
+    }
+    return passthrough;
+}

package/dist/accessor/index.d.ts

@@ -1 +1,2 @@
 export { fromCtor, fromInstance } from "./host-accessor";
+export type { SdkHostOpts } from "./opts-translator";

package/dist/accessor/opts-translator.d.ts

@@ -0,0 +1,10 @@
+import type { HostOpts } from "../decorators";
+import type { CreateBaseWorkflowOpts } from "@hatchet-dev/typescript-sdk";
+/**
+ * SDK-compatible host options.
+ */
+export type SdkHostOpts = Omit<CreateBaseWorkflowOpts, "on">;
+/**
+ * Translates enhanced HostOpts to SDK-compatible SdkHostOpts.
+ */
+export declare const translateHostOpts: (opts: HostOpts) => SdkHostOpts;

package/dist/accessor/opts-translator.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateHostOpts = void 0;
+/**
+ * Translates onEvents to SDK-compatible string array.
+ */
+const translateOnEvents = (onEvents) => {
+    // If no onEvents provided, return undefined
+    if (!onEvents || onEvents.length === 0) {
+        return undefined;
+    }
+    return onEvents.map((e) => (typeof e === "string" ? e : e.name));
+};
+/**
+ * Translates enhanced HostOpts to SDK-compatible SdkHostOpts.
+ */
+const translateHostOpts = (opts) => {
+    const { onEvents, ...passthrough } = opts;
+    const translatedOnEvents = translateOnEvents(onEvents);
+    // Only include onEvents if it has values
+    if (translatedOnEvents) {
+        return { ...passthrough, onEvents: translatedOnEvents };
+    }
+    return passthrough;
+};
+exports.translateHostOpts = translateHostOpts;

package/dist/client/client.d.ts

@@ -1,7 +1,7 @@
 import { HatchetClient } from "@hatchet-dev/typescript-sdk";
 import { PushEventOptions } from "@hatchet-dev/typescript-sdk/clients/event/event-client";
-import { type AnyEventDefinition, type EventInput } from "../events";
-import type { HostRunFn } from "../interaction";
+import type { AnyEventDefinition, EventInput } from "../events";
+import type { HostRunFn } from "../execution";
 import type { Event } from "@hatchet-dev/typescript-sdk/protoc/events";
 /**
  * Options for emitting events.

package/dist/client/client.js

@@ -12,14 +12,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Client = void 0;
 const typescript_sdk_1 = require("@hatchet-dev/typescript-sdk");
 const common_1 = require("@nestjs/common");
-const events_1 = require("../events");
-const adapter_factory_1 = require("../interaction/host-run/adapter-factory");
+const event_definition_1 = require("../events/event-definition");
+const host_run_1 = require("../execution/host-run");
 let Client = class Client {
     client;
     run;
     constructor(client) {
         this.client = client;
-        this.run = (0, adapter_factory_1.createHostRunForAdmin)(client);
+        this.run = (0, host_run_1.createHostRunForAdmin)(client);
     }
     /**
      * Access to the underlying HatchetClient SDK.
@@ -42,7 +42,7 @@ let Client = class Client {
      * ```
      */
     async emit(event, input, options) {
-        return await this.client.events.push(event.name, { ...input, [events_1.EVENT_MARKER]: event.name }, options);
+        return await this.client.events.push(event.name, { ...input, [event_definition_1.EVENT_MARKER]: event.name }, options);
     }
     /**
      * Emit multiple events of the same type.
@@ -65,7 +65,7 @@ let Client = class Client {
             return [];
         }
         const result = await this.client.events.bulkPush(event.name, inputs.map((input) => ({
-            payload: { ...input, [events_1.EVENT_MARKER]: event.name },
+            payload: { ...input, [event_definition_1.EVENT_MARKER]: event.name },
         })), options);
         return result.events;
     }

package/dist/context/context-factory.d.ts

@@ -1,16 +1,22 @@
-import type { TaskCtx, WorkflowCtx } from "./context";
-import type { Context as HContext } from "@hatchet-dev/typescript-sdk";
+import { type BaseCtx, type HostTriggerConfig, type TaskCtx, type WorkflowCtx } from "./context";
+/**
+ * Arguments for context factory functions.
+ * Derived from BaseCtx using Pick to ensure type alignment.
+ */
+type CreateCtxArgs<I> = Pick<BaseCtx<I>, "fromSDK" | "triggerSource"> & {
+    input: I;
+    hostConfig: HostTriggerConfig;
+};
 /**
  * Creates a TaskCtx from SDK Context for standalone task execution.
  *
- * @param sdkCtx The SDK context.
- * @param validatedInput Optional validated/transformed input to use instead of raw SDK input.
+ * @param args The arguments for creating the task context.
  */
-export declare function createTaskCtx<I>(sdkCtx: HContext<I, any>, validatedInput?: I): TaskCtx<any>;
+export declare const createTaskCtx: <I>(args: CreateCtxArgs<I>) => TaskCtx<any>;
 /**
  * Creates a WorkflowCtx from SDK Context for workflow task execution.
  *
- * @param sdkCtx The SDK context.
- * @param validatedInput Optional validated/transformed input to use instead of raw SDK input.
+ * @param args The arguments for creating the workflow context.
  */
-export declare function createWorkflowCtx<I>(sdkCtx: HContext<I, any>, validatedInput?: I): WorkflowCtx<any>;
+export declare const createWorkflowCtx: <I>(args: CreateCtxArgs<I>) => WorkflowCtx<any>;
+export {};

package/dist/context/context-factory.js

@@ -1,43 +1,70 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTaskCtx = createTaskCtx;
-exports.createWorkflowCtx = createWorkflowCtx;
+exports.createWorkflowCtx = exports.createTaskCtx = void 0;
+const context_1 = require("./context");
 const adapter_factory_1 = require("../interaction/host-run/adapter-factory");
+/**
+ * Creates the helper methods derived from the SDK context.
+ * These are methods that wrap SDK functionality.
+ */
+const createContextHelpers = (fromSDK) => ({
+    run: (0, adapter_factory_1.createHostRunForContext)(fromSDK),
+});
+/**
+ * Creates the trigger guard methods bound to the context's trigger source.
+ */
+const createTriggerGuards = (triggerSource, input) => ({
+    isRun: () => triggerSource === "run",
+    isCron: () => triggerSource === "cron",
+    isEvent: (eventDef) => {
+        if (triggerSource !== "event") {
+            return false;
+        }
+        // If no event definition is provided, then we validate against any event.
+        if (!eventDef) {
+            return true;
+        }
+        return eventDef.isCtx({ input });
+    },
+});
+/**
+ * Maps the args to the 1:1 context properties.
+ */
+const mapContextProperties = (args) => ({
+    fromSDK: args.fromSDK,
+    input: args.input,
+    triggerSource: args.triggerSource,
+    hostConfig: args.hostConfig,
+});
 /**
  * Creates a TaskCtx from SDK Context for standalone task execution.
  *
- * @param sdkCtx The SDK context.
- * @param validatedInput Optional validated/transformed input to use instead of raw SDK input.
+ * @param args The arguments for creating the task context.
  */
-function createTaskCtx(sdkCtx, validatedInput) {
-    const run = (0, adapter_factory_1.createHostRunForContext)(sdkCtx);
-    // Cast needed because TASK_MARKER is a phantom type for compile-time detection only
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    return {
-        fromSDK: sdkCtx,
-        input: validatedInput ?? sdkCtx.input,
-        run,
-    };
-}
+const createTaskCtx = (args) => ({
+    [context_1.TASK_MARKER]: true,
+    ...mapContextProperties(args),
+    ...createContextHelpers(args.fromSDK),
+    ...createTriggerGuards(args.triggerSource, args.input),
+});
+exports.createTaskCtx = createTaskCtx;
 /**
  * Creates a WorkflowCtx from SDK Context for workflow task execution.
  *
- * @param sdkCtx The SDK context.
- * @param validatedInput Optional validated/transformed input to use instead of raw SDK input.
+ * @param args The arguments for creating the workflow context.
  */
-function createWorkflowCtx(sdkCtx, validatedInput) {
-    const run = (0, adapter_factory_1.createHostRunForContext)(sdkCtx);
+const createWorkflowCtx = (args) => {
     const parent = async (method) => {
         const methodName = method.name;
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-        return await sdkCtx.parentOutput(methodName);
+        return await args.fromSDK.parentOutput(methodName);
     };
-    // Cast needed because TASK_MARKER is a phantom type for compile-time detection only
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
     return {
-        fromSDK: sdkCtx,
-        input: validatedInput ?? sdkCtx.input,
-        run,
+        [context_1.TASK_MARKER]: true,
+        ...mapContextProperties(args),
+        ...createContextHelpers(args.fromSDK),
+        ...createTriggerGuards(args.triggerSource, args.input),
         parent,
     };
-}
+};
+exports.createWorkflowCtx = createWorkflowCtx;

package/dist/context/context.d.ts

@@ -1,9 +1,34 @@
 import type { TaskHost, WorkflowHost } from "../abstracts";
+import type { AnyEventDefinition, EventOutput } from "../events";
 import type { HostRunFn } from "../interaction";
-import type { AnyTaskFn, OutputOfTaskFn } from "../ref";
+import type { AnyTaskFn, OutputOfTaskFn } from "../ref/shared";
 import type { Context } from "@hatchet-dev/typescript-sdk";
-declare const TASK_MARKER: unique symbol;
+export declare const TASK_MARKER: unique symbol;
 export type TaskMarker = typeof TASK_MARKER;
+/**
+ * Type representing the source that triggered the task execution.
+ *
+ * - "run": Triggered with default payload via direct run.
+ * - "event": Triggered by an event.
+ * - "cron": Triggered by a cron schedule.
+ *
+ * Note that the detection of trigger source is best-effort and may not be accurate in all cases.
+ * Hatchet does not currently provide first-class support for distinguishing all trigger sources.
+ */
+export type TriggerSource = "run" | "event" | "cron";
+/**
+ * Configuration extracted from host decorator for trigger introspection.
+ */
+export interface HostTriggerConfig {
+    /**
+     * Event names this host listens to
+     */
+    onEvents: string[];
+    /**
+     * Cron schedules this host responds to
+     */
+    onCrons: string[];
+}
 /**
  * Type for the context when a task is running. This is universal for standalone and workflow tasks.
  * This partially implements the `Context` type from the SDK.
@@ -11,6 +36,14 @@ export type TaskMarker = typeof TASK_MARKER;
  * @template I The input type of the task.
  */
 export interface BaseCtx<I> {
+    /**
+     * Host metadata accessor for introspection.
+     */
+    readonly hostConfig: HostTriggerConfig;
+    /**
+     * The source that triggered the task execution.
+     */
+    triggerSource: TriggerSource;
     /**
      * Provides access to the underlying SDK context.
      */
@@ -23,6 +56,31 @@ export interface BaseCtx<I> {
      * Function to run other tasks within the context of this task.
      */
     run: HostRunFn;
+    /**
+     * Returns true if triggered via direct run.
+     * When true, ctx.input is the validated host schema type.
+     */
+    isRun: () => this is BaseCtx<I> & {
+        triggerSource: "run";
+    };
+    /**
+     * Returns true if triggered via event.
+     * Optionally accepts an EventDefinition to check for a specific event type.
+     *
+     * @param eventDef Optional event definition to check for specific event
+     */
+    isEvent: <E extends AnyEventDefinition>(eventDef?: E) => this is BaseCtx<I> & {
+        triggerSource: "event";
+        input: E extends AnyEventDefinition ? EventOutput<E> : unknown;
+    };
+    /**
+     * Returns true if triggered via cron schedule.
+     * When true, ctx.input is void/empty.
+     */
+    isCron: () => this is BaseCtx<I> & {
+        triggerSource: "cron";
+        input: never;
+    };
 }
 /**
  * Context type of the run of a standalone task.
@@ -48,4 +106,3 @@ export type WorkflowCtx<T extends WorkflowHost<any>> = BaseCtx<T extends Workflo
  * This is essentially BaseCtx with the input type extracted from the host.
  */
 export type HelperCtx<T extends TaskHost<any> | WorkflowHost<any>> = BaseCtx<T extends TaskHost<infer I> ? I : T extends WorkflowHost<infer I> ? I : never>;
-export {};

package/dist/context/context.js

@@ -1,2 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_MARKER = void 0;
+exports.TASK_MARKER = Symbol("TASK_MARKER");

package/dist/context/index.d.ts

@@ -1 +1 @@
-export type { BaseCtx, TaskCtx, WorkflowCtx, HelperCtx } from "./context";
+export type { BaseCtx, TaskCtx, WorkflowCtx, HelperCtx, TriggerSource, HostTriggerConfig, } from "./context";

package/dist/context/test-narrowing.d.ts

@@ -0,0 +1,5 @@
+import type { BaseCtx } from "./context";
+declare function testNarrowing(ctx: BaseCtx<{
+    userId: string;
+}>): void;
+export { testNarrowing };

package/dist/context/test-narrowing.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testNarrowing = testNarrowing;
+function testNarrowing(ctx) {
+    // Before narrowing
+    const source1 = ctx.triggerSource; // Should be "run" | "event" | "cron"
+    if (ctx.isRun()) {
+        // After narrowing - should be just "run"
+        const source2 = ctx.triggerSource; // Does this compile?
+        console.log(source2);
+    }
+    if (ctx.isCron()) {
+        const source3 = ctx.triggerSource; // Does this compile?
+        console.log(source3);
+    }
+    console.log(source1);
+}

package/dist/context/trigger-guards.d.ts

@@ -0,0 +1,22 @@
+import type { BaseCtx } from "./context";
+/**
+ * Context when triggered via direct run (client.run()).
+ * Input is validated against host's inputSchema.
+ */
+export interface RunCtx<I> extends BaseCtx<I> {
+    triggerSource: "run";
+}
+/**
+ * Context when triggered via event (client.emit()).
+ * Input contains event marker and payload.
+ */
+export interface EventCtx extends BaseCtx<Record<string, unknown>> {
+    triggerSource: "event";
+}
+/**
+ * Context when triggered via cron schedule.
+ * Input is empty/undefined.
+ */
+export interface CronCtx extends BaseCtx<Record<string, never>> {
+    triggerSource: "cron";
+}

package/dist/context/trigger-guards.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });