@moxxy/agent 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,87 @@
+# @moxxy/agent
+
+The fastest way to run a [moxxy](https://moxxy.ai) agent — **one install, one
+call.** Batteries included: it bundles the runtime (`@moxxy/core`), the default
+loop, and the OpenAI + Anthropic providers behind drop-in presets.
+
+```bash
+npm i @moxxy/agent
+```
+
+## Hello, agent
+
+```ts
+import { setupAgent, openaiPreset } from '@moxxy/agent';
+
+const { ask } = setupAgent(openaiPreset({ apiKey: process.env.OPENAI_API_KEY }));
+
+console.log(await ask('Write a haiku about TypeScript.'));
+```
+
+Stream the events instead:
+
+```ts
+const { stream } = setupAgent(openaiPreset({ apiKey: process.env.OPENAI_API_KEY }));
+
+for await (const event of stream('Explain async generators.')) {
+  if (event.type === 'assistant_chunk') process.stdout.write(event.delta);
+}
+```
+
+## Claude, or both
+
+```ts
+import { setupAgent, openaiPreset, anthropicPreset } from '@moxxy/agent';
+
+// Just Claude:
+const claude = setupAgent(anthropicPreset({ apiKey: process.env.ANTHROPIC_API_KEY }));
+
+// Or register both and switch per turn (the first preset is active):
+const agent = setupAgent([
+  openaiPreset({ apiKey: process.env.OPENAI_API_KEY }),
+  anthropicPreset({ apiKey: process.env.ANTHROPIC_API_KEY }),
+]);
+await agent.ask('Hi from OpenAI');
+agent.setProvider('anthropic');
+await agent.ask('Now from Claude');
+```
+
+## Add tools, swap blocks live
+
+```ts
+import { setupAgent, openaiPreset } from '@moxxy/agent';
+import { defineTool } from '@moxxy/sdk';
+import { z } from 'zod';
+
+const agent = setupAgent(openaiPreset({ apiKey: process.env.OPENAI_API_KEY }));
+
+agent.addTool(
+  defineTool({
+    name: 'get_weather',
+    description: 'Current weather for a city.',
+    inputSchema: z.object({ city: z.string() }),
+    handler: async ({ city }) => `Sunny in ${city}.`,
+  }),
+);
+
+console.log(await agent.ask("What's the weather in Paris?"));
+```
+
+`agent.session` is the live moxxy [`Session`](https://www.npmjs.com/package/@moxxy/core)
+— full control for anything the sugar doesn't cover.
+
+## Presets
+
+| preset | options |
+|---|---|
+| `openaiPreset(opts?)` | `apiKey` (→ `OPENAI_API_KEY`), `model`, `baseURL` (OpenAI-compatible vendors: z.ai/xAI/Google/Ollama) |
+| `anthropicPreset(opts?)` | `apiKey` (→ `ANTHROPIC_API_KEY`), `model` |
+
+Need more control or a different provider/mode? Drop down to
+[`@moxxy/core`](https://www.npmjs.com/package/@moxxy/core)'s `setupAgent({ plugins, provider, tools, … })`
+and register any blocks you like — `@moxxy/agent` re-exports `setupAgent` and all
+its types.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `@moxxy/agent` — the batteries-included entry to moxxy.
+ *
+ * One install, one call. Where `@moxxy/core`'s {@link setupAgent} is the flexible,
+ * block-agnostic factory (you bring the plugins), this package bundles the
+ * default loop + the OpenAI and Anthropic providers behind drop-in **presets**:
+ *
+ *   import { setupAgent, openaiPreset } from '@moxxy/agent';
+ *   const { ask } = setupAgent(openaiPreset({ apiKey: process.env.OPENAI_API_KEY }));
+ *   console.log(await ask('Hello!'));
+ *
+ * A preset is just a pre-filled {@link AgentPreset}, so they compose — pass an
+ * array to register several providers at once (the first is active; swap with
+ * `agent.setProvider(name)`):
+ *
+ *   const agent = setupAgent([openaiPreset({ apiKey: a }), anthropicPreset({ apiKey: b })]);
+ *   agent.setProvider('anthropic'); // for the next turn
+ */
+import type { AgentPreset } from '@moxxy/core';
+export interface ProviderPresetOptions {
+    /** API key. Defaults to the provider's conventional env var
+     *  (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`). */
+    readonly apiKey?: string;
+    /** Override the model id (otherwise the provider's default catalog applies). */
+    readonly model?: string;
+}
+export interface OpenAIPresetOptions extends ProviderPresetOptions {
+    /** Point at an OpenAI-compatible endpoint (z.ai, xAI, Google, Ollama/local). */
+    readonly baseURL?: string;
+}
+/**
+ * One-shop OpenAI (and OpenAI-compatible) preset: the default loop + the OpenAI
+ * provider, configured + activated. `setupAgent(openaiPreset({ apiKey }))`.
+ */
+export declare function openaiPreset(opts?: OpenAIPresetOptions): AgentPreset;
+/**
+ * One-shop Anthropic (Claude) preset: the default loop + the Anthropic provider,
+ * configured + activated. `setupAgent(anthropicPreset({ apiKey }))`.
+ */
+export declare function anthropicPreset(opts?: ProviderPresetOptions): AgentPreset;
+export { setupAgent, type Agent, type AgentPreset, type SetupAgentOptions, type MoxxyEvent, type Plugin, type ToolDef, type PermissionResolver, } from '@moxxy/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/C,MAAM,WAAW,qBAAqB;IACpC;oDACgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAOD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,mBAAwB,GAAG,WAAW,CAYxE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,qBAA0B,GAAG,WAAW,CAW7E;AAGD,OAAO,EACL,UAAU,EACV,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * `@moxxy/agent` — the batteries-included entry to moxxy.
+ *
+ * One install, one call. Where `@moxxy/core`'s {@link setupAgent} is the flexible,
+ * block-agnostic factory (you bring the plugins), this package bundles the
+ * default loop + the OpenAI and Anthropic providers behind drop-in **presets**:
+ *
+ *   import { setupAgent, openaiPreset } from '@moxxy/agent';
+ *   const { ask } = setupAgent(openaiPreset({ apiKey: process.env.OPENAI_API_KEY }));
+ *   console.log(await ask('Hello!'));
+ *
+ * A preset is just a pre-filled {@link AgentPreset}, so they compose — pass an
+ * array to register several providers at once (the first is active; swap with
+ * `agent.setProvider(name)`):
+ *
+ *   const agent = setupAgent([openaiPreset({ apiKey: a }), anthropicPreset({ apiKey: b })]);
+ *   agent.setProvider('anthropic'); // for the next turn
+ */
+import defaultModePlugin from '@moxxy/mode-default';
+import openaiPlugin from '@moxxy/plugin-provider-openai';
+import anthropicPlugin from '@moxxy/plugin-provider-anthropic';
+/** Drop `undefined` config fields so they don't override provider defaults. */
+function clean(config) {
+    return Object.fromEntries(Object.entries(config).filter(([, v]) => v !== undefined));
+}
+/**
+ * One-shop OpenAI (and OpenAI-compatible) preset: the default loop + the OpenAI
+ * provider, configured + activated. `setupAgent(openaiPreset({ apiKey }))`.
+ */
+export function openaiPreset(opts = {}) {
+    return {
+        plugins: [defaultModePlugin, openaiPlugin],
+        provider: {
+            name: 'openai',
+            config: clean({
+                apiKey: opts.apiKey ?? process.env.OPENAI_API_KEY,
+                model: opts.model,
+                baseURL: opts.baseURL,
+            }),
+        },
+    };
+}
+/**
+ * One-shop Anthropic (Claude) preset: the default loop + the Anthropic provider,
+ * configured + activated. `setupAgent(anthropicPreset({ apiKey }))`.
+ */
+export function anthropicPreset(opts = {}) {
+    return {
+        plugins: [defaultModePlugin, anthropicPlugin],
+        provider: {
+            name: 'anthropic',
+            config: clean({
+                apiKey: opts.apiKey ?? process.env.ANTHROPIC_API_KEY,
+                model: opts.model,
+            }),
+        },
+    };
+}
+// Re-export the core entry + its types so an app needs only `@moxxy/agent`.
+export { setupAgent, } from '@moxxy/core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AACpD,OAAO,YAAY,MAAM,+BAA+B,CAAC;AACzD,OAAO,eAAe,MAAM,kCAAkC,CAAC;AAe/D,+EAA+E;AAC/E,SAAS,KAAK,CAAC,MAA+B;IAC5C,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;AACvF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B,EAAE;IACzD,OAAO;QACL,OAAO,EAAE,CAAC,iBAAiB,EAAE,YAAY,CAAC;QAC1C,QAAQ,EAAE;YACR,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,KAAK,CAAC;gBACZ,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;gBACjD,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC;SACH;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAA8B,EAAE;IAC9D,OAAO;QACL,OAAO,EAAE,CAAC,iBAAiB,EAAE,eAAe,CAAC;QAC7C,QAAQ,EAAE;YACR,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,KAAK,CAAC;gBACZ,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB;gBACpD,KAAK,EAAE,IAAI,CAAC,KAAK;aAClB,CAAC;SACH;KACF,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,OAAO,EACL,UAAU,GAQX,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@moxxy/agent",
+  "version": "0.2.0",
+  "description": "Batteries-included entry to moxxy: one install + one call to run an agent. Bundles @moxxy/core, the default loop, and the OpenAI + Anthropic providers behind drop-in presets — `setupAgent(openaiPreset({ apiKey }))`.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "agentic",
+    "llm",
+    "openai",
+    "anthropic",
+    "sdk"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/agent"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@moxxy/core": "0.3.0",
+    "@moxxy/sdk": "0.15.0",
+    "@moxxy/mode-default": "0.1.0",
+    "@moxxy/plugin-provider-openai": "0.1.0",
+    "@moxxy/plugin-provider-anthropic": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { setupAgent, openaiPreset, anthropicPreset } from './index.js';
+
+const ORIGINAL_OPENAI = process.env.OPENAI_API_KEY;
+afterEach(() => {
+  if (ORIGINAL_OPENAI === undefined) delete process.env.OPENAI_API_KEY;
+  else process.env.OPENAI_API_KEY = ORIGINAL_OPENAI;
+});
+
+describe('@moxxy/agent presets', () => {
+  it('openaiPreset → a single-call agent with openai active', () => {
+    const agent = setupAgent(openaiPreset({ apiKey: 'sk-test' }));
+    expect(agent.session.providers.getActiveName()).toBe('openai');
+    expect(typeof agent.ask).toBe('function');
+    expect(typeof agent.stream).toBe('function');
+  });
+
+  it('anthropicPreset → anthropic active', () => {
+    const agent = setupAgent(anthropicPreset({ apiKey: 'sk-ant' }));
+    expect(agent.session.providers.getActiveName()).toBe('anthropic');
+  });
+
+  it('an array of presets registers both providers (first active) and de-dupes the shared mode', () => {
+    const agent = setupAgent([openaiPreset({ apiKey: 'a' }), anthropicPreset({ apiKey: 'b' })]);
+    expect(agent.session.providers.getActiveName()).toBe('openai');
+    expect(
+      agent.session.providers
+        .list()
+        .map((d) => d.name)
+        .sort(),
+    ).toEqual(['anthropic', 'openai']);
+    agent.setProvider('anthropic');
+    expect(agent.session.providers.getActiveName()).toBe('anthropic');
+  });
+
+  it('falls back to the conventional env var for the api key', () => {
+    process.env.OPENAI_API_KEY = 'env-key';
+    expect(openaiPreset().provider?.config?.apiKey).toBe('env-key');
+    expect(openaiPreset({ apiKey: 'explicit' }).provider?.config?.apiKey).toBe('explicit');
+  });
+});

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * `@moxxy/agent` — the batteries-included entry to moxxy.
+ *
+ * One install, one call. Where `@moxxy/core`'s {@link setupAgent} is the flexible,
+ * block-agnostic factory (you bring the plugins), this package bundles the
+ * default loop + the OpenAI and Anthropic providers behind drop-in **presets**:
+ *
+ *   import { setupAgent, openaiPreset } from '@moxxy/agent';
+ *   const { ask } = setupAgent(openaiPreset({ apiKey: process.env.OPENAI_API_KEY }));
+ *   console.log(await ask('Hello!'));
+ *
+ * A preset is just a pre-filled {@link AgentPreset}, so they compose — pass an
+ * array to register several providers at once (the first is active; swap with
+ * `agent.setProvider(name)`):
+ *
+ *   const agent = setupAgent([openaiPreset({ apiKey: a }), anthropicPreset({ apiKey: b })]);
+ *   agent.setProvider('anthropic'); // for the next turn
+ */
+
+import type { AgentPreset } from '@moxxy/core';
+import defaultModePlugin from '@moxxy/mode-default';
+import openaiPlugin from '@moxxy/plugin-provider-openai';
+import anthropicPlugin from '@moxxy/plugin-provider-anthropic';
+
+export interface ProviderPresetOptions {
+  /** API key. Defaults to the provider's conventional env var
+   *  (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`). */
+  readonly apiKey?: string;
+  /** Override the model id (otherwise the provider's default catalog applies). */
+  readonly model?: string;
+}
+
+export interface OpenAIPresetOptions extends ProviderPresetOptions {
+  /** Point at an OpenAI-compatible endpoint (z.ai, xAI, Google, Ollama/local). */
+  readonly baseURL?: string;
+}
+
+/** Drop `undefined` config fields so they don't override provider defaults. */
+function clean(config: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(config).filter(([, v]) => v !== undefined));
+}
+
+/**
+ * One-shop OpenAI (and OpenAI-compatible) preset: the default loop + the OpenAI
+ * provider, configured + activated. `setupAgent(openaiPreset({ apiKey }))`.
+ */
+export function openaiPreset(opts: OpenAIPresetOptions = {}): AgentPreset {
+  return {
+    plugins: [defaultModePlugin, openaiPlugin],
+    provider: {
+      name: 'openai',
+      config: clean({
+        apiKey: opts.apiKey ?? process.env.OPENAI_API_KEY,
+        model: opts.model,
+        baseURL: opts.baseURL,
+      }),
+    },
+  };
+}
+
+/**
+ * One-shop Anthropic (Claude) preset: the default loop + the Anthropic provider,
+ * configured + activated. `setupAgent(anthropicPreset({ apiKey }))`.
+ */
+export function anthropicPreset(opts: ProviderPresetOptions = {}): AgentPreset {
+  return {
+    plugins: [defaultModePlugin, anthropicPlugin],
+    provider: {
+      name: 'anthropic',
+      config: clean({
+        apiKey: opts.apiKey ?? process.env.ANTHROPIC_API_KEY,
+        model: opts.model,
+      }),
+    },
+  };
+}
+
+// Re-export the core entry + its types so an app needs only `@moxxy/agent`.
+export {
+  setupAgent,
+  type Agent,
+  type AgentPreset,
+  type SetupAgentOptions,
+  type MoxxyEvent,
+  type Plugin,
+  type ToolDef,
+  type PermissionResolver,
+} from '@moxxy/core';