@amodalai/runtime 0.3.49 → 0.3.51

package/dist/src/setup/commit-setup.test.js

@@ -0,0 +1,310 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Phase E.2 integration test for `commitSetup`. Runs against a real
+ * Postgres + a real `LocalFsBackend` over a temp repo so the
+ * file-then-DB ordering, idempotency, and validation gating all get
+ * exercised end-to-end.
+ *
+ * Skips when DATABASE_URL is not set (same pattern as the Phase B
+ * setup-state.test.ts).
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import * as path from 'node:path';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { closeDb, ensureSchema, getDb, upsertSetupState, } from '@amodalai/db';
+import { LocalFsBackend } from '../tools/fs/local.js';
+import { commitSetup, composeAmodalJson } from './commit-setup.js';
+const HAS_DB = Boolean(process.env['DATABASE_URL']);
+const describeWhenDb = HAS_DB ? describe : describe.skip;
+function makePlan(overrides) {
+    return {
+        templatePackage: '@amodalai/test-template',
+        slots: [],
+        config: [],
+        completion: {
+            title: 'Test Agent',
+            suggestions: [],
+            automationTitle: null,
+        },
+        ...overrides,
+    };
+}
+const slackSlot = {
+    label: 'Slack',
+    description: 'Where the digest gets posted.',
+    required: true,
+    multi: false,
+    options: [
+        {
+            packageName: '@amodalai/connection-slack',
+            displayName: 'Slack',
+            authType: 'bearer',
+            oauthScopes: [],
+        },
+    ],
+};
+describeWhenDb('commitSetup (Phase E.2 integration)', () => {
+    let db;
+    let repoRoot;
+    let fs;
+    let agentId;
+    const scopeId = '';
+    beforeAll(async () => {
+        db = getDb();
+        await ensureSchema(db);
+    });
+    afterAll(async () => {
+        await closeDb();
+    });
+    beforeEach(async () => {
+        repoRoot = await mkdtemp(path.join(tmpdir(), 'commit-setup-'));
+        fs = new LocalFsBackend({ repoRoot });
+        agentId = `agent_${randomUUID()}`;
+    });
+    afterEach(async () => {
+        // Clean DB row + temp repo so reruns stay isolated.
+        try {
+            const { deleteSetupState } = await import('@amodalai/db');
+            await deleteSetupState(db, agentId, scopeId);
+        }
+        catch {
+            // Ignore — best-effort cleanup.
+        }
+        await rm(repoRoot, { recursive: true, force: true });
+    });
+    it('returns no_state when no setup_state row exists', async () => {
+        const result = await commitSetup({ db, fs, agentId, scopeId });
+        expect(result).toMatchObject({ ok: false, reason: 'no_state' });
+    });
+    it('returns not_ready when a required slot is missing', async () => {
+        await upsertSetupState(db, agentId, scopeId, {
+            phase: 'configuring',
+            plan: makePlan({ slots: [slackSlot] }),
+        });
+        const result = await commitSetup({ db, fs, agentId, scopeId });
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            throw new Error('unreachable');
+        expect(result.reason).toBe('not_ready');
+        if (result.reason !== 'not_ready')
+            throw new Error('unreachable');
+        expect(result.warnings[0]?.kind).toBe('missing_required_slot');
+    });
+    it('commits when required slots are satisfied — writes amodal.json + marks completed_at', async () => {
+        await upsertSetupState(db, agentId, scopeId, {
+            phase: 'configuring',
+            plan: makePlan({
+                slots: [slackSlot],
+                completion: { title: 'Marketing Digest', suggestions: [], automationTitle: 'Weekly digest' },
+            }),
+            appendCompleted: [
+                {
+                    slotLabel: 'Slack',
+                    packageName: '@amodalai/connection-slack',
+                    connectedAt: new Date().toISOString(),
+                    validatedAt: new Date().toISOString(),
+                    validationFormatted: 'Found 12 channels',
+                },
+            ],
+        });
+        const result = await commitSetup({ db, fs, agentId, scopeId });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            throw new Error('unreachable');
+        expect(result.alreadyComplete).toBe(false);
+        expect(result.completedAt).toBeInstanceOf(Date);
+        // amodal.json was written with the right content.
+        const written = await readFile(path.join(repoRoot, 'amodal.json'), 'utf-8');
+        const parsed = JSON.parse(written);
+        expect(parsed.name).toBe('marketing-digest');
+        expect(parsed.version).toBe('1.0.0');
+        expect(parsed.packages).toContain('@amodalai/test-template');
+        expect(parsed.packages).toContain('@amodalai/connection-slack');
+    });
+    it('is idempotent — second commit returns alreadyComplete: true with the same timestamp', async () => {
+        await upsertSetupState(db, agentId, scopeId, {
+            phase: 'configuring',
+            plan: makePlan(),
+        });
+        const r1 = await commitSetup({ db, fs, agentId, scopeId });
+        expect(r1.ok).toBe(true);
+        if (!r1.ok)
+            throw new Error('unreachable');
+        const r2 = await commitSetup({ db, fs, agentId, scopeId });
+        expect(r2.ok).toBe(true);
+        if (!r2.ok)
+            throw new Error('unreachable');
+        expect(r2.alreadyComplete).toBe(true);
+        expect(r2.completedAt.getTime()).toBe(r1.completedAt.getTime());
+    });
+    it('force: true commits even with missing required slots', async () => {
+        await upsertSetupState(db, agentId, scopeId, {
+            phase: 'configuring',
+            plan: makePlan({ slots: [slackSlot] }),
+        });
+        const result = await commitSetup({ db, fs, agentId, scopeId, force: true });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            throw new Error('unreachable');
+        // amodal.json was still written even without the Slack connection
+        // — this is the "user said skip Slack and finish anyway" path.
+        const written = await readFile(path.join(repoRoot, 'amodal.json'), 'utf-8');
+        expect(written.length).toBeGreaterThan(0);
+    });
+    it('returns not_ready with a clear warning when no Plan is attached', async () => {
+        // Edge case: row exists (from update_setup_state seeding planning
+        // phase) but no Plan ever got attached.
+        await upsertSetupState(db, agentId, scopeId, { phase: 'planning' });
+        const result = await commitSetup({ db, fs, agentId, scopeId });
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            throw new Error('unreachable');
+        expect(result.reason).toBe('not_ready');
+    });
+    it('does not write amodal.json when readiness fails', async () => {
+        await upsertSetupState(db, agentId, scopeId, {
+            phase: 'configuring',
+            plan: makePlan({ slots: [slackSlot] }),
+        });
+        const result = await commitSetup({ db, fs, agentId, scopeId });
+        expect(result.ok).toBe(false);
+        // The temp repo is fresh — no amodal.json should have been
+        // written when readiness blocked the commit.
+        await expect(readFile(path.join(repoRoot, 'amodal.json'), 'utf-8')).rejects.toThrow();
+    });
+    it('survives a concurrent double-commit: first wins, second sees alreadyComplete', async () => {
+        // Phase E.2 risk from the build plan: "Agent fires
+        // request_complete_setup at the same instant the user clicks
+        // Finish setup. Both reach commit_setup; first acquires the
+        // row lock and writes; second sees completed_at IS NOT NULL
+        // and returns alreadyComplete: true. Test this explicitly
+        // with two parallel HTTP calls."
+        await upsertSetupState(db, agentId, scopeId, {
+            phase: 'configuring',
+            plan: makePlan(),
+        });
+        const [r1, r2] = await Promise.all([
+            commitSetup({ db, fs, agentId, scopeId }),
+            commitSetup({ db, fs, agentId, scopeId }),
+        ]);
+        // Both succeed.
+        expect(r1.ok).toBe(true);
+        expect(r2.ok).toBe(true);
+        if (!r1.ok || !r2.ok)
+            throw new Error('unreachable');
+        // Exactly one was the canonical write; the other reports
+        // alreadyComplete: true. Both report the same timestamp
+        // (the second is reading the row the first wrote).
+        const canonical = r1.alreadyComplete ? r2 : r1;
+        const followUp = r1.alreadyComplete ? r1 : r2;
+        expect(canonical.alreadyComplete).toBe(false);
+        expect(followUp.alreadyComplete).toBe(true);
+        expect(canonical.completedAt.getTime()).toBe(followUp.completedAt.getTime());
+        // The amodal.json that landed is well-formed (only one writer
+        // — the second branch early-returned before writing).
+        const written = await readFile(path.join(repoRoot, 'amodal.json'), 'utf-8');
+        const parsed = JSON.parse(written);
+        expect(parsed.name).toBeTruthy();
+        expect(parsed.version).toBeTruthy();
+    });
+    it('concurrent commits with one force=true still resolve idempotently', async () => {
+        // Edge case: the agent calls request_complete_setup (force:
+        // false) at the same time the user clicks Finish anyway
+        // (force: true). Whichever lands first wins; the other
+        // returns alreadyComplete: true. Force flag is irrelevant
+        // post-completion since completedAt is already set.
+        await upsertSetupState(db, agentId, scopeId, {
+            phase: 'configuring',
+            plan: makePlan(),
+        });
+        const [r1, r2] = await Promise.all([
+            commitSetup({ db, fs, agentId, scopeId, force: false }),
+            commitSetup({ db, fs, agentId, scopeId, force: true }),
+        ]);
+        expect(r1.ok).toBe(true);
+        expect(r2.ok).toBe(true);
+        if (!r1.ok || !r2.ok)
+            throw new Error('unreachable');
+        expect(r1.completedAt.getTime()).toBe(r2.completedAt.getTime());
+    });
+});
+describe('composeAmodalJson (unit)', () => {
+    it('builds a config from name + packages with template first', () => {
+        const config = composeAmodalJson({
+            phase: 'configuring',
+            currentStep: null,
+            completed: [
+                {
+                    slotLabel: 'Slack',
+                    packageName: '@amodalai/connection-slack',
+                    connectedAt: '2026-04-30T10:00:00Z',
+                    validatedAt: '2026-04-30T10:00:05Z',
+                    validationFormatted: 'Found 12',
+                },
+            ],
+            skipped: [],
+            configAnswers: {},
+            deferredRequests: [],
+            providedContext: {},
+            plan: makePlan({
+                templatePackage: '@amodalai/marketing-ops',
+                completion: { title: 'Marketing Ops', suggestions: [], automationTitle: null },
+            }),
+        }, makePlan({
+            templatePackage: '@amodalai/marketing-ops',
+            completion: { title: 'Marketing Ops', suggestions: [], automationTitle: null },
+        }));
+        expect(config.name).toBe('marketing-ops');
+        expect(config.packages).toEqual(['@amodalai/marketing-ops', '@amodalai/connection-slack']);
+    });
+    it('falls back to "agent" when the completion title is empty', () => {
+        const config = composeAmodalJson({
+            phase: 'configuring',
+            currentStep: null,
+            completed: [],
+            skipped: [],
+            configAnswers: {},
+            deferredRequests: [],
+            providedContext: {},
+            plan: null,
+        }, null);
+        expect(config.name).toBe('agent');
+        expect(config.packages).toBeUndefined();
+    });
+    it('dedupes packages across the template + completed list', () => {
+        const config = composeAmodalJson({
+            phase: 'configuring',
+            currentStep: null,
+            completed: [
+                {
+                    slotLabel: 'Slack',
+                    packageName: '@amodalai/connection-slack',
+                    connectedAt: 'x',
+                    validatedAt: null,
+                    validationFormatted: null,
+                },
+                {
+                    slotLabel: 'Slack DM',
+                    packageName: '@amodalai/connection-slack',
+                    connectedAt: 'x',
+                    validatedAt: null,
+                    validationFormatted: null,
+                },
+            ],
+            skipped: [],
+            configAnswers: {},
+            deferredRequests: [],
+            providedContext: {},
+            plan: makePlan({ templatePackage: '@amodalai/connection-slack' }),
+        }, makePlan({ templatePackage: '@amodalai/connection-slack' }));
+        // Single occurrence even though it appeared 3 times across template + completed.
+        expect(config.packages).toEqual(['@amodalai/connection-slack']);
+    });
+});
+//# sourceMappingURL=commit-setup.test.js.map

package/dist/src/setup/commit-setup.test.js.map

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

package/dist/src/tools/README.md

@@ -0,0 +1,270 @@
+<!--
+Copyright 2026 Amodal Labs, Inc.
+SPDX-License-Identifier: MIT
+-->
+
+# Custom-tool SDK
+
+Public API for tools shipped inside agent packages — `agent-admin`,
+`connection-*`, `template-*`, and any third-party agent the registry
+points to. Every tool that wants to do more than return a string
+(emit inline UI, read or write files, run a query, make an HTTP call)
+goes through this surface.
+
+The SDK is maintained as **additive-only** post-launch. Existing
+fields and block types do not change shape — older tools keep working
+when the runtime upgrades, and the registry doesn't have to track
+per-package SDK versions.
+
+## Where tools live
+
+```
+<agent-package>/
+  package.json              ← amodal.permissions declares capabilities
+  tools/
+    my_tool/
+      tool.json             ← description + JSON Schema parameters
+      handler.ts            ← export default async (params, ctx) => …
+```
+
+The runtime walks `<agent-package>/tools/*/{tool.json, handler.ts}`
+on agent load. Every directory whose name matches `^[a-z][a-z0-9_]*$`
+becomes a tool the LLM can call. There is no separate registration
+step.
+
+## Writing a handler
+
+```ts
+// tools/show_preview/handler.ts
+import type { ToolContext } from "@amodalai/runtime/tools";
+
+export default async function showPreview(
+  params: { title: string; tagline: string },
+  ctx: ToolContext,
+): Promise<{ ok: true }> {
+  ctx.emit({
+    type: "block",
+    block: {
+      type: "agent_card_preview",
+      card: {
+        title: params.title,
+        tagline: params.tagline,
+        platforms: [],
+        thumbnailConversation: [],
+      },
+    },
+  });
+  return { ok: true };
+}
+```
+
+The first argument is the parameter object (validated against
+`tool.json#parameters` before the handler runs). The second is a
+[`ToolContext`](./context.ts) — the SDK surface this README documents.
+
+Pure-JS handlers work too — agent packages with no build step can ship
+a plain function and skip the `@amodalai/runtime` import. The runtime
+compiles `handler.ts` with esbuild on first call regardless.
+
+## `ToolContext` reference
+
+```ts
+interface ToolContext {
+  // Identity
+  agentId: string;
+  scopeId: string; // empty string = agent-level
+  scopeContext?: Record<string, string>;
+  sessionId: string;
+
+  // Side effects (always available)
+  emit(event: EmitEvent): void; // structured: text | block | error
+  log(message: string): void; // sugar for emit({type:'text', …})
+
+  // Capabilities (permission-gated)
+  fs: FsBackend;
+  db: ToolDbHandle;
+  fetch: typeof globalThis.fetch;
+
+  // Cancellation
+  signal: AbortSignal;
+}
+```
+
+### `ctx.emit(event)`
+
+Three event variants:
+
+- `{type: 'text', text}` — appended as agent prose alongside the LLM's stream.
+- `{type: 'block', block}` — dispatched into the inline-block list and rendered
+  by the widget (or by Studio's `inlineBlockRenderers` for Studio-only block
+  types like `connection_panel`).
+- `{type: 'error', message}` — surfaces an inline error notice and is logged
+  server-side.
+
+Block types are typed in [`@amodalai/types/blocks`](../../../types/src/blocks.ts)
+as a discriminated union — `text`, `ask_choice`, `agent_card_preview`,
+`connection_panel`, `proposal`, `update_plan`. Add a new variant by
+extending the union; the widget reducer keys off the `type` field.
+
+### `ctx.fs` — repo file access
+
+```ts
+ctx.fs.readRepoFile("amodal.json");
+ctx.fs.writeRepoFile("skills/digest/SKILL.md", body);
+ctx.fs.readManyRepoFiles(["a.json", "b.json"]);
+ctx.fs.listRepoFiles("skills/");
+ctx.fs.deleteRepoFile("skills/old-skill/SKILL.md");
+```
+
+All paths are repo-relative. Absolute paths and `..` traversal are
+rejected — the backend throws `FsSandboxError`. The same handler
+works against either backend the runtime selects via
+`AMODAL_REPO_MODE`:
+
+- `local` (default, `amodal dev`) — direct `fs/promises`, sub-ms.
+- `cloud` — proxies through `cloud-phase-4/platform-api`'s
+  `/api/repo/files/*` routes (Phase 0G); ~20-50ms per write.
+
+Permission gates: `readRepoFile` / `readManyRepoFiles` / `listRepoFiles`
+require `fs.read`. `writeRepoFile` / `deleteRepoFile` require `fs.write`.
+
+### `ctx.db` — Drizzle handle
+
+```ts
+const rows = await ctx.db.execute({
+  sql: "SELECT * FROM setup_state WHERE agent_id = $1",
+  params: [ctx.agentId],
+});
+```
+
+Scoped to the agent's session. Phase B introduces per-domain query
+modules at `@amodalai/db/queries/<domain>.ts` (the Midday pattern); use
+those over raw SQL when one exists.
+
+Permission gate: any call to `ctx.db.execute` requires both `db.read`
+and `db.write` — the SDK can't reliably parse SQL to know which is
+which, so the conservative gate is "declare both if you touch the DB
+at all." Phase B may split into `query()` / `mutate()` once we see how
+db tools shake out in practice.
+
+### `ctx.fetch` — outbound HTTP
+
+Same signature as `globalThis.fetch`. The runtime injects `ctx.signal`
+when the caller doesn't pass one, so outbound requests cancel with the
+tool invocation.
+
+Permission gate: `net.fetch`.
+
+## Declaring permissions
+
+In the agent package's `package.json`:
+
+```json
+{
+  "name": "@amodalai/agent-admin",
+  "amodal": {
+    "permissions": ["fs.read", "fs.write", "db.read", "db.write"]
+  }
+}
+```
+
+Default-deny: a package with no `amodal.permissions` block gets an
+empty list, and any tool inside it that reaches for a privileged
+`ctx.*` capability throws `PermissionError` at the boundary, naming
+the tool, the missing permission, and the package.
+
+Available tiers:
+
+- `fs.read` / `fs.write` — repo file access.
+- `db.read` / `db.write` — Drizzle `ctx.db.execute`.
+- `net.fetch` — outbound HTTP.
+
+Notably **not present**: `secrets.*`. Credentials enter the system in
+exactly two places — the Configure modal (`POST /api/secrets/:name`)
+and the OAuth callback (`/api/oauth/callback`). The SDK has no
+`ctx.saveSecret` and never will. Tools never see tokens in args, in
+chat history, or in the LLM's context window. If your tool needs a
+secret to talk to a third party, read it from `process.env` at runtime
+through the connection package's auth surface — never accept it as a
+parameter from the LLM.
+
+## Common patterns
+
+### Emit a block from a handler
+
+```ts
+ctx.emit({
+  type: "block",
+  block: {
+    type: "ask_choice",
+    askId: `choice_${ctx.sessionId}_${Date.now().toString(36)}`,
+    question: "When should the digest run?",
+    options: [
+      { label: "Monday 8 AM", value: "monday-8am" },
+      { label: "Friday 4 PM", value: "friday-4pm" },
+    ],
+  },
+});
+```
+
+### Read setup state from the DB (Phase B onward)
+
+```ts
+const rows = await ctx.db.execute({
+  sql: "SELECT * FROM setup_state WHERE agent_id = $1 AND scope_id = $2",
+  params: [ctx.agentId, ctx.scopeId],
+});
+```
+
+### Write a config file
+
+```ts
+await ctx.fs.writeRepoFile(
+  "amodal.json",
+  JSON.stringify({ ...config, packages: [...config.packages, name] }, null, 2) +
+    "\n",
+);
+```
+
+### Make an outbound HTTP call
+
+```ts
+const res = await ctx.fetch("https://api.example.com/probe", {
+  headers: { Authorization: `Bearer ${process.env.MY_TOKEN}` },
+});
+const data = (await res.json()) as { count: number };
+```
+
+## Errors
+
+- `PermissionError` — a `ctx.*` method was called without the matching
+  permission declared. Message names tool / package / permission so
+  the package author can fix the manifest in one place.
+- `FsSandboxError` — a path resolved outside the repo root. Callers
+  should treat this as a bug, not a recoverable failure.
+
+Both extend `Error` and are exported from `@amodalai/runtime/tools`.
+
+## Versioning
+
+The SDK ships in `@amodalai/runtime`. Subpath import:
+
+```ts
+import type { ToolContext } from "@amodalai/runtime/tools";
+import {
+  PermissionError,
+  FsSandboxError,
+  LocalFsBackend,
+} from "@amodalai/runtime/tools";
+```
+
+Treat the block-type union and the `ToolContext` interface as
+**additive-only**. New phases extend; they do not rename or remove.
+
+## Related
+
+- **Connection validation probes** (Phase A) — the contract a connection
+  package's `validate.js` follows so the admin agent's
+  `validate_connection` tool can surface a real-data sanity check after
+  Connect. Documented in
+  [`@amodalai/core/cards/README.md`](../../../core/src/cards/README.md#connection-validation-probes).

package/dist/src/tools/admin-tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ToolRegistry } from './types.js';
+import type { Logger } from '../logger.js';
+export interface AdminToolsOptions {
+    /** Path to the agent repo — `install_package` writes amodal.json here. */
+    repoRoot: string;
+    /** npm registry base URL. Defaults to npmjs.org; tests override. */
+    registryUrl?: string;
+    logger: Logger;
+}
+export declare function registerAdminTools(registry: ToolRegistry, opts: AdminToolsOptions): void;
+interface SearchHit {
+    name: string;
+    version: string;
+    description: string;
+    keywords: string[];
+}
+/**
+ * Pull the relevant fields from npm's `/-/v1/search` response. The response
+ * shape is `{ objects: [{ package: { name, version, description, keywords } }] }`.
+ */
+export declare function extractSearchHits(raw: unknown): SearchHit[];
+export {};