@telorun/sdk 0.10.0 → 0.12.0

package/LICENSE

@@ -1,6 +1,6 @@
 # SUSTAINABLE USE LICENSE (Fair-code)
 
-Copyright (c) 2026 DiglyAI
+Copyright (c) 2026 CodeNet Sp. z o.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
 
@@ -14,4 +14,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
 
-For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact DiglyAI.
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -8,10 +8,6 @@ The Node.js SDK provides the authoring surface for Telo modules. It defines the
 - **Context types** for accessing the kernel, registry, and events.
 - **Shared primitives** used by Telo modules and tooling.
 
-## Status
-
-Early prototype. APIs and contracts are still evolving. The API surface - including YAML shapes - may change at any time without notice.
-
 ## When to Use It
 
 Use the SDK when building or extending Telo modules. It is not the kernel itself; it is the contract layer that keeps module behavior consistent and predictable.
@@ -69,9 +65,3 @@ throws:
 ```
 
 `inherit` is driven by the analyzer's dataflow pass over `x-telo-step-context` arrays; future composers opt in by declaring both the annotation and `inherit: true`. See [modules/run/docs/structured-errors.md](../../modules/run/docs/structured-errors.md) for the end-to-end flow.
-
-## Related Docs
-
-- Kernel overview: [kernel/README.md](../../kernel/README.md)
-- Built‑in modules: [modules/](../../modules/)
-- SDKs index: [sdk/README.md](../README.md)

package/dist/capabilities/provider.d.ts

@@ -1,4 +1,4 @@
-export interface Provider {
-    init(): Promise<void>;
+export interface Provider<TOutput = unknown> {
+    provide(): Promise<TOutput>;
 }
 //# sourceMappingURL=provider.d.ts.map

package/dist/capabilities/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/capabilities/provider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/capabilities/provider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ,CAAC,OAAO,GAAG,OAAO;IACzC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7B"}

package/dist/capability-definition.d.ts

@@ -0,0 +1,8 @@
+import type { CapabilityDefinition } from "./types.js";
+/**
+ * Factory that wires the declarative `expand` config on a CapabilityDefinition
+ * into the `onManifest` and `onInvoke` lifecycle hooks. The kernel only ever
+ * calls these hooks — it has no knowledge of the `expand` config.
+ */
+export declare function createCapability(def: CapabilityDefinition): CapabilityDefinition;
+//# sourceMappingURL=capability-definition.d.ts.map

package/dist/capability-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-definition.d.ts","sourceRoot":"","sources":["../src/capability-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,oBAAoB,GAAG,oBAAoB,CAwBhF"}

package/dist/capability-definition.js

@@ -0,0 +1,21 @@
+/**
+ * Factory that wires the declarative `expand` config on a CapabilityDefinition
+ * into the `onManifest` and `onInvoke` lifecycle hooks. The kernel only ever
+ * calls these hooks — it has no knowledge of the `expand` config.
+ */
+export function createCapability(def) {
+    const compile = def.expand?.compile ?? [];
+    const runtime = def.expand?.runtime ?? [];
+    return {
+        ...def,
+        onManifest: compile.length
+            ? (manifest, ctx) => ctx.expandPaths(manifest, compile, runtime)
+            : def.onManifest,
+        onInvoke: runtime.length
+            ? async (instance, inputs, ctx) => {
+                const expanded = ctx.moduleContext.expandPaths(inputs, runtime);
+                return instance.invoke(expanded);
+            }
+            : def.onInvoke,
+    };
+}

package/dist/cel-environment.d.ts

@@ -0,0 +1,3 @@
+import { Environment } from "@marcbachmann/cel-js";
+export declare const celEnvironment: Environment;
+//# sourceMappingURL=cel-environment.d.ts.map

package/dist/cel-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,eAAO,MAAM,cAAc,aAWvB,CAAC"}

package/dist/cel-environment.js

@@ -0,0 +1,13 @@
+import { Environment } from "@marcbachmann/cel-js";
+export const celEnvironment = new Environment({ unlistedVariablesAreDyn: true })
+    .registerFunction("join(list, string): string", (list, sep) => list.map(String).join(sep))
+    .registerFunction("keys(map): list", (map) => {
+    if (map instanceof Map)
+        return [...map.keys()];
+    return Object.keys(map);
+})
+    .registerFunction("values(map): list", (map) => {
+    if (map instanceof Map)
+        return [...map.values()];
+    return Object.values(map);
+});

package/dist/execution-context.d.ts

@@ -0,0 +1,13 @@
+import { EvaluationContext } from "./evaluation-context.js";
+import { ModuleContext } from "./module-context.js";
+/**
+ * The ephemeral, per-trigger context layer. Merges a ModuleContext with
+ * arbitrary execution-time properties (e.g. { request, inputs } for HTTP;
+ * any shape is valid — determined by the trigger type).
+ *
+ * Execution props overlay the module namespaces on key conflict.
+ */
+export declare class ExecutionContext extends EvaluationContext {
+    constructor(moduleCtx: ModuleContext, execProps: Record<string, unknown>);
+}
+//# sourceMappingURL=execution-context.d.ts.map

package/dist/execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.d.ts","sourceRoot":"","sources":["../src/execution-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;gBACzC,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASzE"}

package/dist/execution-context.js

@@ -0,0 +1,13 @@
+import { EvaluationContext } from "./evaluation-context.js";
+/**
+ * The ephemeral, per-trigger context layer. Merges a ModuleContext with
+ * arbitrary execution-time properties (e.g. { request, inputs } for HTTP;
+ * any shape is valid — determined by the trigger type).
+ *
+ * Execution props overlay the module namespaces on key conflict.
+ */
+export class ExecutionContext extends EvaluationContext {
+    constructor(moduleCtx, execProps) {
+        super(moduleCtx.source, Object.assign(Object.create(null), moduleCtx.context, execProps), moduleCtx.createInstance, moduleCtx.secretValues, moduleCtx.emit);
+    }
+}

package/dist/resource-instance.d.ts

@@ -1,7 +1,8 @@
 import type { Invocable } from "./capabilities/invokable.js";
+import type { Provider } from "./capabilities/provider.js";
 import type { Runnable } from "./capabilities/runnable.js";
 import type { ResourceContext } from "./resource-context.js";
-export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<Invocable<TInput, TOutput>> & Partial<Runnable> & {
+export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<Invocable<TInput, TOutput>> & Partial<Runnable> & Partial<Provider<TOutput>> & {
     init?(ctx?: ResourceContext): Promise<void>;
     teardown?(): void | Promise<void>;
     snapshot?(): Record<string, any> | Promise<Record<string, any>>;

package/dist/resource-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GAAG;IAClB,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CACjE,CAAC"}
+{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CACjE,CAAC"}

package/dist/stream.d.ts

@@ -11,6 +11,18 @@
  * resulting value a real-class constructor that cel-js can register and
  * recognize, so `${{ steps.X.result.output }}` evaluations pass through cleanly.
  *
+ * Singleton across sdk copies: cel-js identifies registered types by
+ * constructor identity (`v.constructor === RegisteredCtor`). The kernel and
+ * any npm-loaded controller can — and routinely do — resolve `@telorun/sdk`
+ * to different installs (workspace vs `.telo/npm/<hash>/...`), so two `Stream`
+ * classes with the same shape but different identity would silently break
+ * stream-typed CEL evaluations with "Unsupported type: Stream". The first
+ * `@telorun/sdk` copy to load registers its `Stream` class on `globalThis`
+ * under a stable `Symbol.for("@telorun/sdk:Stream")` key; later copies discard
+ * their local declaration at export time and re-export the registered one.
+ * Every Stream value in the process shares one constructor regardless of
+ * install topology — no build artifact or `file:` symlink required.
+ *
  * The companion analyzer registers `Stream` as a CEL object type with no
  * fields — terminal access (passing the value through) succeeds, member access
  * (`result.output.text`, `result.output[0]`) raises a CEL error at runtime,
@@ -24,9 +36,14 @@
  * patterns work without unwrapping. Internally it forwards `Symbol.asyncIterator`
  * to the underlying iterable.
  */
-export declare class Stream<T = unknown> implements AsyncIterable<T> {
-    private readonly source;
-    constructor(source: AsyncIterable<T>);
-    [Symbol.asyncIterator](): AsyncIterator<T>;
+interface Stream<T = unknown> extends AsyncIterable<T> {
 }
+declare const LocalStream: {
+    new <T = unknown>(source: AsyncIterable<T>): {
+        "__#private@#source": AsyncIterable<T>;
+        [Symbol.asyncIterator](): AsyncIterator<T>;
+    };
+};
+declare const Stream: typeof LocalStream;
+export { Stream };
 //# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,MAAM,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAErD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;CAG3C"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,UAAU,MAAM,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAG;AAOzD,QAAA,MAAM,WAAW;SAAgB,CAAC,oBAMZ,aAAa,CAAC,CAAC,CAAC;8BAF3B,aAAa,CAAC,CAAC,CAAC;kCAMC,aAAa,CAAC,CAAC,CAAC;;CAG3C,CAAC;AAUF,QAAA,MAAM,MAAM,EAAE,OAAO,WAA0D,CAAC;AAMhF,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/stream.js

@@ -11,6 +11,18 @@
  * resulting value a real-class constructor that cel-js can register and
  * recognize, so `${{ steps.X.result.output }}` evaluations pass through cleanly.
  *
+ * Singleton across sdk copies: cel-js identifies registered types by
+ * constructor identity (`v.constructor === RegisteredCtor`). The kernel and
+ * any npm-loaded controller can — and routinely do — resolve `@telorun/sdk`
+ * to different installs (workspace vs `.telo/npm/<hash>/...`), so two `Stream`
+ * classes with the same shape but different identity would silently break
+ * stream-typed CEL evaluations with "Unsupported type: Stream". The first
+ * `@telorun/sdk` copy to load registers its `Stream` class on `globalThis`
+ * under a stable `Symbol.for("@telorun/sdk:Stream")` key; later copies discard
+ * their local declaration at export time and re-export the registered one.
+ * Every Stream value in the process shares one constructor regardless of
+ * install topology — no build artifact or `file:` symlink required.
+ *
  * The companion analyzer registers `Stream` as a CEL object type with no
  * fields — terminal access (passing the value through) succeeds, member access
  * (`result.output.text`, `result.output[0]`) raises a CEL error at runtime,
@@ -24,12 +36,34 @@
  * patterns work without unwrapping. Internally it forwards `Symbol.asyncIterator`
  * to the underlying iterable.
  */
-export class Stream {
-    source;
+// Value binding (private): the class declaration that supplies the runtime
+// implementation. Written as a named class expression so `.name === "Stream"`
+// — debuggers, stack traces, and `Object.prototype.toString` all see "Stream",
+// not the const name. The inner `Stream` identifier is only visible inside
+// the class body (for self-reference); it does not shadow the outer interface.
+const LocalStream = class Stream {
+    // ECMAScript private field rather than TS `private readonly` — the latter
+    // shows up in the inferred type signature, which TS then refuses to export
+    // through an anonymous class expression (TS4094).
+    #source;
     constructor(source) {
-        this.source = source;
+        this.#source = source;
     }
     [Symbol.asyncIterator]() {
-        return this.source[Symbol.asyncIterator]();
+        return this.#source[Symbol.asyncIterator]();
     }
-}
+};
+const STREAM_KEY = Symbol.for("@telorun/sdk:Stream");
+const globalSlot = globalThis;
+if (!(STREAM_KEY in globalSlot))
+    globalSlot[STREAM_KEY] = LocalStream;
+// The exported value: whichever Stream class won the globalThis race (first
+// sdk copy to import this module). Later copies discard their `LocalStream`
+// at export time and route through the winner — keeping constructor identity
+// stable across the kernel/controller realm boundary.
+const Stream = globalSlot[STREAM_KEY];
+// `export { Stream }` re-exports the value binding (the const above) and the
+// type binding (the interface above) under the same name — TypeScript treats
+// value/type as separate namespaces, so a consumer's `import { Stream }`
+// receives both `new Stream(...)` and `Stream<T>`.
+export { Stream };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/capabilities/provider.ts

@@ -1,3 +1,3 @@
-export interface Provider {
-  init(): Promise<void>;
+export interface Provider<TOutput = unknown> {
+  provide(): Promise<TOutput>;
 }

package/src/resource-instance.ts

@@ -1,11 +1,13 @@
 import type { Invocable } from "./capabilities/invokable.js";
+import type { Provider } from "./capabilities/provider.js";
 import type { Runnable } from "./capabilities/runnable.js";
 import type { ResourceContext } from "./resource-context.js";
 
 export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<
   Invocable<TInput, TOutput>
 > &
-  Partial<Runnable> & {
+  Partial<Runnable> &
+  Partial<Provider<TOutput>> & {
     init?(ctx?: ResourceContext): Promise<void>;
     teardown?(): void | Promise<void>;
     snapshot?(): Record<string, any> | Promise<Record<string, any>>;

package/src/stream.ts

@@ -11,6 +11,18 @@
  * resulting value a real-class constructor that cel-js can register and
  * recognize, so `${{ steps.X.result.output }}` evaluations pass through cleanly.
  *
+ * Singleton across sdk copies: cel-js identifies registered types by
+ * constructor identity (`v.constructor === RegisteredCtor`). The kernel and
+ * any npm-loaded controller can — and routinely do — resolve `@telorun/sdk`
+ * to different installs (workspace vs `.telo/npm/<hash>/...`), so two `Stream`
+ * classes with the same shape but different identity would silently break
+ * stream-typed CEL evaluations with "Unsupported type: Stream". The first
+ * `@telorun/sdk` copy to load registers its `Stream` class on `globalThis`
+ * under a stable `Symbol.for("@telorun/sdk:Stream")` key; later copies discard
+ * their local declaration at export time and re-export the registered one.
+ * Every Stream value in the process shares one constructor regardless of
+ * install topology — no build artifact or `file:` symlink required.
+ *
  * The companion analyzer registers `Stream` as a CEL object type with no
  * fields — terminal access (passing the value through) succeeds, member access
  * (`result.output.text`, `result.output[0]`) raises a CEL error at runtime,
@@ -24,10 +36,43 @@
  * patterns work without unwrapping. Internally it forwards `Symbol.asyncIterator`
  * to the underlying iterable.
  */
-export class Stream<T = unknown> implements AsyncIterable<T> {
-  constructor(private readonly source: AsyncIterable<T>) {}
+
+// Type binding: `Stream<T>` as written by consumers (`let s: Stream<number>`)
+// resolves to this interface. The class below also conforms to it.
+interface Stream<T = unknown> extends AsyncIterable<T> {}
+
+// Value binding (private): the class declaration that supplies the runtime
+// implementation. Written as a named class expression so `.name === "Stream"`
+// — debuggers, stack traces, and `Object.prototype.toString` all see "Stream",
+// not the const name. The inner `Stream` identifier is only visible inside
+// the class body (for self-reference); it does not shadow the outer interface.
+const LocalStream = class Stream<T = unknown> implements AsyncIterable<T> {
+  // ECMAScript private field rather than TS `private readonly` — the latter
+  // shows up in the inferred type signature, which TS then refuses to export
+  // through an anonymous class expression (TS4094).
+  #source: AsyncIterable<T>;
+
+  constructor(source: AsyncIterable<T>) {
+    this.#source = source;
+  }
 
   [Symbol.asyncIterator](): AsyncIterator<T> {
-    return this.source[Symbol.asyncIterator]();
+    return this.#source[Symbol.asyncIterator]();
   }
-}
+};
+
+const STREAM_KEY = Symbol.for("@telorun/sdk:Stream");
+const globalSlot = globalThis as Record<symbol, unknown>;
+if (!(STREAM_KEY in globalSlot)) globalSlot[STREAM_KEY] = LocalStream;
+
+// The exported value: whichever Stream class won the globalThis race (first
+// sdk copy to import this module). Later copies discard their `LocalStream`
+// at export time and route through the winner — keeping constructor identity
+// stable across the kernel/controller realm boundary.
+const Stream: typeof LocalStream = globalSlot[STREAM_KEY] as typeof LocalStream;
+
+// `export { Stream }` re-exports the value binding (the const above) and the
+// type binding (the interface above) under the same name — TypeScript treats
+// value/type as separate namespaces, so a consumer's `import { Stream }`
+// receives both `new Stream(...)` and `Stream<T>`.
+export { Stream };