@telorun/sdk 0.13.0 → 0.16.0

package/package.json

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

package/src/evaluation-context.ts

@@ -32,12 +32,14 @@ export type InstanceFactory = (
  * fields of the resource config before the controller sees them in init().
  *
  * @param resource  The resource manifest whose config fields may be mutated in-place.
- * @param getInstance  Looks up an already-initialized instance by resource name.
+ * @param getInstance  Looks up an already-initialized instance by resource name. With a
+ *                     non-`Self` `alias`, resolves a cross-module reference into that
+ *                     import's published exported instances instead of the local context.
  *                     Returns undefined when the named resource is not yet initialized.
  */
 export type PreInitHook = (
   resource: ResourceManifest,
-  getInstance: (name: string) => ResourceInstance | undefined,
+  getInstance: (name: string, alias?: string) => ResourceInstance | undefined,
 ) => void;
 
 /** Canonical key for a resource instance: "<module>.<kind>.<name>" */

package/src/invoke-step.ts

@@ -57,6 +57,10 @@ export interface InvokeStepContext {
     instance: ResourceInstance,
     inputs: TInputs,
   ): Promise<any>;
+  /** Resolve a cross-module exported instance (`!ref Alias.name`) to its live instance.
+   *  Optional — providers that pre-resolve cross-module refs before reaching the leaf
+   *  (e.g. the boot-target runner) may omit it. */
+  resolveImportedInstance?(alias: string, name: string): ResourceInstance | undefined;
 }
 
 /**
@@ -93,7 +97,18 @@ export async function executeInvokeStep(
     result = await (raw as Invocable).invoke(inputs);
   } else {
     const ref = raw as KindRef<Invocable>;
-    if (state.scope) {
+    if (ref.alias && ref.alias !== "Self") {
+      // Cross-module exported instance: resolve into the owning import's context and invoke
+      // the live instance directly — works whether or not the step runs inside a `with:`
+      // scope (a plain `steps` list has no scope, so name lookup in the local context fails).
+      const instance = ctx.resolveImportedInstance?.(ref.alias, ref.name);
+      if (!instance) {
+        throw new Error(
+          `Cross-module reference '${ref.alias}.${ref.name}' did not resolve to an exported instance.`,
+        );
+      }
+      result = await ctx.invokeResolved(ref.kind, ref.name, instance, inputs);
+    } else if (state.scope) {
       const instance = state.scope.getInstance(ref.name) as unknown as ResourceInstance;
       result = await ctx.invokeResolved(ref.kind, ref.name, instance, inputs);
     } else {

package/src/module-context.ts

@@ -2,6 +2,7 @@ import type { Invocable } from "./capabilities/invokable.js";
 import type { ControllerPolicy } from "./controller-policy.js";
 import type { EvaluationContext } from "./evaluation-context.js";
 import type { BootTarget } from "./invoke-step.js";
+import type { ResourceInstance } from "./resource-instance.js";
 
 /**
  * Public contract for a persistent, module-scoped context.
@@ -29,6 +30,12 @@ export interface ModuleContext extends EvaluationContext {
   getControllerPolicy(): ControllerPolicy | undefined;
 
   registerImport(alias: string, targetModule: string, kinds: string[]): void;
+  /** Resolve a cross-module exported-instance reference `Alias.name` to its `{kind, name}`
+   *  ref (canonical kind), gated by the import's `exports.resources`. Returns undefined when
+   *  the alias is unknown, the name isn't exported, or the import hasn't initialized yet. */
+  resolveImportedRef(alias: string, name: string): { kind: string; name: string } | undefined;
+  /** Resolve a cross-module exported-instance reference `Alias.name` to its live instance. */
+  resolveImportedInstance(alias: string, name: string): ResourceInstance | undefined;
   getInstance(name: string): unknown;
   getInvocable<TInput = Record<string, any>, TOutput = any>(
     name: string,

package/src/ref.ts

@@ -2,10 +2,16 @@ import type { ResourceInstance } from "./resource-instance.js";
 
 /** Marker type for x-telo-ref fields. Carries the live instance type at the TypeScript level;
  *  at runtime this field holds `{ kind, name }` until Phase 5 injection replaces it.
- *  T is a phantom type — any capability interface (Invocable, Runnable, …) or ResourceInstance. */
+ *  T is a phantom type — any capability interface (Invocable, Runnable, …) or ResourceInstance.
+ *
+ *  `alias` is set only for cross-module references resolved from `!ref Alias.name` against an
+ *  imported library's `exports.resources`. It names the import alias whose child context owns
+ *  the target instance, so Phase 5 injection can resolve into that context rather than the
+ *  referencing resource's own. Absent (or `"Self"`) means a local reference. */
 export interface KindRef<T = ResourceInstance> {
   readonly kind: string;
   readonly name: string;
+  readonly alias?: string;
   readonly __type?: T;
 }
 
@@ -17,11 +23,13 @@ export interface ScopeRef {
 
 /** Gives a controller access to the resources initialized within a scope. */
 export interface ScopeContext {
-  /** Returns the initialized instance for the given name.
+  /** Returns the initialized instance for the given name. With a non-`Self` `alias`,
+   *  resolves a cross-module exported instance (`!ref Alias.name`) into the owning
+   *  import's child context instead of the scope-local / outer resources.
    *  Throws synchronously if the name was not declared in the scope —
    *  this is always a programming error; all scope members are statically
    *  validated in Phase 3 before the kernel ever reaches runtime. */
-  getInstance(name: string): ResourceInstance;
+  getInstance(name: string, alias?: string): ResourceInstance;
 }
 
 /** Returned by Phase 5 injection in place of an x-telo-scope manifest array.

package/dist/capability-definition.d.ts

@@ -1,8 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,21 +0,0 @@
-/**
- * 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

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

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

@@ -1 +0,0 @@
-{"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

@@ -1,13 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,13 +0,0 @@
-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);
-    }
-}