@agent-native/core 0.113.0 → 0.114.1

package/src/scripts/dev/shell.ts

@@ -0,0 +1,111 @@
+import { execSync } from "node:child_process";
+import path from "node:path";
+
+import type { ActionTool } from "../../agent/types.js";
+import {
+  getRequestOrgId,
+  getRequestTimezone,
+  getRequestUserEmail,
+  getRequestUserName,
+  hasRequestContext,
+} from "../../server/request-context.js";
+import { parseArgs } from "../utils.js";
+
+const MAX_OUTPUT = 50_000;
+const TIMEOUT_MS = 30_000;
+
+export const tool: ActionTool = {
+  description:
+    "Run a shell command and return the output. Use for build commands, git operations, package management, or any CLI task. Has a 30-second timeout.",
+  parameters: {
+    type: "object",
+    properties: {
+      command: {
+        type: "string",
+        description: "The shell command to execute",
+      },
+      cwd: {
+        type: "string",
+        description:
+          "Working directory for the command (default: project root)",
+      },
+    },
+    required: ["command"],
+  },
+};
+
+export async function run(args: Record<string, string>): Promise<string> {
+  const command = args.command;
+  if (!command) return "Error: command is required";
+
+  const cwd = args.cwd ? path.resolve(process.cwd(), args.cwd) : process.cwd();
+  const env = childProcessEnvForRequest();
+
+  try {
+    const output = execSync(command, {
+      cwd,
+      timeout: TIMEOUT_MS,
+      encoding: "utf-8",
+      maxBuffer: 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+      env,
+    });
+
+    let result = output;
+    if (result.length > MAX_OUTPUT) {
+      result = result.slice(0, MAX_OUTPUT) + "\n... (output truncated at 50KB)";
+    }
+    return result || "(no output)";
+  } catch (err: any) {
+    let output = "";
+    if (err?.stdout) output += err.stdout;
+    if (err?.stderr) output += (output ? "\n" : "") + err.stderr;
+    if (!output) output = err?.message ?? String(err);
+
+    if (output.length > MAX_OUTPUT) {
+      output = output.slice(0, MAX_OUTPUT) + "\n... (output truncated)";
+    }
+
+    // Throw so the agent framework marks this as isError:true, preventing the
+    // agent from synthesizing a success narrative when the command failed.
+    throw new Error(`Command failed (exit ${err?.status ?? "?"})\n${output}`);
+  }
+}
+
+function childProcessEnvForRequest(): NodeJS.ProcessEnv {
+  const env = { ...process.env, FORCE_COLOR: "0" };
+  const requestScoped = hasRequestContext();
+  const userEmail = getRequestUserEmail();
+  const userName = getRequestUserName();
+  const orgId = getRequestOrgId();
+  const timezone = getRequestTimezone();
+
+  setOrClearRequestEnv(env, "AGENT_USER_EMAIL", userEmail, requestScoped);
+  setOrClearRequestEnv(env, "AGENT_USER_NAME", userName, requestScoped);
+  setOrClearRequestEnv(env, "AGENT_ORG_ID", orgId, requestScoped);
+  setOrClearRequestEnv(env, "AGENT_USER_TIMEZONE", timezone, requestScoped);
+
+  return env;
+}
+
+function setOrClearRequestEnv(
+  env: NodeJS.ProcessEnv,
+  key: string,
+  value: string | undefined,
+  requestScoped: boolean,
+) {
+  if (value) {
+    env[key] = value;
+  } else if (requestScoped) {
+    delete env[key];
+  }
+}
+
+export default async function main(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+  if (!parsed.command) {
+    console.error("Usage: shell --command <cmd> [--cwd <dir>]");
+    throw new Error("Script failed");
+  }
+  console.log(await run(parsed));
+}

package/src/scripts/dev/write-file.ts

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { ActionTool } from "../../agent/types.js";
+import { parseArgs } from "../utils.js";
+
+export const tool: ActionTool = {
+  description:
+    "Write content to a file. Creates the file if it doesn't exist, or overwrites it. Creates parent directories automatically.",
+  parameters: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "File path relative to the project root",
+      },
+      content: {
+        type: "string",
+        description: "The content to write to the file",
+      },
+    },
+    required: ["path", "content"],
+  },
+};
+
+export async function run(args: Record<string, string>): Promise<string> {
+  const filePath = args.path;
+  const content = args.content;
+  if (!filePath) return "Error: path is required";
+  if (content === undefined) return "Error: content is required";
+
+  const resolved = path.resolve(process.cwd(), filePath);
+
+  try {
+    const dir = path.dirname(resolved);
+    fs.mkdirSync(dir, { recursive: true });
+
+    const existed = fs.existsSync(resolved);
+    fs.writeFileSync(resolved, content, "utf-8");
+
+    const bytes = Buffer.byteLength(content, "utf-8");
+    const lines = content.split("\n").length;
+    return `${existed ? "Updated" : "Created"} ${filePath} (${lines} lines, ${bytes} bytes)`;
+  } catch (err: any) {
+    return `Error: ${err?.message ?? String(err)}`;
+  }
+}
+
+export default async function main(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+  if (!parsed.path || parsed.content === undefined) {
+    console.error("Usage: write-file --path <file> --content <text>");
+    throw new Error("Script failed");
+  }
+  console.log(await run(parsed));
+}

package/src/scripts/dev-session.ts

@@ -0,0 +1,96 @@
+/**
+ * Dev-only session bootstrap for `pnpm action <name>` (and any other CLI
+ * caller of `runScript`).
+ *
+ * After changes-53, db-exec / db-query / db-patch refuse to run unless
+ * `getRequestUserEmail()` returns a real identity. In an HTTP request the
+ * Nitro plugin wraps the handler in `runWithRequestContext({ userEmail })`
+ * so scoping just works. CLI invocations have no such wrapper, so without
+ * this helper every db-* CLI run hands the user a stack trace.
+ *
+ * What this does: when the runner is about to dispatch, resolve a real
+ * email from the legacy `sessions` table (the same table that
+ * `addSession()` writes from google-oauth.ts and the A2A receiver fallback
+ * already consults). The runner then wraps dispatch in
+ * `runWithRequestContext({ userEmail })` so the action sees a real identity.
+ *
+ * SHARED-DEV-BOX CAVEAT: this table is unscoped. To avoid silently binding
+ * to another developer, auto-binding only happens when the table contains
+ * exactly one distinct real email. If multiple developers have signed in,
+ * set `AGENT_USER_EMAIL=<your-email>` in your shell or `.env`; explicit env
+ * always wins.
+ *
+ * Strict gating mirrors the A2A precedent in
+ * `server/agent-chat-plugin.ts` (search for "latest session"):
+ *   - NODE_ENV !== "production".
+ *   - AUTH_MODE unset or === "local" — don't auto-impersonate when an
+ *     admin or hosted auth mode is in use.
+ *
+ * If `process.env.AGENT_USER_EMAIL` is already set we return it unchanged
+ * — explicit env wins over any DB-derived guess (matches how
+ * `getRequestUserEmail()` itself behaves).
+ */
+
+const DEV_FALLBACK_EMAIL = "local@localhost"; // guard:allow-localhost-fallback — sentinel intentionally rejected so the resolver doesn't return it
+
+/**
+ * Resolve the local dev user's email for the current CLI invocation.
+ *
+ * Returns the resolved email, or `undefined` when no real identity is
+ * available. Callers should let the downstream "no authenticated user"
+ * error propagate — its message points the user at the two fixes
+ * (sign in via the running app, or set `AGENT_USER_EMAIL`).
+ */
+export async function resolveDevUserEmail(): Promise<string | undefined> {
+  const explicit = process.env.AGENT_USER_EMAIL;
+  if (explicit) return explicit;
+
+  // Hard refusal: this helper must never source identity in prod.
+  if (process.env.NODE_ENV === "production") return undefined;
+
+  // AUTH_MODE may be unset (default dev shim) or "local". Anything else
+  // means a non-dev auth mode is in play; don't try to fish a session
+  // out of the DB on its behalf.
+  const authMode = process.env.AUTH_MODE;
+  if (authMode && authMode !== "local") return undefined;
+
+  try {
+    const { getDbExec } = await import("../db/client.js");
+    const { rows } = await getDbExec().execute({
+      sql: `SELECT email
+            FROM (
+              SELECT TRIM(email) AS email, MAX(created_at) AS last_seen
+              FROM sessions
+              WHERE email IS NOT NULL AND TRIM(email) <> ?
+              GROUP BY TRIM(email)
+            ) AS session_owners
+            WHERE email <> ''
+            ORDER BY last_seen DESC
+            LIMIT 2`,
+      args: [DEV_FALLBACK_EMAIL],
+    });
+    const emails = rows
+      .map((row) => (typeof row.email === "string" ? row.email.trim() : ""))
+      .filter((email) => email.length > 0);
+    if (emails.length === 0) return undefined;
+    if (emails.length > 1) {
+      console.warn(
+        `[dev-session] multiple session owners found (${emails.join(
+          ", ",
+        )}); set AGENT_USER_EMAIL=<email> to choose one`,
+      );
+      return undefined;
+    }
+    const email = emails[0];
+    console.log(
+      `[dev-session] auto-bound to ${email} (set AGENT_USER_EMAIL to override)`,
+    );
+    return email;
+  } catch {
+    // The sessions table doesn't exist yet (fresh install where the web
+    // server has never booted) or the DB isn't reachable. Either way,
+    // we can't produce an identity — let the caller throw with the
+    // friendlier "sign in first" hint.
+    return undefined;
+  }
+}

package/src/scripts/docs/index.ts

@@ -0,0 +1,8 @@
+export const coreDocsScripts: Record<
+  string,
+  (args: string[]) => Promise<void>
+> = {
+  "docs-search": (args) => import("./search.js").then((m) => m.default(args)),
+  "source-search": (args) =>
+    import("./source-search.js").then((m) => m.default(args)),
+};

package/src/scripts/docs/search.ts

@@ -0,0 +1,274 @@
+/**
+ * Core script: docs-search
+ *
+ * Search and read agent-native framework documentation.
+ * Docs are bundled in @agent-native/core so they're always the right version.
+ *
+ * Usage:
+ *   pnpm action docs-search --query "actions"
+ *   pnpm action docs-search --slug authentication
+ *   pnpm action docs-search --list
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { parseArgs } from "../utils.js";
+
+interface DocMeta {
+  slug: string;
+  title: string;
+  description: string;
+}
+
+interface DocFull extends DocMeta {
+  body: string;
+}
+
+function getDocsRoot(): string {
+  // Resolve from the package root:
+  //   src/scripts/docs/search.ts -> docs/
+  //   dist/scripts/docs/search.js -> docs/
+  return path.resolve(
+    path.dirname(new URL(import.meta.url).pathname),
+    "../../../docs",
+  );
+}
+
+function getDocsDir(): string {
+  return path.join(getDocsRoot(), "content");
+}
+
+function parseFrontmatter(raw: string): {
+  data: Record<string, string>;
+  body: string;
+} {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) return { data: {}, body: raw };
+
+  const data: Record<string, string> = {};
+  for (const line of match[1].split("\n")) {
+    const m = line.match(/^(\w+):\s*"?(.*?)"?\s*$/);
+    if (m) data[m[1]] = m[2];
+  }
+  return { data, body: match[2] };
+}
+
+function titleFromBody(body: string): string | null {
+  const heading = body.match(/^#\s+(.+?)\s*$/m);
+  return heading?.[1]?.trim() || null;
+}
+
+function isDocSourceFile(filename: string): boolean {
+  return filename.endsWith(".mdx") || filename.endsWith(".md");
+}
+
+function docSourcePathWithoutExtension(filename: string): string {
+  return filename.replace(/\.(?:mdx|md)$/, "");
+}
+
+function docSourceSlugFromFilename(filename: string): string {
+  return docSourcePathWithoutExtension(
+    filename.split(/[\\/]/).pop() ?? filename,
+  );
+}
+
+function preferMdxDocSourceFiles(files: string[]): string[] {
+  const byPath = new Map<string, string>();
+  for (const file of [...files].sort()) {
+    if (!isDocSourceFile(file)) continue;
+
+    const pathWithoutExtension = docSourcePathWithoutExtension(file);
+    const existing = byPath.get(pathWithoutExtension);
+    if (!existing || file.endsWith(".mdx")) {
+      byPath.set(pathWithoutExtension, file);
+    }
+  }
+  return Array.from(byPath.values()).sort((a, b) =>
+    docSourcePathWithoutExtension(a).localeCompare(
+      docSourcePathWithoutExtension(b),
+    ),
+  );
+}
+
+function loadMarkdownDoc(filePath: string, slug: string): DocFull {
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const { data, body } = parseFrontmatter(raw);
+  return {
+    slug,
+    title: data.title || data.name || titleFromBody(body) || slug,
+    description: data.description || "",
+    body,
+  };
+}
+
+function loadFilesystemDocs(): DocFull[] {
+  const docs: DocFull[] = [];
+  const rootDocs = [
+    { file: "AGENTS.md", slug: "agent-native-docs" },
+    { file: "SKILL.md", slug: "agent-native-docs-skill" },
+    { file: "README.md", slug: "agent-native-docs-readme" },
+  ];
+  for (const doc of rootDocs) {
+    const filePath = path.join(getDocsRoot(), doc.file);
+    if (fs.existsSync(filePath)) {
+      docs.push(loadMarkdownDoc(filePath, doc.slug));
+    }
+  }
+
+  const docsDir = getDocsDir();
+  if (!fs.existsSync(docsDir)) return docs;
+
+  const files = preferMdxDocSourceFiles(
+    fs
+      .readdirSync(docsDir)
+      .filter((file) => fs.statSync(path.join(docsDir, file)).isFile()),
+  );
+  docs.push(
+    ...files.map((file) => {
+      const slug = docSourceSlugFromFilename(file);
+      return loadMarkdownDoc(path.join(docsDir, file), slug);
+    }),
+  );
+  return docs;
+}
+
+function slugifyDocId(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+async function loadAgentBundleDocs(): Promise<DocFull[]> {
+  try {
+    const { loadAgentsBundle, getRuntimeSkills } =
+      await import("../../server/agents-bundle.js");
+    const bundle = await loadAgentsBundle();
+    const docs: DocFull[] = [];
+    if (bundle.workspaceAgentsMd?.trim()) {
+      docs.push({
+        slug: "agents-workspace",
+        title: "Workspace AGENTS.md",
+        description: "Full bundled workspace-level agent instructions.",
+        body: bundle.workspaceAgentsMd,
+      });
+    }
+    if (bundle.agentsMd?.trim()) {
+      docs.push({
+        slug: "agents-template",
+        title: "Template AGENTS.md",
+        description: "Full bundled template/app agent instructions.",
+        body: bundle.agentsMd,
+      });
+    }
+    // Only runtime-visible skills are searchable/readable here — `scope: dev`
+    // skills are meant for the human's coding agent (Claude Code), not the
+    // in-app runtime agent, so they must not appear in docs-search results.
+    for (const skill of getRuntimeSkills(bundle)) {
+      const slug = `skill-${slugifyDocId(skill.meta.name)}`;
+      docs.push({
+        slug,
+        title: `Skill: ${skill.meta.name}`,
+        description: skill.meta.description,
+        body: skill.content,
+      });
+    }
+    return docs;
+  } catch {
+    return [];
+  }
+}
+
+async function loadAllDocs(): Promise<DocFull[]> {
+  return [...loadFilesystemDocs(), ...(await loadAgentBundleDocs())];
+}
+
+async function searchDocs(query: string): Promise<DocMeta[]> {
+  const docs = await loadAllDocs();
+  const terms = query.toLowerCase().split(/\s+/);
+
+  const scored = docs
+    .map((doc) => {
+      const searchText =
+        `${doc.title} ${doc.description} ${doc.body}`.toLowerCase();
+      let score = 0;
+      for (const term of terms) {
+        if (doc.title.toLowerCase().includes(term)) score += 10;
+        if (doc.description.toLowerCase().includes(term)) score += 5;
+        if (doc.slug.includes(term)) score += 8;
+        // Count body occurrences
+        const bodyMatches = searchText.split(term).length - 1;
+        score += Math.min(bodyMatches, 5);
+      }
+      return { doc, score };
+    })
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  return scored.map(({ doc }) => ({
+    slug: doc.slug,
+    title: doc.title,
+    description: doc.description,
+  }));
+}
+
+export default async function docsSearchScript(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help === "true") {
+    console.log(`Usage: pnpm action docs-search [options]
+
+Options:
+  --query <text>    Search docs by keyword (returns matching pages)
+  --slug <slug>     Read a specific doc page by slug
+  --list            List all available doc pages
+  --help            Show this help message`);
+    return;
+  }
+
+  if (parsed.list === "true") {
+    const docs = await loadAllDocs();
+    const listing = docs.map((d) => ({
+      slug: d.slug,
+      title: d.title,
+      description: d.description,
+    }));
+    console.log(JSON.stringify(listing, null, 2));
+    return;
+  }
+
+  if (parsed.slug) {
+    const docs = await loadAllDocs();
+    const doc = docs.find((d) => d.slug === parsed.slug);
+    if (!doc) {
+      console.log(`Doc not found: ${parsed.slug}`);
+      console.log(`Available: ${docs.map((d) => d.slug).join(", ")}`);
+      return;
+    }
+    console.log(`# ${doc.title}\n`);
+    if (doc.description) console.log(`${doc.description}\n`);
+    console.log(doc.body);
+    return;
+  }
+
+  if (parsed.query) {
+    const results = await searchDocs(parsed.query);
+    if (results.length === 0) {
+      console.log(`No docs found matching "${parsed.query}".`);
+      return;
+    }
+    console.log(`Found ${results.length} doc(s) matching "${parsed.query}":\n`);
+    for (const result of results.slice(0, 8)) {
+      console.log(`  ${result.slug} — ${result.title}`);
+      if (result.description) {
+        console.log(`    ${result.description}`);
+      }
+    }
+    console.log(`\nUse --slug <slug> to read the full doc.`);
+    return;
+  }
+
+  console.log("Provide --query, --slug, or --list. Use --help for details.");
+}