@agent-native/core 0.113.0 → 0.114.1

package/src/scripts/resources/effective.ts

@@ -0,0 +1,71 @@
+/**
+ * Core script: resource-effective
+ *
+ * Show the workspace -> organization/app -> personal inheritance stack for a
+ * resource path and which layer is active.
+ *
+ * Usage:
+ *   pnpm action resource-effective --path <path> [--format json|text]
+ */
+
+import {
+  ensurePersonalDefaults,
+  resourceEffectiveContext,
+} from "../../resources/store.js";
+import { getRequestUserEmail } from "../../server/request-context.js";
+import { parseArgs, fail } from "../utils.js";
+
+export default async function resourceEffectiveScript(
+  args: string[],
+): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help === "true") {
+    console.log(`Usage: pnpm action resource-effective --path <path> [options]
+
+Options:
+  --path <path>        Resource path (required)
+  --format json|text   Output format (default: text)
+  --help               Show this help message`);
+    return;
+  }
+
+  const resourcePath = parsed.path;
+  if (!resourcePath) {
+    fail("--path is required. Example: --path instructions/guardrails.md");
+  }
+
+  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  if (!owner) {
+    fail(
+      "resource-effective requires an authenticated user (request context or AGENT_USER_EMAIL env var).",
+    );
+  }
+
+  await ensurePersonalDefaults(owner);
+  const context = await resourceEffectiveContext(owner, resourcePath);
+
+  if (parsed.format === "json") {
+    console.log(JSON.stringify(context, null, 2));
+    return;
+  }
+
+  console.log(`Effective resource: ${context.path}`);
+  console.log(`Active scope: ${context.effectiveScope ?? "none"}\n`);
+
+  for (const layer of context.layers) {
+    const state = layer.effective
+      ? "active"
+      : layer.overridden
+        ? "overridden"
+        : layer.exists
+          ? "available"
+          : "missing";
+    const updated = layer.resource?.updatedAt
+      ? `, updated ${new Date(layer.resource.updatedAt).toISOString()}`
+      : "";
+    console.log(
+      `- ${layer.label} (${layer.scope}): ${state}${layer.resource ? `, id ${layer.resource.id}${updated}` : ""}`,
+    );
+  }
+}

package/src/scripts/resources/index.ts

@@ -0,0 +1,18 @@
+export const coreResourceScripts: Record<
+  string,
+  (args: string[]) => Promise<void>
+> = {
+  "resource-list": (args) => import("./list.js").then((m) => m.default(args)),
+  "resource-read": (args) => import("./read.js").then((m) => m.default(args)),
+  "resource-effective": (args) =>
+    import("./effective.js").then((m) => m.default(args)),
+  "resource-write": (args) => import("./write.js").then((m) => m.default(args)),
+  "resource-delete": (args) =>
+    import("./delete.js").then((m) => m.default(args)),
+  "migrate-learnings": (args) =>
+    import("./migrate-learnings.js").then((m) => m.default(args)),
+  "save-memory": (args) =>
+    import("./save-memory.js").then((m) => m.default(args)),
+  "delete-memory": (args) =>
+    import("./delete-memory.js").then((m) => m.default(args)),
+};

package/src/scripts/resources/list.ts

@@ -0,0 +1,103 @@
+/**
+ * Core script: resource-list
+ *
+ * List resources stored in the SQL resource store.
+ *
+ * Usage:
+ *   pnpm action resource-list [--prefix <path>] [--scope personal|shared|workspace|all] [--format json|text] [--include-agent-scratch true]
+ */
+
+import {
+  resourceList,
+  resourceListAccessible,
+  ensurePersonalDefaults,
+  SHARED_OWNER,
+  WORKSPACE_OWNER,
+} from "../../resources/store.js";
+import { getRequestUserEmail } from "../../server/request-context.js";
+import { parseArgs, fail } from "../utils.js";
+
+export default async function resourceListScript(
+  args: string[],
+): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help === "true") {
+    console.log(`Usage: pnpm action resource-list [options]
+
+Options:
+  --prefix <path>              Filter by path prefix
+  --scope personal|shared|workspace|all
+                               Scope to list (default: all)
+  --format json|text           Output format (default: text)
+  --include-agent-scratch true Include hidden agent scratch files
+  --help                       Show this help message`);
+    return;
+  }
+
+  const prefix = parsed.prefix;
+  const scope = parsed.scope ?? "all";
+  const format = parsed.format ?? "text";
+  const includeAgentScratch =
+    parsed["include-agent-scratch"] === "true" ||
+    parsed.includeAgentScratch === "true" ||
+    parsed.includeScratch === "true";
+  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  if (!owner) {
+    fail(
+      "resource-list requires an authenticated user (request context or AGENT_USER_EMAIL env var).",
+    );
+  }
+
+  // Seed personal AGENTS.md + LEARNINGS.md on first access
+  if (scope !== "shared" && scope !== "workspace") {
+    await ensurePersonalDefaults(owner);
+  }
+
+  let resources;
+  if (scope === "personal") {
+    resources = includeAgentScratch
+      ? await resourceList(owner, prefix, { includeAgentScratch: true })
+      : await resourceList(owner, prefix);
+  } else if (scope === "shared") {
+    resources = includeAgentScratch
+      ? await resourceList(SHARED_OWNER, prefix, { includeAgentScratch: true })
+      : await resourceList(SHARED_OWNER, prefix);
+  } else if (scope === "workspace") {
+    resources = includeAgentScratch
+      ? await resourceList(WORKSPACE_OWNER, prefix, {
+          includeAgentScratch: true,
+        })
+      : await resourceList(WORKSPACE_OWNER, prefix);
+  } else {
+    resources = includeAgentScratch
+      ? await resourceListAccessible(owner, prefix, {
+          includeAgentScratch: true,
+        })
+      : await resourceListAccessible(owner, prefix);
+  }
+
+  if (format === "json") {
+    console.log(JSON.stringify(resources, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  if (resources.length === 0) {
+    console.log("No resources found.");
+    return;
+  }
+
+  console.log(`Resources: ${resources.length}\n`);
+
+  for (const r of resources) {
+    const ownerLabel =
+      r.owner === WORKSPACE_OWNER
+        ? "[workspace]"
+        : r.owner === SHARED_OWNER
+          ? "[shared]"
+          : `[${r.owner}]`;
+    const sizeLabel = r.size != null ? ` (${r.size} bytes)` : "";
+    console.log(`  ${r.path}  ${ownerLabel}${sizeLabel}  ${r.mimeType}`);
+  }
+}

package/src/scripts/resources/migrate-learnings.ts

@@ -0,0 +1,40 @@
+/**
+ * Core script: migrate-learnings
+ *
+ * Migrate a learnings.md file from the project root into the SQL resource
+ * store at SHARED scope under "LEARNINGS.md". This is the exact owner/path
+ * pair the live prompt injection (`loadResourcesForPrompt` in
+ * agent-chat-plugin.ts) reads via an exact-match lookup, so the migrated
+ * content actually reaches the production agent's prompt.
+ *
+ * Usage:
+ *   pnpm action migrate-learnings
+ */
+
+import fs from "fs";
+import path from "path";
+
+import { resourcePut, SHARED_OWNER } from "../../resources/store.js";
+
+export default async function migrateLearningsScript(
+  _args: string[],
+): Promise<void> {
+  const filePath = path.resolve(process.cwd(), "learnings.md");
+
+  if (!fs.existsSync(filePath)) {
+    console.log("No learnings.md found");
+    return;
+  }
+
+  const content = fs.readFileSync(filePath, "utf-8");
+
+  const resource = await resourcePut(
+    SHARED_OWNER,
+    "LEARNINGS.md",
+    content,
+    "text/markdown",
+  );
+  console.log(
+    `Migrated learnings.md to shared resource store as LEARNINGS.md (${resource.size} bytes)`,
+  );
+}

package/src/scripts/resources/read.ts

@@ -0,0 +1,107 @@
+/**
+ * Core script: resource-read
+ *
+ * Read a resource and output its content to stdout.
+ *
+ * Usage:
+ *   pnpm action resource-read --path <path> [--scope personal|shared|workspace]
+ */
+
+import {
+  resourceGetByPath,
+  ensurePersonalDefaults,
+  SHARED_OWNER,
+  WORKSPACE_OWNER,
+} from "../../resources/store.js";
+import { getRequestUserEmail } from "../../server/request-context.js";
+import { parseArgs, fail } from "../utils.js";
+
+export default async function resourceReadScript(
+  args: string[],
+): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help === "true") {
+    console.log(`Usage: pnpm action resource-read --path <path> [options]
+
+Options:
+  --path <path>            Resource path (required)
+  --scope personal|shared|workspace
+                           Scope to read from (default: personal, falls back to shared then workspace)
+  --help                   Show this help message`);
+    return;
+  }
+
+  const resourcePath = parsed.path;
+  if (!resourcePath) {
+    fail("--path is required. Example: --path LEARNINGS.md");
+  }
+
+  const scope = parsed.scope;
+  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  if (!owner) {
+    fail(
+      "resource-read requires an authenticated user (request context or AGENT_USER_EMAIL env var).",
+    );
+  }
+
+  // Seed personal AGENTS.md + LEARNINGS.md on first access
+  if (scope !== "shared" && scope !== "workspace") {
+    await ensurePersonalDefaults(owner);
+  }
+
+  if (scope === "workspace") {
+    const resource = await resourceGetByPath(WORKSPACE_OWNER, resourcePath);
+    if (!resource) {
+      console.log(
+        `Resource not found: ${resourcePath} (scope: workspace). Workspace resources are managed from Dispatch.`,
+      );
+      return;
+    }
+    process.stdout.write(resource.content);
+    return;
+  }
+
+  if (scope === "shared") {
+    const resource = await resourceGetByPath(SHARED_OWNER, resourcePath);
+    if (!resource) {
+      console.log(
+        `Resource not found: ${resourcePath} (scope: shared). You can create it with resource-write.`,
+      );
+      return;
+    }
+    process.stdout.write(resource.content);
+    return;
+  }
+
+  // Default: try personal first, then app/organization shared, then workspace.
+  const personal = await resourceGetByPath(owner, resourcePath);
+  if (personal) {
+    process.stdout.write(personal.content);
+    return;
+  }
+
+  if (scope === "personal") {
+    // Explicit personal scope — don't fall back
+    console.log(
+      `Resource not found: ${resourcePath} (scope: personal). You can create it with resource-write.`,
+    );
+    return;
+  }
+
+  const shared = await resourceGetByPath(SHARED_OWNER, resourcePath);
+  if (shared) {
+    process.stdout.write(shared.content);
+    return;
+  }
+
+  const workspace = await resourceGetByPath(WORKSPACE_OWNER, resourcePath);
+  if (workspace) {
+    process.stdout.write(workspace.content);
+    return;
+  }
+
+  console.log(
+    `Resource not found: ${resourcePath}. You can create it with resource-write.`,
+  );
+}

package/src/scripts/resources/save-memory.ts

@@ -0,0 +1,99 @@
+/**
+ * Core script: save-memory
+ *
+ * Create or update a structured memory entry and its index.
+ * Stores memory as a resource at `memory/<name>.md` (personal scope)
+ * and maintains a `memory/MEMORY.md` index.
+ */
+
+import { resourcePut, resourceGetByPath } from "../../resources/store.js";
+import { getRequestUserEmail } from "../../server/request-context.js";
+import { parseArgs, fail } from "../utils.js";
+
+const VALID_TYPES = ["user", "feedback", "project", "reference"] as const;
+
+const EMPTY_INDEX = `# Memory Index
+`;
+
+export default async function saveMemoryScript(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  const name = parsed.name;
+  if (!name) fail("--name is required (e.g. 'coding-style', 'project-alpha')");
+
+  const type = parsed.type;
+  if (!type || !VALID_TYPES.includes(type as any)) {
+    fail(`--type is required. Must be one of: ${VALID_TYPES.join(", ")}`);
+  }
+
+  const description = parsed.description;
+  if (!description) fail("--description is required (one-line summary)");
+
+  const content = parsed.content;
+  if (!content) fail("--content is required");
+
+  const owner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+  if (!owner) {
+    fail(
+      "save-memory requires an authenticated user (request context or AGENT_USER_EMAIL env var).",
+    );
+  }
+  const memoryPath = `memory/${name}.md`;
+  const indexPath = "memory/MEMORY.md";
+  const now = new Date().toISOString().slice(0, 10);
+
+  // Build the memory file with frontmatter
+  const fileContent = `---
+type: ${type}
+description: ${description}
+updated: ${now}
+---
+
+${content}`;
+
+  // Write the memory file
+  await resourcePut(owner, memoryPath, fileContent, "text/markdown");
+
+  // Update the index
+  let index: string;
+  try {
+    const existing = await resourceGetByPath(owner, indexPath);
+    index = existing?.content ?? EMPTY_INDEX;
+  } catch {
+    index = EMPTY_INDEX;
+  }
+
+  // Parse existing entries (simple line-based: `- [name](file) — description`)
+  const lines = index.split("\n");
+  const entryLine = `- [${name}](${name}.md) — ${description}`;
+  const entryPrefix = `- [${name}]`;
+
+  // Find and replace or append
+  let found = false;
+  const updatedLines = lines.map((line) => {
+    if (line.startsWith(entryPrefix)) {
+      found = true;
+      return entryLine;
+    }
+    return line;
+  });
+
+  if (!found) {
+    // Append after the header
+    updatedLines.push(entryLine);
+  }
+
+  const updatedIndex = updatedLines.join("\n").trimEnd() + "\n";
+
+  // Check size
+  const lineCount = updatedIndex.split("\n").length;
+  if (lineCount > 200) {
+    console.log(
+      `Warning: Memory index has ${lineCount} lines (recommended: <200). Consider consolidating or removing old memories.`,
+    );
+  }
+
+  await resourcePut(owner, indexPath, updatedIndex, "text/markdown");
+
+  console.log(`Saved memory "${name}" (${type}): ${description}`);
+}

package/src/scripts/resources/write.ts

@@ -0,0 +1,158 @@
+/**
+ * Core script: resource-write
+ *
+ * Write (create or update) a resource in the SQL store.
+ *
+ * Usage:
+ *   pnpm action resource-write --path <path> --content <content> [--scope personal|shared] [--mime <mime-type>] [--visibility workspace|agent_scratch]
+ */
+
+import {
+  canWriteLocalWorkspaceResourcePath,
+  resourcePut,
+  SHARED_OWNER,
+  WORKSPACE_OWNER,
+  type ResourceCreatedBy,
+  type ResourceVisibility,
+} from "../../resources/store.js";
+import { getRequestUserEmail } from "../../server/request-context.js";
+import { parseArgs, fail } from "../utils.js";
+
+const EXTENSION_MIME_MAP: Record<string, string> = {
+  ".md": "text/markdown",
+  ".ts": "text/typescript",
+  ".tsx": "text/typescript",
+  ".js": "text/javascript",
+  ".jsx": "text/javascript",
+  ".json": "application/json",
+  ".html": "text/html",
+  ".css": "text/css",
+  ".yaml": "text/yaml",
+  ".yml": "text/yaml",
+  ".xml": "application/xml",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain",
+  ".csv": "text/csv",
+  ".sql": "text/sql",
+  ".sh": "text/x-shellscript",
+  ".py": "text/x-python",
+  ".toml": "text/toml",
+};
+
+function inferMimeType(filePath: string): string {
+  const dotIndex = filePath.lastIndexOf(".");
+  if (dotIndex === -1) return "text/plain";
+  const ext = filePath.slice(dotIndex).toLowerCase();
+  return EXTENSION_MIME_MAP[ext] ?? "text/plain";
+}
+
+function parseVisibility(
+  value: string | undefined,
+): ResourceVisibility | undefined {
+  if (!value) return undefined;
+  if (value === "workspace" || value === "agent_scratch") return value;
+  fail("--visibility must be workspace or agent_scratch.");
+}
+
+function parseCreatedBy(
+  value: string | undefined,
+): ResourceCreatedBy | undefined {
+  if (!value) return undefined;
+  if (value === "user" || value === "agent" || value === "system") return value;
+  fail("--created-by must be user, agent, or system.");
+}
+
+function parseOptionalNumber(
+  value: string | undefined,
+  flag: string,
+): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) fail(`${flag} must be a number.`);
+  return parsed;
+}
+
+export default async function resourceWriteScript(
+  args: string[],
+): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help === "true") {
+    console.log(
+      `Usage: pnpm action resource-write --path <path> --content <content> [options]
+
+Options:
+  --path <path>            Resource path (required)
+  --content <content>      Content to write (required)
+  --scope personal|shared|workspace
+                           Scope to write to (default: personal). Workspace is writable for local file mode control resources.
+  --mime <mime-type>       MIME type (default: inferred from extension)
+  --visibility workspace|agent_scratch
+                           Visibility (default: workspace)
+  --created-by user|agent|system
+                           Provenance label (default: user)
+  --thread-id <id>         Agent thread id for scratch/provenance
+  --run-id <id>            Agent run id for scratch/provenance
+  --expires-at <ms>        Expiry timestamp in epoch milliseconds
+  --help                   Show this help message`,
+    );
+    return;
+  }
+
+  const resourcePath = parsed.path;
+  if (!resourcePath) {
+    fail("--path is required. Example: --path notes/todo.md");
+  }
+
+  const content = parsed.content;
+  if (content === undefined || content === null) {
+    fail("--content is required.");
+  }
+
+  const scope = parsed.scope ?? "personal";
+  if (scope === "workspace") {
+    if (!(await canWriteLocalWorkspaceResourcePath(resourcePath))) {
+      fail(
+        "Workspace resources are managed from Dispatch unless local file mode exposes this path. Writable local workspace paths are AGENTS.md, agent-native.json, mcp.config.json, .mcp.json, and skills/.",
+      );
+    }
+  }
+  const mimeType = parsed.mime ?? inferMimeType(resourcePath);
+  const visibility = parseVisibility(parsed.visibility);
+  const createdBy = parseCreatedBy(parsed["created-by"] ?? parsed.createdBy);
+  const threadId = parsed["thread-id"] ?? parsed.threadId;
+  const runId = parsed["run-id"] ?? parsed.runId;
+  const expiresAt = parseOptionalNumber(
+    parsed["expires-at"] ?? parsed.expiresAt,
+    "--expires-at",
+  );
+  let owner: string;
+  if (scope === "shared") {
+    owner = SHARED_OWNER;
+  } else if (scope === "workspace") {
+    owner = WORKSPACE_OWNER;
+  } else {
+    const personalOwner = getRequestUserEmail() ?? process.env.AGENT_USER_EMAIL;
+    if (!personalOwner) {
+      fail(
+        "resource-write --scope=personal requires an authenticated user (request context or AGENT_USER_EMAIL env var).",
+      );
+    }
+    owner = personalOwner;
+  }
+
+  const writeOptions = {
+    visibility,
+    createdBy,
+    threadId,
+    runId,
+    expiresAt,
+  };
+  const hasWriteOptions = Object.values(writeOptions).some(
+    (value) => value !== undefined,
+  );
+  const resource = hasWriteOptions
+    ? await resourcePut(owner, resourcePath, content, mimeType, writeOptions)
+    : await resourcePut(owner, resourcePath, content, mimeType);
+  console.log(`Wrote resource: ${resource.path} (${resource.size} bytes)`);
+}