@looprun-ai/mastra 0.1.0

package/dist/session.js

@@ -0,0 +1,53 @@
+/**
+ * @looprun-ai/mastra — per-conversation session state.
+ *
+ * One LoopRunAgent is registered ONCE (Mastra instance / Studio) while each conversation gets its
+ * own world + ledger + message history, keyed by sessionId. A per-session promise-chain mutex
+ * serializes concurrent turns of the same conversation.
+ */
+import { createLedger } from '@looprun-ai/core';
+export class SessionStore {
+    sessions = new Map();
+    factory;
+    singleton;
+    constructor(world) {
+        if (typeof world === 'function') {
+            this.factory = world;
+            this.singleton = null;
+        }
+        else {
+            this.factory = null;
+            this.singleton = world;
+        }
+    }
+    get(id) {
+        const existing = this.sessions.get(id);
+        if (existing)
+            return existing;
+        if (this.singleton && id !== 'default') {
+            throw new Error(`looprun: session "${id}" requested but the agent was built with a single world INSTANCE — ` +
+                'pass a world FACTORY ((sessionId) => world) to support multiple conversations.');
+        }
+        const world = this.singleton ?? this.factory(id);
+        const session = {
+            id,
+            world,
+            ledger: createLedger(),
+            turnIndex: 0,
+            messages: [],
+            chain: Promise.resolve(),
+        };
+        this.sessions.set(id, session);
+        return session;
+    }
+    end(id) {
+        this.sessions.delete(id);
+    }
+    /** Serialize `fn` on the session's mutex chain. */
+    run(session, fn) {
+        const next = session.chain.then(fn, fn);
+        session.chain = next.catch(() => { });
+        return next;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAiBhD,MAAM,OAAO,YAAY;IACN,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IAChD,OAAO,CAAyB;IAChC,SAAS,CAAW;IAErC,YAAY,KAA0B;QACpC,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,GAAG,KAAwB,CAAC;YACxC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACzB,CAAC;IACH,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,qBAAqB,EAAE,qEAAqE;gBAC1F,gFAAgF,CACnF,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAQ,CAAC,EAAE,CAAC,CAAC;QAClD,MAAM,OAAO,GAAsB;YACjC,EAAE;YACF,KAAK;YACL,MAAM,EAAE,YAAY,EAAE;YACtB,SAAS,EAAE,CAAC;YACZ,QAAQ,EAAE,EAAE;YACZ,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;SACzB,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,mDAAmD;IACnD,GAAG,CAAI,OAA0B,EAAE,EAAoB;QACrD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACxC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/tools.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDef } from '@looprun-ai/core';
+import type { LoopRunSession } from './session.js';
+export type SessionAccessor = () => LoopRunSession;
+/** Build the Mastra tool map for a spec surface: domain tools (world.exec) + the terminal tools. */
+export declare function buildWorldTools(toolDefs: ToolDef[], surface: ReadonlySet<string>, getSession: SessionAccessor): Record<string, any>;
+/** Build ONLY the terminal tools (native-tools mode: domain tools execute themselves). */
+export declare function buildTerminalTools(getSession: SessionAccessor): Record<string, any>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,MAAM,MAAM,eAAe,GAAG,MAAM,cAAc,CAAC;AAEnD,oGAAoG;AACpG,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAC5B,UAAU,EAAE,eAAe,GAE1B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiCrB;AAED,0FAA0F;AAE1F,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiBnF"}

package/dist/tools.js

@@ -0,0 +1,67 @@
+/**
+ * @looprun-ai/mastra — tool wiring: JSON-schema ToolDefs → Mastra tools executed through the world seam.
+ *
+ * Terminal tools (replyToUser/askUser) are runtime-owned: their execute captures the user-facing
+ * text into the ACTIVE session's ledger. Domain tools route to `world.exec(name, args)`.
+ */
+import { createTool } from '@mastra/core/tools';
+import { isTerminal, recordTerminal, terminalToolDefs } from '@looprun-ai/core';
+import { jsonSchemaToZodObject } from './json-schema-zod.js';
+/** Build the Mastra tool map for a spec surface: domain tools (world.exec) + the terminal tools. */
+export function buildWorldTools(toolDefs, surface, getSession) {
+    const byName = new Map(toolDefs.map((d) => [d.name, d]));
+    // Backfill terminal defs when the host's toolDefs omit them.
+    for (const def of terminalToolDefs())
+        if (!byName.has(def.name))
+            byName.set(def.name, def);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tools = {};
+    for (const def of byName.values()) {
+        if (!surface.has(def.name) && !isTerminal(def.name))
+            continue;
+        if (isTerminal(def.name)) {
+            tools[def.name] = createTool({
+                id: def.name,
+                description: def.description,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                inputSchema: jsonSchemaToZodObject(def.inputSchema),
+                execute: async (input) => {
+                    const args = (input ?? {});
+                    const session = getSession();
+                    recordTerminal(session.ledger, def.name, args);
+                    return session.world.exec(def.name, args);
+                },
+            });
+            continue;
+        }
+        tools[def.name] = createTool({
+            id: def.name,
+            description: def.description,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            inputSchema: jsonSchemaToZodObject(def.inputSchema),
+            execute: async (input) => getSession().world.exec(def.name, (input ?? {})),
+        });
+    }
+    return tools;
+}
+/** Build ONLY the terminal tools (native-tools mode: domain tools execute themselves). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildTerminalTools(getSession) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tools = {};
+    for (const def of terminalToolDefs()) {
+        tools[def.name] = createTool({
+            id: def.name,
+            description: def.description,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            inputSchema: jsonSchemaToZodObject(def.inputSchema),
+            execute: async (input) => {
+                const args = (input ?? {});
+                recordTerminal(getSession().ledger, def.name, args);
+                return { success: true };
+            },
+        });
+    }
+    return tools;
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/world-adapters.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @looprun-ai/mastra — world adapters for NATIVE-TOOLS mode (including MCP).
+ *
+ * In native-tools mode the tools execute themselves (Mastra assigned tools, toolsets, or
+ * `@mastra/mcp` MCPClient tools) and guards are enforced through the agent hooks; the world seam
+ * is needed only for STATE: stateful guards (`precondition`, custom world reads) and
+ * `theme.stateBlock`. A `StateView` supplies those reads; `refresh` (if given) runs at each
+ * turn boundary so remote state can be re-fetched.
+ *
+ * Ledger-based guards (requiresBefore, noDuplicateCall, confirmFirst, maxCallsPerTurn, …) need
+ * NO state view — they read the observed ledger the hooks feed.
+ */
+import type { AgentWorld } from '@looprun-ai/core';
+/** Domain state reads for guards + theme.stateBlock (backed by your API / MCP resources / cache). */
+export interface StateView {
+    /** Called at each turn boundary (advanceTurn) — re-fetch remote state here if needed. */
+    refresh?(): void | Promise<void>;
+    [k: string]: any;
+}
+/** Synthesize an AgentWorld for native-tools mode: state from `stateView`, execution by the tools. */
+export declare function worldFromTools(opts?: {
+    stateView?: StateView;
+}): AgentWorld;
+//# sourceMappingURL=world-adapters.d.ts.map

package/dist/world-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-adapters.d.ts","sourceRoot":"","sources":["../src/world-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,qGAAqG;AACrG,MAAM,WAAW,SAAS;IACxB,yFAAyF;IACzF,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjC,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CAClB;AAED,sGAAsG;AACtG,wBAAgB,cAAc,CAAC,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,SAAS,CAAA;CAAO,GAAG,UAAU,CAsB/E"}

package/dist/world-adapters.js

@@ -0,0 +1,24 @@
+/** Synthesize an AgentWorld for native-tools mode: state from `stateView`, execution by the tools. */
+export function worldFromTools(opts = {}) {
+    const view = opts.stateView ?? {};
+    const world = {
+        exec: (name) => {
+            throw new Error(`looprun: world.exec("${name}") called in native-tools mode — domain tools execute themselves; ` +
+                'only the runtime-owned terminal tools should reach the world.');
+        },
+        advanceTurn: () => {
+            void view.refresh?.();
+        },
+        ingestAttachment: (url) => url,
+        toolCalls: [],
+        sseActions: [],
+    };
+    for (const [k, v] of Object.entries(view)) {
+        if (k === 'refresh')
+            continue;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        world[k] = typeof v === 'function' ? v.bind(view) : v;
+    }
+    return world;
+}
+//# sourceMappingURL=world-adapters.js.map

package/dist/world-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-adapters.js","sourceRoot":"","sources":["../src/world-adapters.ts"],"names":[],"mappings":"AAsBA,sGAAsG;AACtG,MAAM,UAAU,cAAc,CAAC,OAAkC,EAAE;IACjE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IAClC,MAAM,KAAK,GAAe;QACxB,IAAI,EAAE,CAAC,IAAY,EAAE,EAAE;YACrB,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,oEAAoE;gBAC9F,+DAA+D,CACpE,CAAC;QACF,CAAC;QACD,WAAW,EAAE,GAAG,EAAE;YAChB,KAAK,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QACxB,CAAC;QACD,gBAAgB,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG;QACtC,SAAS,EAAE,EAAE;QACb,UAAU,EAAE,EAAE;KACf,CAAC;IACF,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,8DAA8D;QAC7D,KAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@looprun-ai/mastra",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "looprun on Mastra: LoopRunAgent — a genuine @mastra/core Agent compiled from an AgentSpec, with deterministic guard enforcement (beforeToolCall veto), the terminal protocol, bounded no-tools redrive and honest-abstain exhaustion. Studio-compatible.",
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "governance",
+    "guardrails",
+    "agentspec",
+    "mastra",
+    "agent"
+  ],
+  "license": "Apache-2.0",
+  "author": "LoopRun Team",
+  "homepage": "https://looprun.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/looprun-ai/looprun.git",
+    "directory": "packages/mastra"
+  },
+  "bugs": {
+    "url": "https://github.com/looprun-ai/looprun/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@looprun-ai/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@mastra/core": "^1.42.0",
+    "ai": "^6.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@mastra/core": "^1.42.0",
+    "@types/node": "^22.0.0",
+    "ai": "^6.0.184",
+    "typescript": "^5.7.0",
+    "vitest": "^2.0.0",
+    "zod": "^3.24.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}