@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/recall/index.js

@@ -2,7 +2,7 @@ import { embedMany, tool } from "ai";
 import { z } from "zod";
 import { createWorkersAI } from "workers-ai-provider";
 import { definePlugin } from "@dynamicagents/core";
-import { parseTurn, sessionText } from "@dynamicagents/core/agent";
+import { gatewayLogFields, parseTurn, sessionText } from "@dynamicagents/core/agent";
 /**
  * `@dynamicagents/plugins/recall` — episodic memory over Cloudflare Vectorize.
  *
@@ -14,11 +14,11 @@ import { parseTurn, sessionText } from "@dynamicagents/core/agent";
  * context window.
  *
  * Core carries **no embedding code at all**: no `Embed` type, no
- * `embeddingModelId`, no recall config. It used to, without a single caller, and
- * that had fixed the shape of embedding for every future plugin — one model, one
- * dimension, `string[] → number[][]` — while `ModelConfig` could only say "the
- * agent has an embedding model" when the true statement is "*this plugin* uses
- * this embedding model". So the whole embedding path lives here.
+ * `embeddingModelId`, no recall config. Putting any of it there fixes the shape
+ * of embedding for every future plugin — one model, one dimension,
+ * `string[] → number[][]` — and lets `ModelConfig` say only "the agent has an
+ * embedding model" when the true statement is "*this plugin* uses this embedding
+ * model". So the whole embedding path lives here.
  *
  * The namespace is always bound in code from the caller's verified identity,
  * never model input, so one caller can never read another's archive.
@@ -101,24 +101,34 @@ export async function recallSearch(index, namespace, query, embed, topK = DEFAUL
     });
 }
 export function recall(config) {
-    const { ai, index, namespace, aiGatewayId, embeddingModelId = DEFAULT_EMBEDDING_MODEL_ID, topK = DEFAULT_TOP_K, metadataTextMax = DEFAULT_METADATA_TEXT_MAX } = config;
+    const { ai, index, namespace, aiGatewayId, agentName, embeddingModelId = DEFAULT_EMBEDDING_MODEL_ID, topK = DEFAULT_TOP_K, metadataTextMax = DEFAULT_METADATA_TEXT_MAX } = config;
     /**
      * Built on first use, never at module scope. Cloudflare evaluates module scope
      * during `wrangler deploy` to validate the new version, and bindings are not
      * populated at that point — constructing eagerly makes `createWorkersAI` throw
      * "you must provide either a binding or credentials".
+     *
+     * The gateway goes on the embedding model and never on the provider — see
+     * core's Workers AI runtime for why setting it on both discards the model's.
+     * Only `agent` and `phase` are known here: one call embeds a whole displaced
+     * range, which can span channels, or a query the model wrote.
      */
     let provider;
+    const embeddingSettings = aiGatewayId
+        ? {
+            gateway: {
+                id: aiGatewayId,
+                ...gatewayLogFields({ agent: agentName, phase: "embed" })
+            }
+        }
+        : {};
     const embed = config.embed ??
         (async (texts) => {
             if (texts.length === 0)
                 return [];
-            provider ??= createWorkersAI({
-                binding: ai,
-                ...(aiGatewayId ? { gateway: { id: aiGatewayId } } : {})
-            });
+            provider ??= createWorkersAI({ binding: ai });
             const { embeddings } = await embedMany({
-                model: provider.embedding(embeddingModelId),
+                model: provider.embedding(embeddingModelId, embeddingSettings),
                 values: texts
             });
             return embeddings;

package/dist/repo/checkout.d.ts

@@ -21,8 +21,8 @@ interface RefreshOutcome {
 /**
  * What this module needs back from a git command.
  *
- * A structural subset of `index.ts`'s `RunResult` rather than an import of it,
- * so the dependency runs one way: `index.ts` knows about this file, and this file
+ * A structural subset of `context.ts`'s `RunResult` rather than an import of it,
+ * so the dependency runs one way: the tools know about this file, and this file
  * knows only about the shape of an answer. `unreachable` is the field that earns
  * the type — a command that *ran and failed* has answered the question it was
  * asked, and one that never ran has answered nothing, which two refusals below
@@ -34,7 +34,7 @@ export interface GitAnswer {
     stderr: string;
     unreachable?: true;
 }
-/** The two runners `refreshCheckout` borrows from `repoSurface`. */
+/** The two runners `refreshCheckout` borrows from `repoContext`. */
 export interface GitRunners {
     plain: (args: string, cwd: string, vars?: Record<string, string>) => Promise<GitAnswer>;
     /**
@@ -64,6 +64,32 @@ export declare function resolveDefaultBranch(plain: GitRunners["plain"], dir: st
     branch?: string;
     unreachable?: string;
 }>;
+/**
+ * Write the identity this checkout's commits carry into its own config.
+ *
+ * **Repo-local, and repeated on every clone and every refresh.** The workspace
+ * outlives the deployment's configuration: written once, at the clone, it is
+ * frozen — change the configured name and every checkout that already exists
+ * goes on committing under the old one, with nothing in the tree saying why.
+ * Rewriting costs two commands against a checkout that is being set up anyway.
+ *
+ * It is the *nearest* answer, not the only one. `repo_commit` names the identity
+ * on the commit itself, which is the one layer a stale config cannot outrank.
+ * Underneath, a repository this plugin never cloned falls back to whatever the
+ * shell's own git is configured with — which is an identity rather than nothing
+ * only where `exec` is backed by the computer plugin, whose workspace writes one
+ * per container; see
+ * {@link file://../computer/host/git-identity.ts}. `exec` is an arbitrary
+ * runner, so that is a property of a deployment, not of this plugin.
+ *
+ * Unchecked, like the config pins at the clone: git's identity is needed by the
+ * first commit, and a failure to write it fails that commit with a sentence far
+ * clearer than anything this could report from here.
+ */
+export declare function writeGitIdentity(plain: GitRunners["plain"], dir: string, author: {
+    name: string;
+    email: string;
+}): Promise<void>;
 /**
  * Bring an existing checkout back to a clean, current state.
  *
@@ -78,9 +104,13 @@ export declare function resolveDefaultBranch(plain: GitRunners["plain"], dir: st
  * one outcome nobody could recover from. Refusing costs a round; discarding
  * costs the work.
  */
-export declare function refreshCheckout({ dir, url, branch, plain, fetchOrigin }: GitRunners & {
+export declare function refreshCheckout({ dir, url, branch, author, plain, fetchOrigin }: GitRunners & {
     dir: string;
     url: string;
     branch: string | undefined;
+    author: {
+        name: string;
+        email: string;
+    };
 }): Promise<RefreshOutcome>;
 export {};

package/dist/repo/checkout.js

@@ -21,6 +21,36 @@ export async function resolveDefaultBranch(plain, dir) {
         ? { branch: head.stdout.trim().replace(/^origin\//, "") }
         : {};
 }
+/**
+ * Write the identity this checkout's commits carry into its own config.
+ *
+ * **Repo-local, and repeated on every clone and every refresh.** The workspace
+ * outlives the deployment's configuration: written once, at the clone, it is
+ * frozen — change the configured name and every checkout that already exists
+ * goes on committing under the old one, with nothing in the tree saying why.
+ * Rewriting costs two commands against a checkout that is being set up anyway.
+ *
+ * It is the *nearest* answer, not the only one. `repo_commit` names the identity
+ * on the commit itself, which is the one layer a stale config cannot outrank.
+ * Underneath, a repository this plugin never cloned falls back to whatever the
+ * shell's own git is configured with — which is an identity rather than nothing
+ * only where `exec` is backed by the computer plugin, whose workspace writes one
+ * per container; see
+ * {@link file://../computer/host/git-identity.ts}. `exec` is an arbitrary
+ * runner, so that is a property of a deployment, not of this plugin.
+ *
+ * Unchecked, like the config pins at the clone: git's identity is needed by the
+ * first commit, and a failure to write it fails that commit with a sentence far
+ * clearer than anything this could report from here.
+ */
+export async function writeGitIdentity(plain, dir, author) {
+    // Through the environment, so a configured name containing a quote stays a
+    // value rather than becoming shell.
+    await plain(`config user.name "$GIT_NAME"`, dir, { GIT_NAME: author.name });
+    await plain(`config user.email "$GIT_EMAIL"`, dir, {
+        GIT_EMAIL: author.email
+    });
+}
 /**
  * Bring an existing checkout back to a clean, current state.
  *
@@ -35,7 +65,7 @@ export async function resolveDefaultBranch(plain, dir) {
  * one outcome nobody could recover from. Refusing costs a round; discarding
  * costs the work.
  */
-export async function refreshCheckout({ dir, url, branch, plain, fetchOrigin }) {
+export async function refreshCheckout({ dir, url, branch, author, plain, fetchOrigin }) {
     const remote = await plain("remote get-url origin", dir);
     // Interrogated, for the same reason the `status` below is: a question that went
     // unanswered is not the answer "some other repository". Read as one, an
@@ -59,6 +89,11 @@ export async function refreshCheckout({ dir, url, branch, plain, fetchOrigin })
                 `not ${url}. Pick a different directory or work with the checkout that is there.`
         };
     }
+    // Ahead of every refusal below, and deliberately: a refusal leaves the *tree*
+    // untouched, which is what those sentences promise. An identity is not tree
+    // state, and a dirty tree is the case where somebody is about to commit —
+    // exactly when a stale name would be spent.
+    await writeGitIdentity(plain, dir, author);
     // Interrogated, not assumed. Empty stdout from a `status` that *failed* is not
     // a clean tree, it is no answer at all — and the next two commands are `fetch`
     // and `reset --hard`. Conflating the two lets a permissions error or a

package/dist/repo/context.d.ts

@@ -0,0 +1,109 @@
+import type { RepoCheckout, RepoConfig, RepoExec, RepoGitResult } from "./index.js";
+/**
+ * How many items one forge list call asks for. GitHub's maximum, and its default
+ * without this is 30.
+ *
+ * One page, never a Link-header walk: an unbounded fetch loop does not belong
+ * inside a model turn, and the render is bounded by `maxOutputChars` anyway. What
+ * matters is that a full page is *reported* as possibly partial rather than
+ * presented as the whole answer — a pull request's newest review comments are on
+ * the last page, and those are exactly the ones an agent was sent to act on.
+ */
+export declare const FORGE_PAGE_SIZE = 100;
+/**
+ * Where GraphQL lives, given where REST does.
+ *
+ * On github.com they share an origin and `/graphql` hangs off it. On GitHub
+ * Enterprise — which {@link RepoConfig.apiBase} exists for — REST is under
+ * `/api/v3` and GraphQL is its **sibling** at `/api/graphql`, not a path beneath
+ * it. Appending blindly yields `/api/v3/graphql`, which is a 404 on every
+ * Enterprise install and no failure at all on the public API, so the mistake
+ * survives every test written against github.com.
+ */
+export declare function graphqlEndpoint(apiBase: string): string;
+/**
+ * Middle-out truncation, so both the head of a diff and its tail survive.
+ *
+ * Deliberately a **copy** of the computer plugin's function of the same name,
+ * not an import. `npm run verify:exports` fails any subpath whose module graph
+ * reaches a sibling's directory, and its own advice for a shared helper is to
+ * duplicate it — installing `repo` must not drag `computer` (and therefore
+ * `@cloudflare/computer`) into a consumer's bundle. Fifteen lines is a cheaper
+ * price than that coupling, and it is the same reason `exec` is injected here
+ * rather than imported.
+ *
+ * The `half < 1` guard is not padding: without it a small `max` makes `half`
+ * zero or negative, and `slice(-0)` is `slice(0)` — the whole string — so the
+ * function would return *more* than it was given.
+ */
+export declare function truncateOutput(text: string, max: number): string;
+/**
+ * What one container command produced — plus one bit the container did not.
+ *
+ * `exec` does not only *return* failures, it throws them: `@cloudflare/computer`
+ * throws `EEXEC_LOST` when a container is replaced mid-command, and any call to a
+ * Durable Object can fail outright. Both are caught at the seam
+ * ({@link repoContext}'s `run`) and turned into a failed result, so every tool
+ * answers in its own `!success` branch — "could not read the status of /w/r: …"
+ * is a better sentence than any wrapper one level up could write, and a seventh
+ * tool calling `plain` gets it without being told.
+ *
+ * `unreachable` is for the branches that must tell the two apart. A command that
+ * ran and failed has answered the question it was asked; a command that never ran
+ * has answered nothing, and three places here read a failure as an answer.
+ */
+export type RunResult = Awaited<ReturnType<RepoExec>> & {
+    unreachable?: true;
+};
+/** What {@link repoContext} hands each group of tools. */
+export interface RepoContext {
+    config: RepoConfig;
+    workdir: string;
+    author: {
+        name: string;
+        email: string;
+    };
+    allowedHosts: string[];
+    bounded: (text: string) => string;
+    notifyCheckout: (checkout: RepoCheckout) => Promise<void>;
+    logFailure: (tool: string, detail: {
+        exitCode?: number;
+        stderr?: string;
+        stdout?: string;
+    }) => void;
+    plain: (args: string, cwd: string, vars?: Record<string, string>) => Promise<RunResult>;
+    runGit: (op: () => Promise<RepoGitResult>) => Promise<RunResult>;
+    fetchOrigin: (dir: string, url: string) => Promise<RunResult>;
+    pushBranch: (dir: string, url: string, branch: string) => Promise<RunResult>;
+    origin: (dir: string) => Promise<{
+        remote?: {
+            host: string;
+            url: string;
+        };
+        unreachable?: string;
+    }>;
+    forge: (tool: string, path: string, init?: {
+        method: string;
+        body: unknown;
+    }) => Promise<{
+        ok: true;
+        data: unknown;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    forgeGraphql: (tool: string, query: string, variables: Record<string, unknown>) => Promise<{
+        ok: true;
+        data: unknown;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    forgeRepo: (dir: string) => Promise<{
+        owner: string;
+        repo: string;
+    } | {
+        refusal: string;
+    }>;
+}
+export declare function repoContext(config: RepoConfig, runtime?: unknown): RepoContext;