@pylonsync/sdk 0.4.22 → 0.4.23

package/dist/index.d.ts

@@ -434,6 +434,12 @@ export interface ActionDefinition {
     input?: InputFieldDefinition[];
     /** See `QueryDefinition.auth`. */
     auth?: string;
+    /** Set by `discoverFunctions` for `agent()` definitions —
+     *  `buildManifest` injects the AgentRun/AgentMessage entities when
+     *  any action carries it, so templates that pass `actions:
+     *  fns.actions` (rather than spreading the whole result) still get
+     *  the injection. Not serialized into the manifest. */
+    isAgent?: boolean;
     /**
      * Which write kind this was before the manifest's read/write split
      * collapsed mutations and actions into one bucket. Preserved so a
@@ -780,6 +786,9 @@ export declare function discoverAppRoutes(opts?: {
 export interface DiscoveredFunctions {
     queries: QueryDefinition[];
     actions: ActionDefinition[];
+    /** True when any discovered function is an `agent()` — buildManifest
+     *  then injects the AgentRun/AgentMessage entities + policies. */
+    hasAgents?: boolean;
 }
 /**
  * Walk `functions/` and return every externally callable function, for
@@ -1059,6 +1068,11 @@ export declare function buildManifest(options: {
     connections?: ManifestConnection[];
     crons?: ManifestCron[];
     fonts?: ManifestFont[];
+    /** Set by `discoverFunctions()` (spread its result into this call).
+     *  When true, the framework's AgentRun/AgentMessage entities and
+     *  their owner-scoping policies are appended to the manifest —
+     *  unless the app already declares entities with those names. */
+    hasAgents?: boolean;
 }): AppManifest;
 export { defineStudioConfig, defineStudioExtensions, type BrandConfig, type ThemeConfig, type ThemeAccent, type ThemeAppearance, type IconName, type SidebarConfig, type SidebarSection, type SidebarItem, type SidebarPageItem, type SidebarResourceItem, type SidebarLinkItem, type SidebarHeadingItem, type SidebarFooter, type SidebarFooterCard, type SidebarFooterCustom, type ResourceConfig, type ResourceListConfig, type ColumnConfig, type ColumnRenderer, type RendererKind, type RendererText, type RendererAvatar, type RendererBadge, type RendererDate, type RendererLink, type RendererBoolean, type RendererNumber, type RendererJson, type RendererCustom, type BulkAction, type RowAction, type PageConfig, type StudioConfig, type StudioCellRendererProps, type StudioPageProps, type StudioExtensions, } from "./studio";
 /**

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.22",
+  "version": "0.4.23",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/agent-manifest.test.ts

@@ -0,0 +1,85 @@
+/**
+ * `hasAgents` manifest injection: buildManifest appends the
+ * AgentRun/AgentMessage entities + owner-scoping policies when any
+ * `agent()` was discovered — as ordinary synced entities, so every
+ * downstream surface (sync, codegen, migrate) applies unchanged.
+ */
+import { expect, test } from "bun:test";
+import { buildManifest, entity, field } from "./index";
+
+const base = {
+  name: "t",
+  version: "0",
+  entities: [entity("Doc", { title: field.string() })],
+  routes: [],
+};
+
+test("hasAgents injects entities, indexes, sync scopes, and policies", () => {
+  const m = buildManifest({ ...base, hasAgents: true });
+
+  const run = m.entities.find((e) => e.name === "AgentRun")!;
+  expect(run).toBeDefined();
+  const runFields = Object.fromEntries(run.fields.map((f) => [f.name, f.type]));
+  expect(runFields.agent).toBe("string");
+  expect(runFields.status).toBe("string");
+  expect(runFields.streamId).toBe("string");
+  expect(runFields.createdAt).toBe("datetime");
+  expect(run.sync_scope).toBe("auth.userId != null && data.userId == auth.userId");
+
+  const msg = m.entities.find((e) => e.name === "AgentMessage")!;
+  expect(msg).toBeDefined();
+  const msgFields = Object.fromEntries(msg.fields.map((f) => [f.name, f.type]));
+  expect(msgFields.runId).toBe("id(AgentRun)");
+  expect(msgFields.content).toBe("json");
+  expect(msgFields.seq).toBe("int");
+  expect(msg.indexes.some((i) => i.name === "by_run")).toBe(true);
+  expect(msg.sync_scope).toBe("auth.userId != null && data.userId == auth.userId");
+
+  const runPolicy = m.policies.find((p) => p.entity === "AgentRun")!;
+  expect(runPolicy.allowRead).toBe("auth.userId != null && data.userId == auth.userId");
+  expect(runPolicy.allowInsert).toBe("false");
+  expect(runPolicy.allowUpdate).toBe("false");
+  expect(runPolicy.allowDelete).toBe("false");
+  expect(m.policies.some((p) => p.entity === "AgentMessage")).toBe(true);
+});
+
+test("without hasAgents nothing is injected", () => {
+  const m = buildManifest(base);
+  expect(m.entities.some((e) => e.name === "AgentRun")).toBe(false);
+  expect(m.policies.some((p) => p.entity === "AgentRun")).toBe(false);
+});
+
+test("app-declared AgentRun and policies win over injection", () => {
+  const custom = entity("AgentRun", { custom: field.string() });
+  const m = buildManifest({
+    ...base,
+    entities: [...base.entities, custom],
+    policies: [
+      { name: "mine", entity: "AgentRun", allowRead: "auth.userId != null" },
+    ],
+    hasAgents: true,
+  });
+  const runs = m.entities.filter((e) => e.name === "AgentRun");
+  expect(runs).toHaveLength(1);
+  expect(runs[0].fields.map((f) => f.name)).toEqual(["custom"]);
+  const policies = m.policies.filter((p) => p.entity === "AgentRun");
+  expect(policies).toHaveLength(1);
+  expect(policies[0].name).toBe("mine");
+  // AgentMessage still injected (not declared by the app).
+  expect(m.entities.some((e) => e.name === "AgentMessage")).toBe(true);
+});
+
+test("hasAgents is inferred from actions carrying isAgent", () => {
+  const m = buildManifest({
+    ...base,
+    actions: [{ name: "helper", isAgent: true, fnType: "action" }],
+  });
+  expect(m.entities.some((e) => e.name === "AgentRun")).toBe(true);
+  // Explicit false wins over inference.
+  const off = buildManifest({
+    ...base,
+    actions: [{ name: "helper", isAgent: true, fnType: "action" }],
+    hasAgents: false,
+  });
+  expect(off.entities.some((e) => e.name === "AgentRun")).toBe(false);
+});

package/src/index.ts

@@ -579,6 +579,12 @@ export interface ActionDefinition {
   input?: InputFieldDefinition[];
   /** See `QueryDefinition.auth`. */
   auth?: string;
+  /** Set by `discoverFunctions` for `agent()` definitions —
+   *  `buildManifest` injects the AgentRun/AgentMessage entities when
+   *  any action carries it, so templates that pass `actions:
+   *  fns.actions` (rather than spreading the whole result) still get
+   *  the injection. Not serialized into the manifest. */
+  isAgent?: boolean;
   /**
    * Which write kind this was before the manifest's read/write split
    * collapsed mutations and actions into one bucket. Preserved so a
@@ -1449,6 +1455,9 @@ function argsToInput(
 export interface DiscoveredFunctions {
   queries: QueryDefinition[];
   actions: ActionDefinition[];
+  /** True when any discovered function is an `agent()` — buildManifest
+   *  then injects the AgentRun/AgentMessage entities + policies. */
+  hasAgents?: boolean;
 }
 
 /**
@@ -1519,6 +1528,7 @@ export async function discoverFunctions(opts?: {
 
   const queries: QueryDefinition[] = [];
   const actions: ActionDefinition[] = [];
+  let hasAgents = false;
 
   for (const file of files) {
     const name = file.replace(/\.(ts|js)$/, "");
@@ -1547,17 +1557,25 @@ export async function discoverFunctions(opts?: {
       continue;
     }
     if (shape.internal === true) continue;
+    const isAgent = shape.__pylonAgent === true;
+    if (isAgent) hasAgents = true;
 
     const input = argsToInput(definition!.args);
     const auth = typeof shape.auth === "string" ? shape.auth : undefined;
     if (definition!.type === "query") {
       queries.push({ name, input, auth });
     } else {
-      actions.push({ name, input, auth, fnType: definition!.type });
+      actions.push({
+        name,
+        input,
+        auth,
+        fnType: definition!.type,
+        ...(isAgent ? { isAgent: true } : {}),
+      });
     }
   }
 
-  return { queries, actions };
+  return { queries, actions, hasAgents };
 }
 
 export function queriesToManifest(queries: QueryDefinition[]): ManifestQuery[] {
@@ -1936,6 +1954,91 @@ function isManifestAuthConfig(
   return "trusted_origins" in cfg;
 }
 
+/** The framework entities behind `agent()`. Plain synced entities so
+ *  every existing surface (sync, policies, codegen, migrate) applies. */
+function agentEntities(): EntityDefinition[] {
+  return [
+    entity(
+      "AgentRun",
+      {
+        agent: field.string(),
+        status: field.string(),
+        // User-scoped, deliberately NOT tenantId-scoped: a tenantId
+        // field would trip TenantScopePlugin's auto-scoping and reject
+        // callers with no active organization. Apps needing org-scoped
+        // agent visibility declare their own AgentRun (injection
+        // defers to app-declared entities).
+        userId: field.string().optional(),
+        title: field.string().optional(),
+        // Resumable-stream id of the CURRENT generation — another
+        // device attaches to live tokens via resumeStream(streamId).
+        // Owner-scoped by policy, so it never leaks across users.
+        streamId: field.string().optional(),
+        error: field.string().optional(),
+        createdAt: field.datetime(),
+        updatedAt: field.datetime(),
+      },
+      {
+        indexes: [
+          { name: "by_user", fields: ["userId"], unique: false },
+        ],
+        // Replicate only the caller's own runs. The explicit
+        // null-guard matters: the policy engine evaluates null == null
+        // as TRUE, so without it an anonymous visitor could read any
+        // run that somehow ended up ownerless.
+        sync: { where: "auth.userId != null && data.userId == auth.userId" },
+      },
+    ),
+    entity(
+      "AgentMessage",
+      {
+        runId: field.id("AgentRun"),
+        userId: field.string().optional(),
+        seq: field.int(),
+        role: field.string(),
+        content: field.json(),
+        createdAt: field.datetime(),
+      },
+      {
+        indexes: [
+          // Unique: the loop is the only writer and single-writer per
+          // run; a racing duplicate fails loudly instead of garbling
+          // the transcript.
+          { name: "by_run", fields: ["runId", "seq"], unique: true },
+        ],
+        sync: { where: "auth.userId != null && data.userId == auth.userId" },
+      },
+    ),
+  ];
+}
+
+/** Owner-only reads; every client write denied — the agent loop's
+ *  internal mutations (server-side) are the only writer. */
+function agentPolicies(): PolicyDefinition[] {
+  const lockdown = {
+    allowInsert: "false",
+    allowUpdate: "false",
+    allowDelete: "false",
+  };
+  // The `auth.userId != null` guard is load-bearing: the policy
+  // engine evaluates null == null as TRUE, so a bare equality would
+  // hand ownerless rows to every anonymous caller.
+  return [
+    {
+      name: "agent_run_owner",
+      entity: "AgentRun",
+      allowRead: "auth.userId != null && data.userId == auth.userId",
+      ...lockdown,
+    },
+    {
+      name: "agent_message_owner",
+      entity: "AgentMessage",
+      allowRead: "auth.userId != null && data.userId == auth.userId",
+      ...lockdown,
+    },
+  ];
+}
+
 export function buildManifest(options: {
   name: string;
   version: string;
@@ -1949,6 +2052,11 @@ export function buildManifest(options: {
   connections?: ManifestConnection[];
   crons?: ManifestCron[];
   fonts?: ManifestFont[];
+  /** Set by `discoverFunctions()` (spread its result into this call).
+   *  When true, the framework's AgentRun/AgentMessage entities and
+   *  their owner-scoping policies are appended to the manifest —
+   *  unless the app already declares entities with those names. */
+  hasAgents?: boolean;
 }): AppManifest {
   // Pull policies attached via the fluent `e.entity().policies(...)`
   // chain onto the top-level policies list. Without this, fluent
@@ -1977,11 +2085,32 @@ export function buildManifest(options: {
     });
   }
   const allPolicies = [...(options.policies ?? []), ...attached];
+  // Agent run state: when any `agent()` exists, its durable state lives
+  // in two ORDINARY synced entities — owner-scoped reads, client writes
+  // denied (the loop's internal mutations are the only writer). Being
+  // plain entities means sync replication, codegen types, `pylon
+  // migrate`, and `db.useQuery("AgentMessage", ...)` all just work.
+  const allEntities = [...options.entities];
+  const hasAgents =
+    options.hasAgents ??
+    (options.actions ?? []).some((a) => a.isAgent === true);
+  if (hasAgents) {
+    const taken = new Set(allEntities.map((e) => e.name));
+    for (const ent of agentEntities()) {
+      if (!taken.has(ent.name)) allEntities.push(ent);
+    }
+    const declaredFor = new Set(
+      allPolicies.map((p) => p.entity).filter(Boolean),
+    );
+    for (const pol of agentPolicies()) {
+      if (!declaredFor.has(pol.entity)) allPolicies.push(pol);
+    }
+  }
   return {
     manifest_version: MANIFEST_VERSION,
     name: options.name,
     version: options.version,
-    entities: entitiesToManifest(options.entities),
+    entities: entitiesToManifest(allEntities),
     routes: routesToManifest(options.routes),
     queries: queriesToManifest(options.queries ?? []),
     actions: actionsToManifest(options.actions ?? []),