Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

fix(ts): await async hooks and route their errors through hooksRaise

divit aggarwal7bd9a97f7249
diff --git a/laya-ts/README.md b/laya-ts/README.md
index a64f9be2..61a04705 100644
--- a/laya-ts/README.md
+++ b/laya-ts/README.md
@@ -43,7 +43,9 @@ const out = await agent.predict("charged twice", {
Port of the Python `laya.hooks` lifecycle. A hook is a `(ctx) => void` for `onPredictStart` /
`onPredictEnd`, or an object implementing any subset of `onPredictStart`, `onPredictEnd`,
-`onRoute`, `onLoad`, `onEvict`, `onError`:
+`onRoute`, `onLoad`, `onEvict`, `onError`. A hook may be `async`: it is awaited, in order, before the
+call continues, and a rejection follows `hooksRaise` like a thrown error. `onRoute` runs inside the
+synchronous `route()`, so it is not awaited and a rejection there is only logged:
```ts
const tracer = {
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.ts
index f5bc8e69..927fbec6 100644
--- a/laya-ts/src/agent.ts
+++ b/laya-ts/src/agent.ts
@@ -20,7 +20,7 @@ import {
PredictContext,
aggregateUsage,
composeHooks,
- dispatch,
+ dispatchAsync,
normaliseHooks,
type HookArg,
type PredictHook,
@@ -368,7 +368,7 @@ export class Agent extends HookRegistry {
agent: this,
});
try {
- dispatch(active, "onPredictStart", ctx, { raiseErrors });
+ await dispatchAsync(active, "onPredictStart", ctx, { raiseErrors });
if (ctx.results === null) {
const out: SystemOneResult[] = [];
for (const st of ctx.states) {
@@ -386,7 +386,7 @@ export class Agent extends HookRegistry {
} catch (err) {
ctx.error = err;
try {
- dispatch(active, "onError", ctx, { raiseErrors });
+ await dispatchAsync(active, "onError", ctx, { raiseErrors });
} catch {
// A failing onError hook must not hide the failure that triggered it.
}
@@ -395,7 +395,7 @@ export class Agent extends HookRegistry {
ctx.markElapsed();
if (ctx.results !== null) ctx.usage = aggregateUsage(ctx.results);
try {
- dispatch(active, "onPredictEnd", ctx, { raiseErrors });
+ await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors });
} catch (hookErr) {
// End hooks run on the failure path too; do not let one mask the real error.
if (ctx.error === null) throw hookErr;
diff --git a/laya-ts/src/hooks.ts b/laya-ts/src/hooks.ts
index 8d5428ac..e86830aa 100644
--- a/laya-ts/src/hooks.ts
+++ b/laya-ts/src/hooks.ts
@@ -68,15 +68,15 @@ function now(): number {
/** Optional lifecycle methods. Implement any subset; missing methods are skipped. */
export interface Hook {
- onPredictStart?(ctx: PredictContext): void;
- onPredictEnd?(ctx: PredictContext): void;
+ onPredictStart?(ctx: PredictContext): void | Promise<void>;
+ onPredictEnd?(ctx: PredictContext): void | Promise<void>;
onRoute?(ctx: PredictContext): void;
- onLoad?(ctx: PredictContext): void;
- onEvict?(ctx: PredictContext): void;
- onError?(ctx: PredictContext): void;
+ onLoad?(ctx: PredictContext): void | Promise<void>;
+ onEvict?(ctx: PredictContext): void | Promise<void>;
+ onError?(ctx: PredictContext): void | Promise<void>;
}
-export type PredictHook = (ctx: PredictContext) => void;
+export type PredictHook = (ctx: PredictContext) => void | Promise<void>;
export type HookArg = Hook | Hook[] | null | undefined;
export type PredictHookArg = PredictHook | PredictHook[] | null | undefined;
@@ -295,12 +295,21 @@ export function aggregateUsage(results: Record<string, unknown>[]): Record<strin
return { input_tokens: total("input_tokens"), output_tokens: total("output_tokens") };
}
+function reportHookFailure(hook: Hook, event: HookEvent, err: unknown): void {
+ const name = (hook as object)?.constructor?.name ?? "hook";
+ console.warn(`laya: hook ${name}.${event} failed: ${String(err)}`);
+}
+
/**
* Call `event` on every hook that implements it.
*
* `raiseErrors=false` warns and continues, for hooks (telemetry) that must not fail a
* request. Python also takes a `lock` to serialise dispatch for hooks that are not safe to
- * run concurrently; JS hooks run synchronously on one thread, so there is nothing to lock.
+ * run concurrently; JS hooks run on one thread, so there is nothing to lock.
+ *
+ * It does not wait for a hook that returns a promise, so it is for callers that cannot wait,
+ * such as the synchronous `Router.route`; a rejection can then only be reported as a warning.
+ * `dispatchAsync` waits and applies `raiseErrors` to it.
*/
export function dispatch(
hooks: Hook[],
@@ -313,11 +322,34 @@ export function dispatch(
const method = hook?.[event];
if (typeof method !== "function") continue;
try {
- method.call(hook, ctx);
+ const result: unknown = method.call(hook, ctx);
+ if (typeof (result as PromiseLike<unknown> | null)?.then === "function") {
+ Promise.resolve(result).catch((err) => reportHookFailure(hook, event, err));
+ }
+ } catch (err) {
+ if (raiseErrors) throw err;
+ reportHookFailure(hook, event, err);
+ }
+ }
+}
+
+/** Like `dispatch`, but waits for each hook that returns a promise before the next runs, and a
+ * rejection follows `raiseErrors` the way a thrown error does. */
+export async function dispatchAsync(
+ hooks: Hook[],
+ event: HookEvent,
+ ctx: PredictContext,
+ opts: { raiseErrors?: boolean } = {},
+): Promise<void> {
+ const raiseErrors = opts.raiseErrors ?? true;
+ for (const hook of hooks) {
+ const method = hook?.[event];
+ if (typeof method !== "function") continue;
+ try {
+ await method.call(hook, ctx);
} catch (err) {
if (raiseErrors) throw err;
- const name = (hook as object)?.constructor?.name ?? "hook";
- console.warn(`laya: hook ${name}.${event} failed: ${String(err)}`);
+ reportHookFailure(hook, event, err);
}
}
}
diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.ts
index 0f09b078..3210c1fa 100644
--- a/laya-ts/src/router.ts
+++ b/laya-ts/src/router.ts
@@ -7,6 +7,7 @@ import {
aggregateUsage,
composeHooks,
dispatch,
+ dispatchAsync,
normaliseHooks,
type HookArg,
type PredictHook,
@@ -244,14 +245,14 @@ export class Router extends HookRegistry {
const evicted = this._evict();
// Lifecycle hooks fire after the maps settle, so a hook can safely call the Router.
for (const victim of evicted) {
- dispatch(
+ await dispatchAsync(
composeHooks(this.hooks),
"onEvict",
new PredictContext({ states: [], questions: {}, model: victim, router: this }),
{ raiseErrors: this.hooksRaise },
);
}
- dispatch(
+ await dispatchAsync(
composeHooks(this.hooks),
"onLoad",
new PredictContext({ states: [], questions: {}, model: key, agent, router: this }),
@@ -494,7 +495,7 @@ export class Router extends HookRegistry {
router: this,
});
try {
- dispatch(active, "onPredictStart", ctx, { raiseErrors });
+ await dispatchAsync(active, "onPredictStart", ctx, { raiseErrors });
if (ctx.results === null) {
// Python parity (router.py predict): the request's language also shapes the answer
// distribution through the agent's lang_temperatures. An explicit lang wins;
@@ -523,7 +524,7 @@ export class Router extends HookRegistry {
} catch (err) {
ctx.error = err;
try {
- dispatch(active, "onError", ctx, { raiseErrors });
+ await dispatchAsync(active, "onError", ctx, { raiseErrors });
} catch {
// A failing onError hook must not hide the failure that triggered it.
}
@@ -532,7 +533,7 @@ export class Router extends HookRegistry {
ctx.markElapsed();
if (ctx.results !== null) ctx.usage = aggregateUsage(ctx.results);
try {
- dispatch(active, "onPredictEnd", ctx, { raiseErrors });
+ await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors });
} catch (hookErr) {
// End hooks run on the failure path too; do not let one mask the real error.
if (ctx.error === null) throw hookErr;
diff --git a/laya-ts/tests/hooks.test.ts b/laya-ts/tests/hooks.test.ts
index 6021a58c..f872f084 100644
--- a/laya-ts/tests/hooks.test.ts
+++ b/laya-ts/tests/hooks.test.ts
@@ -113,6 +113,59 @@ describe("agent hooks", () => {
expect(r["stamped"]).toBe(true);
});
+ it("awaits an async end hook, so it can rewrite the results after an await", async () => {
+ const agent = makeAgent([], {
+ async onPredictEnd(ctx) {
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ for (const r of ctx.results ?? []) r["stamped"] = true;
+ },
+ });
+ const r = (await agent.systemOne("hi", QUESTIONS)) as Record<string, unknown>;
+ expect(r["stamped"]).toBe(true);
+ });
+
+ it("an async start hook may skip inference after an await", async () => {
+ const seen: string[] = [];
+ const cached = { model: "cache", answers: {}, usage: { input_tokens: 0, output_tokens: 0 } };
+ const agent = makeAgent(seen, {
+ async onPredictStart(ctx) {
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ ctx.skip([cached]);
+ },
+ });
+ expect(await agent.systemOne("hi", QUESTIONS)).toEqual(cached);
+ expect(seen).toEqual([]);
+ });
+
+ it("waits for each async hook before the next one runs", async () => {
+ const order: string[] = [];
+ const agent = makeAgent([], {
+ hooks: [{
+ async onPredictStart() {
+ order.push("first:begin");
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ order.push("first:end");
+ },
+ }],
+ });
+ await agent.systemOne("hi", QUESTIONS, { onPredictStart: () => void order.push("second") });
+ expect(order).toEqual(["first:begin", "first:end", "second"]);
+ });
+
+ it("a rejecting async hook follows hooksRaise: raised by default, a warning when false", async () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ try {
+ const failing = { async onPredictEnd() { await Promise.resolve(); throw new Error("metrics backend down"); } };
+ await expect(makeAgent([], { hooks: [failing] }).systemOne("hi", QUESTIONS)).rejects.toThrow("metrics backend down");
+ const r = await makeAgent([], { hooks: [failing], hooksRaise: false }).systemOne("hi", QUESTIONS);
+ expect(r.answers).toHaveProperty("q");
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining("metrics backend down"));
+ await new Promise((resolve) => setTimeout(resolve, 10)); // an unhandled rejection would surface here
+ } finally {
+ warn.mockRestore();
+ }
+ });
+
it("per-call hooks run after installed hooks", async () => {
const order: string[] = [];
const agent = makeAgent([], { hooks: [{ onPredictStart: () => order.push("installed") }] });
@@ -226,6 +279,44 @@ describe("router hooks", () => {
expect(r.routing.model).toBe("english");
});
+ it("awaits async Router hooks, and a rejecting onRoute hook does not become an unhandled rejection", async () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ try {
+ const { router } = makeRouter({
+ hooksRaise: false,
+ hooks: [{
+ async onPredictEnd(ctx: PredictContext) {
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ for (const r of ctx.results ?? []) r["stamped"] = true;
+ },
+ async onRoute() { await Promise.resolve(); throw new Error("route hook down"); },
+ }],
+ });
+ const r = (await router.predict("plain english text", QUESTIONS)) as unknown as Record<string, unknown>;
+ expect(r["stamped"]).toBe(true);
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining("route hook down"));
+ await new Promise((resolve) => setTimeout(resolve, 10)); // an unhandled rejection would surface here
+ } finally {
+ warn.mockRestore();
+ }
+ });
+
+ it("an async onLoad hook may call router.load for the model being loaded without deadlocking", async () => {
+ const seen: string[] = [];
+ const { router } = makeRouter({
+ hooks: [{
+ async onLoad(ctx: PredictContext) {
+ seen.push("begin");
+ await router.load(ctx.model as string);
+ seen.push("end");
+ },
+ }],
+ });
+ const timeout = new Promise((resolve) => setTimeout(() => resolve("deadlock"), 500));
+ expect(await Promise.race([router.load("english"), timeout])).not.toBe("deadlock");
+ expect(seen).toEqual(["begin", "end"]);
+ });
+
it("a cache hit still gets a routing key, without overwriting an existing one", async () => {
const { router, calls } = makeRouter({
onPredictStart(ctx: PredictContext) {