@loopstack/observability-examples 0.1.0 → 0.1.1

package/dist/workflows/quota/quota-example.workflow.js

@@ -14,7 +14,7 @@ const zod_1 = require("zod");
 const common_1 = require("@loopstack/common");
 const quota_1 = require("@loopstack/quota");
 const QuotaExampleArgsSchema = zod_1.z.object({
-    quotaType: zod_1.z.string().default('ai_generate_text'),
+    quotaType: zod_1.z.string().default('llm-cost'),
     reportAmount: zod_1.z.number().default(1000),
 });
 let QuotaExampleWorkflow = class QuotaExampleWorkflow extends common_1.BaseWorkflow {

package/dist/workflows/quota/quota-example.workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"quota-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/quota/quota-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,8CAAyF;AAEzF,4CAAsD;AAQtD,MAAM,sBAAsB,GAAG,OAAC,CAAC,MAAM,CAAC;IACtC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC;IACjD,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACvC,CAAC,CAAC;AAUI,IAAM,oBAAoB,GAA1B,MAAM,oBAAqB,SAAQ,qBAA8B;IACzC;IAA7B,YAA6B,WAA+B;QAC1D,KAAK,EAAE,CAAC;QADmB,gBAAW,GAAX,WAAW,CAAoB;IAE5D,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU,CAAC,MAAyB,EAAE,GAAiC;QAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,IAAI,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAEhG,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,gBAAgB;gBAChB,EAAE;gBACF,gBAAgB,OAAO,IAAI;gBAC3B,aAAa,MAAM,CAAC,IAAI,IAAI;gBAC5B,cAAc,MAAM,CAAC,KAAK,IAAI;aAC/B,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;QAEH,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IAGK,AAAN,KAAK,CAAC,WAAW,CAAC,MAAyB,EAAE,GAAiC;QAC5E,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;gBAC9C,QAAQ,EAAE,0DAA0D;aACrE,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEpG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,aAAa;gBACb,EAAE;gBACF,aAAa,GAAG,CAAC,IAAI,CAAC,YAAY,iBAAiB,GAAG,CAAC,IAAI,CAAC,SAAS,yBAAyB;aAC/F,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA1CY,oDAAoB;AAMzB;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC;;;;sDAgBnC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;uDAkBhD;+BAzCU,oBAAoB;IANhC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,+BAA+B;QACtC,WAAW,EACT,0LAA0L;QAC5L,MAAM,EAAE,sBAAsB;KAC/B,CAAC;qCAE0C,0BAAkB;GADjD,oBAAoB,CA0ChC"}
+{"version":3,"file":"quota-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/quota/quota-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,8CAAyF;AAEzF,4CAAsD;AAQtD,MAAM,sBAAsB,GAAG,OAAC,CAAC,MAAM,CAAC;IACtC,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC;IACzC,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACvC,CAAC,CAAC;AAUI,IAAM,oBAAoB,GAA1B,MAAM,oBAAqB,SAAQ,qBAA8B;IACzC;IAA7B,YAA6B,WAA+B;QAC1D,KAAK,EAAE,CAAC;QADmB,gBAAW,GAAX,WAAW,CAAoB;IAE5D,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU,CAAC,MAAyB,EAAE,GAAiC;QAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,IAAI,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAEhG,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,gBAAgB;gBAChB,EAAE;gBACF,gBAAgB,OAAO,IAAI;gBAC3B,aAAa,MAAM,CAAC,IAAI,IAAI;gBAC5B,cAAc,MAAM,CAAC,KAAK,IAAI;aAC/B,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;QAEH,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IAGK,AAAN,KAAK,CAAC,WAAW,CAAC,MAAyB,EAAE,GAAiC;QAC5E,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;gBAC9C,QAAQ,EAAE,0DAA0D;aACrE,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEpG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,aAAa;gBACb,EAAE;gBACF,aAAa,GAAG,CAAC,IAAI,CAAC,YAAY,iBAAiB,GAAG,CAAC,IAAI,CAAC,SAAS,yBAAyB;aAC/F,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA1CY,oDAAoB;AAMzB;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC;;;;sDAgBnC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;uDAkBhD;+BAzCU,oBAAoB;IANhC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,+BAA+B;QACtC,WAAW,EACT,0LAA0L;QAC5L,MAAM,EAAE,sBAAsB;KAC/B,CAAC;qCAE0C,0BAAkB;GADjD,oBAAoB,CA0ChC"}

package/dist/workflows/tracing/interceptors/tracing.interceptor.d.ts

@@ -0,0 +1,10 @@
+import { ToolEnvelope, ToolExecutionContext, ToolInterceptor } from '@loopstack/common';
+import { ToolTraceService } from '../services/tool-trace.service';
+export declare class TracingInterceptor implements ToolInterceptor {
+    private readonly traceStore;
+    private readonly logger;
+    constructor(traceStore: ToolTraceService);
+    intercept(context: ToolExecutionContext, next: () => Promise<ToolEnvelope>): Promise<ToolEnvelope>;
+    private trace;
+}
+//# sourceMappingURL=tracing.interceptor.d.ts.map

package/dist/workflows/tracing/interceptors/tracing.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.interceptor.d.ts","sourceRoot":"","sources":["../../../../src/workflows/tracing/interceptors/tracing.interceptor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAsB,MAAM,mBAAmB,CAAC;AAC5G,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,qBACa,kBAAmB,YAAW,eAAe;IAG5C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAEjC,UAAU,EAAE,gBAAgB;IAEnD,SAAS,CAAC,OAAO,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IAexG,OAAO,CAAC,KAAK;CAKd"}

package/dist/workflows/tracing/interceptors/tracing.interceptor.js

@@ -0,0 +1,48 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var TracingInterceptor_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracingInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const common_2 = require("@loopstack/common");
+const tool_trace_service_1 = require("../services/tool-trace.service");
+let TracingInterceptor = TracingInterceptor_1 = class TracingInterceptor {
+    traceStore;
+    logger = new common_1.Logger(TracingInterceptor_1.name);
+    constructor(traceStore) {
+        this.traceStore = traceStore;
+    }
+    async intercept(context, next) {
+        const toolName = context.tool.constructor.name;
+        const workflowId = context.runContext.workflowId;
+        const startTime = performance.now();
+        try {
+            const result = await next();
+            this.trace(toolName, workflowId, startTime, true);
+            return result;
+        }
+        catch (error) {
+            this.trace(toolName, workflowId, startTime, false);
+            throw error;
+        }
+    }
+    trace(toolName, workflowId, startTime, success) {
+        const durationMs = Math.round(performance.now() - startTime);
+        this.traceStore.record({ toolName, workflowId, durationMs, success });
+        this.logger.log(`${toolName} — ${success ? 'ok' : 'failed'} in ${durationMs}ms (workflow ${workflowId})`);
+    }
+};
+exports.TracingInterceptor = TracingInterceptor;
+exports.TracingInterceptor = TracingInterceptor = TracingInterceptor_1 = __decorate([
+    (0, common_2.UseToolInterceptor)({ priority: 10 }),
+    __metadata("design:paramtypes", [tool_trace_service_1.ToolTraceService])
+], TracingInterceptor);
+//# sourceMappingURL=tracing.interceptor.js.map

package/dist/workflows/tracing/interceptors/tracing.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.interceptor.js","sourceRoot":"","sources":["../../../../src/workflows/tracing/interceptors/tracing.interceptor.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,2CAAwC;AACxC,8CAA4G;AAC5G,uEAAkE;AAG3D,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAGA;IAFZ,MAAM,GAAG,IAAI,eAAM,CAAC,oBAAkB,CAAC,IAAI,CAAC,CAAC;IAE9D,YAA6B,UAA4B;QAA5B,eAAU,GAAV,UAAU,CAAkB;IAAG,CAAC;IAE7D,KAAK,CAAC,SAAS,CAAC,OAA6B,EAAE,IAAiC;QAC9E,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAC/C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;QACjD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAEpC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;YAClD,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;YACnD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,QAAgB,EAAE,UAAkB,EAAE,SAAiB,EAAE,OAAgB;QACrF,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,MAAM,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,OAAO,UAAU,gBAAgB,UAAU,GAAG,CAAC,CAAC;IAC5G,CAAC;CACF,CAAA;AAzBY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,2BAAkB,EAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;qCAIM,qCAAgB;GAH9C,kBAAkB,CAyB9B"}

package/dist/workflows/tracing/services/tool-trace.service.d.ts

@@ -0,0 +1,12 @@
+export interface ToolTraceEntry {
+    toolName: string;
+    workflowId: string;
+    durationMs: number;
+    success: boolean;
+}
+export declare class ToolTraceService {
+    private readonly entries;
+    record(entry: ToolTraceEntry): void;
+    forWorkflow(workflowId: string): ToolTraceEntry[];
+}
+//# sourceMappingURL=tool-trace.service.d.ts.map

package/dist/workflows/tracing/services/tool-trace.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-trace.service.d.ts","sourceRoot":"","sources":["../../../../src/workflows/tracing/services/tool-trace.service.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,qBACa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAOnC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE;CAGlD"}

package/dist/workflows/tracing/services/tool-trace.service.js

@@ -0,0 +1,28 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolTraceService = void 0;
+const common_1 = require("@nestjs/common");
+const MAX_ENTRIES = 100;
+let ToolTraceService = class ToolTraceService {
+    entries = [];
+    record(entry) {
+        this.entries.push(entry);
+        if (this.entries.length > MAX_ENTRIES) {
+            this.entries.shift();
+        }
+    }
+    forWorkflow(workflowId) {
+        return this.entries.filter((entry) => entry.workflowId === workflowId);
+    }
+};
+exports.ToolTraceService = ToolTraceService;
+exports.ToolTraceService = ToolTraceService = __decorate([
+    (0, common_1.Injectable)()
+], ToolTraceService);
+//# sourceMappingURL=tool-trace.service.js.map

package/dist/workflows/tracing/services/tool-trace.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-trace.service.js","sourceRoot":"","sources":["../../../../src/workflows/tracing/services/tool-trace.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAS5C,MAAM,WAAW,GAAG,GAAG,CAAC;AAGjB,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IACV,OAAO,GAAqB,EAAE,CAAC;IAEhD,MAAM,CAAC,KAAqB;QAC1B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED,WAAW,CAAC,UAAkB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;IACzE,CAAC;CACF,CAAA;AAbY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;GACA,gBAAgB,CAa5B"}

package/dist/workflows/tracing/tools/simulate-work.tool.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { BaseTool, ToolEnvelope } from '@loopstack/common';
+declare const SimulateWorkSchema: z.ZodObject<{
+    label: z.ZodString;
+    delayMs: z.ZodNumber;
+}, z.core.$strip>;
+type SimulateWorkArgs = z.infer<typeof SimulateWorkSchema>;
+export interface SimulateWorkToolResult {
+    label: string;
+    delayMs: number;
+}
+export declare const SimulateWorkToolResultSchema: z.ZodObject<{
+    label: z.ZodString;
+    delayMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare class SimulateWorkTool extends BaseTool<SimulateWorkArgs, object, SimulateWorkToolResult> {
+    protected handle(args: SimulateWorkArgs): Promise<ToolEnvelope<SimulateWorkToolResult>>;
+}
+export {};
+//# sourceMappingURL=simulate-work.tool.d.ts.map

package/dist/workflows/tracing/tools/simulate-work.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulate-work.tool.d.ts","sourceRoot":"","sources":["../../../../src/workflows/tracing/tools/simulate-work.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAQ,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjE,QAAA,MAAM,kBAAkB;;;iBAGtB,CAAC;AAEH,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE3D,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,4BAA4B;;;kBAGvC,CAAC;AAEH,qBAOa,gBAAiB,SAAQ,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,sBAAsB,CAAC;cAC9E,MAAM,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,sBAAsB,CAAC,CAAC;CAI9F"}

package/dist/workflows/tracing/tools/simulate-work.tool.js

@@ -0,0 +1,36 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimulateWorkTool = exports.SimulateWorkToolResultSchema = void 0;
+const zod_1 = require("zod");
+const common_1 = require("@loopstack/common");
+const SimulateWorkSchema = zod_1.z.object({
+    label: zod_1.z.string(),
+    delayMs: zod_1.z.number().min(0).max(5000),
+});
+exports.SimulateWorkToolResultSchema = zod_1.z.strictObject({
+    label: zod_1.z.string(),
+    delayMs: zod_1.z.number(),
+});
+let SimulateWorkTool = class SimulateWorkTool extends common_1.BaseTool {
+    async handle(args) {
+        await new Promise((resolve) => setTimeout(resolve, args.delayMs));
+        return { data: { label: args.label, delayMs: args.delayMs } };
+    }
+};
+exports.SimulateWorkTool = SimulateWorkTool;
+exports.SimulateWorkTool = SimulateWorkTool = __decorate([
+    (0, common_1.Tool)({
+        name: 'simulate_work',
+        description: 'Sleeps for the given duration so interceptors have something to measure.',
+        schema: SimulateWorkSchema,
+        resultSchema: exports.SimulateWorkToolResultSchema,
+        effects: 'none',
+    })
+], SimulateWorkTool);
+//# sourceMappingURL=simulate-work.tool.js.map

package/dist/workflows/tracing/tools/simulate-work.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulate-work.tool.js","sourceRoot":"","sources":["../../../../src/workflows/tracing/tools/simulate-work.tool.ts"],"names":[],"mappings":";;;;;;;;;AAAA,6BAAwB;AACxB,8CAAiE;AAEjE,MAAM,kBAAkB,GAAG,OAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;CACrC,CAAC,CAAC;AASU,QAAA,4BAA4B,GAAG,OAAC,CAAC,YAAY,CAAC;IACzD,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE;CACpB,CAAC,CAAC;AASI,IAAM,gBAAgB,GAAtB,MAAM,gBAAiB,SAAQ,iBAA0D;IACpF,KAAK,CAAC,MAAM,CAAC,IAAsB;QAC3C,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAClE,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;IAChE,CAAC;CACF,CAAA;AALY,4CAAgB;2BAAhB,gBAAgB;IAP5B,IAAA,aAAI,EAAC;QACJ,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE,0EAA0E;QACvF,MAAM,EAAE,kBAAkB;QAC1B,YAAY,EAAE,oCAA4B;QAC1C,OAAO,EAAE,MAAM;KAChB,CAAC;GACW,gBAAgB,CAK5B"}

package/dist/workflows/tracing/tracing-example.workflow.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { BaseWorkflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { ToolTraceService } from './services/tool-trace.service';
+import { SimulateWorkTool } from './tools/simulate-work.tool';
+declare const TracingExampleArgsSchema: z.ZodObject<{
+    steps: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type TracingExampleArgs = z.infer<typeof TracingExampleArgsSchema>;
+export declare class TracingExampleWorkflow extends BaseWorkflow<TracingExampleArgs> {
+    private readonly simulateWorkTool;
+    private readonly traceStore;
+    constructor(simulateWorkTool: SimulateWorkTool, traceStore: ToolTraceService);
+    runAndTrace(_state: object, ctx: RunContext<TracingExampleArgs>): Promise<void>;
+}
+export {};
+//# sourceMappingURL=tracing-example.workflow.d.ts.map

package/dist/workflows/tracing/tracing-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/tracing/tracing-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAA0C,MAAM,mBAAmB,CAAC;AACzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,QAAA,MAAM,wBAAwB;;iBAE5B,CAAC;AAEH,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEnE,qBAMa,sBAAuB,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IAExE,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU;gBADV,gBAAgB,EAAE,gBAAgB,EAClC,UAAU,EAAE,gBAAgB;IAMzC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,kBAAkB,CAAC;CAmBtE"}

package/dist/workflows/tracing/tracing-example.workflow.js

@@ -0,0 +1,62 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracingExampleWorkflow = void 0;
+const zod_1 = require("zod");
+const common_1 = require("@loopstack/common");
+const tool_trace_service_1 = require("./services/tool-trace.service");
+const simulate_work_tool_1 = require("./tools/simulate-work.tool");
+const TracingExampleArgsSchema = zod_1.z.object({
+    steps: zod_1.z.number().min(1).max(10).default(3),
+});
+let TracingExampleWorkflow = class TracingExampleWorkflow extends common_1.BaseWorkflow {
+    simulateWorkTool;
+    traceStore;
+    constructor(simulateWorkTool, traceStore) {
+        super();
+        this.simulateWorkTool = simulateWorkTool;
+        this.traceStore = traceStore;
+    }
+    async runAndTrace(_state, ctx) {
+        for (let i = 1; i <= ctx.args.steps; i++) {
+            await this.simulateWorkTool.call({ label: `step-${i}`, delayMs: i * 100 });
+        }
+        const entries = this.traceStore.forWorkflow(ctx.workflowId);
+        await this.documentStore.save(common_1.MarkdownDocument, {
+            markdown: [
+                '## Tool Trace',
+                '',
+                'Collected by `TracingInterceptor` — it wraps every tool call in this app.',
+                '',
+                '| Tool | Duration | Status |',
+                '| ---- | -------- | ------ |',
+                ...entries.map((e) => `| \`${e.toolName}\` | ${e.durationMs}ms | ${e.success ? '✅ ok' : '❌ failed'} |`),
+            ].join('\n'),
+        });
+    }
+};
+exports.TracingExampleWorkflow = TracingExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'end' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], TracingExampleWorkflow.prototype, "runAndTrace", null);
+exports.TracingExampleWorkflow = TracingExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Observability - Tracing Interceptor Example',
+        description: 'Demonstrates a custom ToolInterceptor — @UseToolInterceptor() registers it app-wide, it measures every tool execution and stores trace entries in an injectable service. The workflow runs a few tool calls and renders the collected trace.',
+        schema: TracingExampleArgsSchema,
+    }),
+    __metadata("design:paramtypes", [simulate_work_tool_1.SimulateWorkTool,
+        tool_trace_service_1.ToolTraceService])
+], TracingExampleWorkflow);
+//# sourceMappingURL=tracing-example.workflow.js.map

package/dist/workflows/tracing/tracing-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/tracing/tracing-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6BAAwB;AACxB,8CAAyF;AAEzF,sEAAiE;AACjE,mEAA8D;AAE9D,MAAM,wBAAwB,GAAG,OAAC,CAAC,MAAM,CAAC;IACxC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC,CAAC;AAUI,IAAM,sBAAsB,GAA5B,MAAM,sBAAuB,SAAQ,qBAAgC;IAEvD;IACA;IAFnB,YACmB,gBAAkC,EAClC,UAA4B;QAE7C,KAAK,EAAE,CAAC;QAHS,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,eAAU,GAAV,UAAU,CAAkB;IAG/C,CAAC;IAGK,AAAN,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,GAAmC;QACnE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAE5D,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,eAAe;gBACf,EAAE;gBACF,2EAA2E;gBAC3E,EAAE;gBACF,8BAA8B;gBAC9B,8BAA8B;gBAC9B,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,QAAQ,CAAC,CAAC,UAAU,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC;aACxG,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA5BY,wDAAsB;AAS3B;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;yDAmBzB;iCA3BU,sBAAsB;IANlC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,6CAA6C;QACpD,WAAW,EACT,8OAA8O;QAChP,MAAM,EAAE,wBAAwB;KACjC,CAAC;qCAGqC,qCAAgB;QACtB,qCAAgB;GAHpC,sBAAsB,CA4BlC"}

package/package.json

@@ -9,7 +9,7 @@
     "quota",
     "workflow"
   ],
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "author": {
     "name": "Jakob Klippel",
@@ -31,8 +31,10 @@
   },
   "dependencies": {
     "@loopstack/common": "*",
+    "@loopstack/contracts": "*",
     "@loopstack/quota": "*",
     "@nestjs/common": "^11.1.19",
+    "@nestjs/event-emitter": "^3.0.1",
     "zod": "^4.3.6"
   },
   "files": [

package/src/index.ts

@@ -1,2 +1,12 @@
 export * from './observability-examples.module';
 export * from './workflows/quota/quota-example.workflow';
+export * from './workflows/tracing/tracing-example.workflow';
+export * from './workflows/tracing/services/tool-trace.service';
+export * from './workflows/tracing/interceptors/tracing.interceptor';
+export * from './workflows/tracing/tools/simulate-work.tool';
+export * from './workflows/custom-calculator/custom-calculator-example.workflow';
+export * from './workflows/custom-calculator/calculators/words-processed.calculator';
+export * from './workflows/custom-calculator/tools/analyze-text.tool';
+export * from './workflows/audit-log/audit-log-example.workflow';
+export * from './workflows/audit-log/services/audit-log.service';
+export * from './workflows/audit-log/listeners/audit.listener';

package/src/observability-examples.module.ts

@@ -1,15 +1,42 @@
-import { Module } from '@nestjs/common';
+import { Module, OnModuleInit } from '@nestjs/common';
 import { StudioApp } from '@loopstack/common';
-import { QuotaModule } from '@loopstack/quota';
+import { QuotaCalculatorRegistry, QuotaModule } from '@loopstack/quota';
+import { AuditLogExampleWorkflow } from './workflows/audit-log/audit-log-example.workflow';
+import { AuditListener } from './workflows/audit-log/listeners/audit.listener';
+import { AuditLogService } from './workflows/audit-log/services/audit-log.service';
+import { WordsProcessedQuotaCalculator } from './workflows/custom-calculator/calculators/words-processed.calculator';
+import { CustomCalculatorExampleWorkflow } from './workflows/custom-calculator/custom-calculator-example.workflow';
+import { AnalyzeTextTool } from './workflows/custom-calculator/tools/analyze-text.tool';
 import { QuotaExampleWorkflow } from './workflows/quota/quota-example.workflow';
+import { TracingInterceptor } from './workflows/tracing/interceptors/tracing.interceptor';
+import { ToolTraceService } from './workflows/tracing/services/tool-trace.service';
+import { SimulateWorkTool } from './workflows/tracing/tools/simulate-work.tool';
+import { TracingExampleWorkflow } from './workflows/tracing/tracing-example.workflow';
 
 @StudioApp({
   title: 'Observability Examples',
-  workflows: [QuotaExampleWorkflow],
+  workflows: [QuotaExampleWorkflow, TracingExampleWorkflow, CustomCalculatorExampleWorkflow, AuditLogExampleWorkflow],
 })
 @Module({
   imports: [QuotaModule.forRoot({ enabled: false })],
-  providers: [QuotaExampleWorkflow],
-  exports: [QuotaExampleWorkflow],
+  providers: [
+    QuotaExampleWorkflow,
+    TracingExampleWorkflow,
+    ToolTraceService,
+    TracingInterceptor,
+    SimulateWorkTool,
+    CustomCalculatorExampleWorkflow,
+    AnalyzeTextTool,
+    AuditLogExampleWorkflow,
+    AuditLogService,
+    AuditListener,
+  ],
+  exports: [QuotaExampleWorkflow, TracingExampleWorkflow, CustomCalculatorExampleWorkflow, AuditLogExampleWorkflow],
 })
-export class ObservabilityExamplesModule {}
+export class ObservabilityExamplesModule implements OnModuleInit {
+  constructor(private readonly calculatorRegistry: QuotaCalculatorRegistry) {}
+
+  onModuleInit() {
+    this.calculatorRegistry.register('AnalyzeTextTool', new WordsProcessedQuotaCalculator());
+  }
+}

package/src/workflows/audit-log/audit-log-example.workflow.ts

@@ -0,0 +1,43 @@
+import { BaseWorkflow, MarkdownDocument, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { AuditLogService } from './services/audit-log.service';
+
+@Workflow({
+  title: 'Observability - Audit Log Example',
+  description:
+    'Demonstrates subscribing to framework events — an @OnEvent("client.message") listener records every workflow and document lifecycle event into an injectable service. The workflow emits a few events, then renders its own audit trail.',
+})
+export class AuditLogExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly auditLog: AuditLogService) {
+    super();
+  }
+
+  @Transition({ to: 'auditing' })
+  async doWork() {
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'Doing some work — each saved document emits a `document.created` event.',
+    });
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: 'The audit listener captures these events app-wide.',
+    });
+  }
+
+  @Transition({ from: 'auditing', to: 'end' })
+  async renderAudit(_state: object, ctx: RunContext) {
+    const entries = this.auditLog.forWorkflow(ctx.workflowId);
+
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: [
+        '## Audit Trail',
+        '',
+        `Captured by \`AuditListener\` via \`@OnEvent('client.message')\` for workflow \`${ctx.workflowId}\`.`,
+        '',
+        '| Event type | User |',
+        '| ---------- | ---- |',
+        ...entries.map((e) => `| \`${e.type}\` | \`${e.userId ?? 'anonymous'}\` |`),
+      ].join('\n'),
+    });
+  }
+}

package/src/workflows/audit-log/listeners/audit.listener.ts

@@ -0,0 +1,22 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import type { ClientMessage } from '@loopstack/contracts/events';
+import { AuditLogService } from '../services/audit-log.service';
+
+@Injectable()
+export class AuditListener {
+  private readonly logger = new Logger(AuditListener.name);
+
+  constructor(private readonly auditLog: AuditLogService) {}
+
+  @OnEvent('client.message')
+  handle(payload: ClientMessage): void {
+    const workflowId = 'workflowId' in payload ? payload.workflowId : undefined;
+    this.auditLog.record({
+      type: payload.type,
+      workflowId,
+      userId: payload.userId,
+    });
+    this.logger.log(`${payload.type} (workflow ${workflowId ?? '-'})`);
+  }
+}

package/src/workflows/audit-log/services/audit-log.service.ts

@@ -0,0 +1,25 @@
+import { Injectable } from '@nestjs/common';
+
+export interface AuditEntry {
+  type: string;
+  workflowId?: string;
+  userId: string | null;
+}
+
+const MAX_ENTRIES = 200;
+
+@Injectable()
+export class AuditLogService {
+  private readonly entries: AuditEntry[] = [];
+
+  record(entry: AuditEntry): void {
+    this.entries.push(entry);
+    if (this.entries.length > MAX_ENTRIES) {
+      this.entries.shift();
+    }
+  }
+
+  forWorkflow(workflowId: string): AuditEntry[] {
+    return this.entries.filter((entry) => entry.workflowId === workflowId);
+  }
+}

package/src/workflows/custom-calculator/__tests__/custom-calculator-example.spec.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { runWorkflow } from '@loopstack/testing';
+import { ObservabilityExamplesModule } from '../../../observability-examples.module';
+import { CustomCalculatorExampleWorkflow } from '../custom-calculator-example.workflow';
+import { AnalyzeTextTool } from '../tools/analyze-text.tool';
+
+/**
+ * The counter-lesson to replay: here the tool runs *live*. The whole point is the interceptor
+ * and quota calculator that fire around a real tool call, so mocking the tool would defeat the
+ * test. Importing the app module wires up the `QuotaInterceptor` and registers the custom
+ * calculator; `QuotaModule.forRoot({ enabled: false })` makes quota a no-op, so no Redis.
+ */
+describe('CustomCalculatorExampleWorkflow', () => {
+  it('runs the analyze tool live and reports the analysis with quota disabled', async () => {
+    const run = await runWorkflow(
+      CustomCalculatorExampleWorkflow,
+      { text: 'The quick brown fox jumps over the lazy dog' },
+      { imports: [ObservabilityExamplesModule], providers: [AnalyzeTextTool] },
+    );
+
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe('completed');
+    const markdown = run.documents.map((d) => (d.content as { markdown?: string }).markdown ?? '').join('\n');
+    expect(markdown).toContain('- Words: `9`');
+    expect(markdown).toContain('- Limit: `-1`');
+  });
+});

package/src/workflows/custom-calculator/calculators/words-processed.calculator.ts

@@ -0,0 +1,15 @@
+import { ToolEnvelope, ToolExecutionContext } from '@loopstack/common';
+import { QuotaUsage, ToolQuotaCalculator } from '@loopstack/quota';
+import type { AnalyzeTextToolResult } from '../tools/analyze-text.tool';
+
+export class WordsProcessedQuotaCalculator implements ToolQuotaCalculator {
+  quotaType = 'words-processed';
+
+  calculateQuotaUsage(_context: ToolExecutionContext, result: ToolEnvelope): QuotaUsage | null {
+    const data = result.data as AnalyzeTextToolResult | undefined;
+    if (typeof data?.words !== 'number') {
+      return null;
+    }
+    return { quotaType: this.quotaType, actualAmount: data.words };
+  }
+}

package/src/workflows/custom-calculator/custom-calculator-example.workflow.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { BaseWorkflow, MarkdownDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { QuotaClientService } from '@loopstack/quota';
+import { AnalyzeTextTool } from './tools/analyze-text.tool';
+import type { AnalyzeTextToolResult } from './tools/analyze-text.tool';
+
+const CustomCalculatorExampleArgsSchema = z.object({
+  text: z.string().default('The quick brown fox jumps over the lazy dog'),
+});
+
+type CustomCalculatorExampleArgs = z.infer<typeof CustomCalculatorExampleArgsSchema>;
+
+@Workflow({
+  title: 'Observability - Custom Quota Calculator Example',
+  description:
+    'Demonstrates a custom ToolQuotaCalculator — WordsProcessedQuotaCalculator meters AnalyzeTextTool by words in the result. The built-in QuotaInterceptor checks and reports the quota automatically; the workflow only calls the tool.',
+  schema: CustomCalculatorExampleArgsSchema,
+})
+export class CustomCalculatorExampleWorkflow extends BaseWorkflow<CustomCalculatorExampleArgs> {
+  constructor(
+    private readonly analyzeTextTool: AnalyzeTextTool,
+    private readonly quotaClient: QuotaClientService,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'end' })
+  async analyze(_state: object, ctx: RunContext<CustomCalculatorExampleArgs>) {
+    const result = await this.analyzeTextTool.call({ text: ctx.args.text });
+    const analysis = result.data as AnalyzeTextToolResult;
+
+    const quota = await this.quotaClient.checkQuota(ctx.userId, 'words-processed');
+
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: [
+        '## Text Analysis',
+        '',
+        `- Words: \`${analysis.words}\``,
+        `- Characters: \`${analysis.characters}\``,
+        '',
+        '## Quota `words-processed`',
+        '',
+        `- Used: \`${quota.used}\``,
+        `- Limit: \`${quota.limit}\` (\`-1\` = unlimited / quota disabled)`,
+        '',
+        'The `QuotaInterceptor` charged the word count automatically via `WordsProcessedQuotaCalculator`.',
+        'With `QuotaModule.forRoot({ enabled: false })` all quota calls no-op.',
+      ].join('\n'),
+    });
+  }
+}

package/src/workflows/custom-calculator/tools/analyze-text.tool.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+
+const AnalyzeTextSchema = z.object({
+  text: z.string(),
+});
+
+type AnalyzeTextArgs = z.infer<typeof AnalyzeTextSchema>;
+
+export interface AnalyzeTextToolResult {
+  words: number;
+  characters: number;
+}
+
+export const AnalyzeTextToolResultSchema = z.strictObject({
+  words: z.number(),
+  characters: z.number(),
+});
+
+@Tool({
+  name: 'analyze_text',
+  description: 'Counts words and characters in a text. Its usage is metered by WordsProcessedQuotaCalculator.',
+  schema: AnalyzeTextSchema,
+  resultSchema: AnalyzeTextToolResultSchema,
+  effects: 'none',
+})
+export class AnalyzeTextTool extends BaseTool<AnalyzeTextArgs, object, AnalyzeTextToolResult> {
+  protected async handle(args: AnalyzeTextArgs): Promise<ToolEnvelope<AnalyzeTextToolResult>> {
+    const words = args.text.split(/\s+/).filter(Boolean).length;
+    return Promise.resolve({ data: { words, characters: args.text.length } });
+  }
+}

package/src/workflows/quota/quota-example.workflow.ts

@@ -10,7 +10,7 @@ interface QuotaExampleState {
 }
 
 const QuotaExampleArgsSchema = z.object({
-  quotaType: z.string().default('ai_generate_text'),
+  quotaType: z.string().default('llm-cost'),
   reportAmount: z.number().default(1000),
 });