@lupinum/better-convex-agents 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/dist/agent/AGENTS.md +6 -3
  2. package/dist/agent/pages/docs/build/application-behavior/error-handling.md +40 -1
  3. package/dist/agent/pages/docs/build/authentication/account-deletion.md +73 -0
  4. package/dist/agent/pages/docs/build/authentication/backend-authorization.md +6 -1
  5. package/dist/agent/pages/docs/build/authentication/better-auth-setup.md +3 -1
  6. package/dist/agent/pages/docs/build/authentication/sign-in-and-sign-out.md +3 -0
  7. package/dist/agent/pages/docs/build/authentication/transactional-email.md +45 -10
  8. package/dist/agent/pages/docs/build/files/private-downloads.md +126 -0
  9. package/dist/agent/pages/docs/build/files/storage-urls.md +8 -3
  10. package/dist/agent/pages/docs/build/files/upload-files.md +2 -2
  11. package/dist/agent/pages/docs/build/functions/limits-and-audit.md +142 -4
  12. package/dist/agent/pages/docs/build/functions/testing.md +24 -0
  13. package/dist/agent/pages/docs/build/queries/loading-and-stale-data.md +1 -1
  14. package/dist/agent/pages/docs/build/queries/pagination.md +2 -2
  15. package/dist/agent/pages/docs/build/queries/reactive-arguments.md +46 -0
  16. package/dist/agent/pages/docs/build/server/server-convex.md +16 -1
  17. package/dist/agent/pages/docs/build/write-data/concurrent-operations.md +1 -1
  18. package/dist/agent/pages/docs/build/write-data/forms.md +1 -1
  19. package/dist/agent/pages/docs/build/write-data/multi-step-operations.md +1 -1
  20. package/dist/agent/pages/docs/build/write-data/optimistic-updates.md +1 -1
  21. package/dist/agent/pages/docs/get-started/add-authentication.md +13 -3
  22. package/dist/agent/pages/docs/get-started/complete-and-delete.md +2 -0
  23. package/dist/agent/pages/docs/get-started/first-realtime-page.md +3 -1
  24. package/dist/agent/pages/docs/get-started/installation.md +3 -0
  25. package/dist/agent/pages/docs/get-started/next-steps.md +30 -0
  26. package/dist/agent/pages/docs/get-started/plain-vue.md +143 -41
  27. package/dist/agent/pages/docs/operations/before-launch.md +1 -1
  28. package/dist/agent/pages/docs/operations/log-streams.md +128 -0
  29. package/dist/agent/pages/docs/recipes/dynamic-query-list.md +1 -1
  30. package/dist/agent/pages/docs/recipes/error-messages.md +1 -1
  31. package/dist/agent/pages/docs/recipes/guest-users.md +67 -15
  32. package/dist/agent/pages/docs/recipes/multiple-file-uploads.md +1 -1
  33. package/dist/agent/pages/docs/recipes/optimistic-todo-list.md +1 -1
  34. package/dist/agent/pages/docs/recipes/realtime-feed.md +1 -1
  35. package/dist/agent/pages/docs/recipes/sign-in-link.md +129 -0
  36. package/dist/agent/pages/docs/reference/api-surface.md +11 -0
  37. package/dist/agent/pages/docs/reference/error-types.md +12 -2
  38. package/dist/agent/pages/docs/reference/operation-error-codes.md +15 -1
  39. package/dist/agent/pages/docs/reference/package-exports.md +3 -2
  40. package/dist/agent/pages/docs/reference/server-api.md +5 -1
  41. package/dist/index.d.mts +1 -1
  42. package/dist/index.d.ts +1 -1
  43. package/dist/index.mjs +1 -1
  44. package/dist/internal.d.mts +1 -1
  45. package/dist/internal.d.ts +1 -1
  46. package/dist/internal.mjs +1 -1
  47. package/dist/mcp.mjs +4 -2
  48. package/dist/shared/{better-convex-agents.DWStY2mj.mjs → better-convex-agents.BAvd6ID4.mjs} +475 -393
  49. package/dist/shared/{better-convex-agents.Jrci7p3C.d.mts → better-convex-agents.l5qUkNCR.d.mts} +14 -2
  50. package/dist/shared/{better-convex-agents.Jrci7p3C.d.ts → better-convex-agents.l5qUkNCR.d.ts} +14 -2
  51. package/dist/test.d.mts +1 -1
  52. package/dist/test.d.ts +1 -1
  53. package/dist/test.mjs +1 -1
  54. package/package.json +3 -3
@@ -1,5 +1,5 @@
1
1
  import { fail, oneLine } from '@lupinum/better-convex-functions';
2
- import { guarded, uploadTypes, maximumUploadBytes, internalsOf, OPERATION, toolNamePattern, toJsonSchema, jsonOf, agentCallerValidator, actorRecord, inertMarkdown, uploadClaimMs, scopesFor, statedAgentRule, storable, readOnly, markHousekeeping, markTools, failureOf, checkInput, isIdOf, callKey, fingerprint, frozen, approversFor, planOf, takeToken, uploadLinkMs, unsendable, idsIn } from '@lupinum/better-convex-functions/internal';
2
+ import { guarded, uploadTypes, maximumUploadBytes, internalsOf, OPERATION, toolNamePattern, toJsonSchema, jsonOf, agentCallerValidator, newSeen, sawActor, actorRecord, inertMarkdown, uploadClaimMs, scopesFor, statedAgentRule, markHousekeeping, markTools, failureOf, checkInput, isIdOf, callKey, fingerprint, frozen, handedFields, approversFor, planOf, uploadLinkMs, readOnly, tookFields, storable, unsendable, takeToken, idsIn } from '@lupinum/better-convex-functions/internal';
3
3
  import { makeFunctionReference, httpActionGeneric, internalQueryGeneric, internalMutationGeneric, mutationGeneric, queryGeneric } from 'convex/server';
4
4
  import { getConvexSize, v } from 'convex/values';
5
5
 
@@ -526,7 +526,11 @@ async function toolCall(entry, args, principal, run) {
526
526
  }
527
527
  function defineTools(fns, modules, options) {
528
528
  const { policy } = fns;
529
- const { person, agent, authorize, lib, tenants, roleOf } = internalsOf(fns);
529
+ const { person, agent, authorize, lib, tenants, roleOf, observed } = internalsOf(fns);
530
+ const withEvent = (kind, action, handler) => (ctx, args) => {
531
+ const event = newSeen();
532
+ return observed(kind, action, event, () => handler(ctx, args, event));
533
+ };
530
534
  const ownRef = (name) => options.functions[name];
531
535
  const operations = /* @__PURE__ */ new Map();
532
536
  for (const module of Object.values(modules)) {
@@ -608,25 +612,29 @@ function defineTools(fns, modules, options) {
608
612
  args,
609
613
  returns: v.object({ status: v.literal("done"), result: paged ? pageResult : op.returns }),
610
614
  handler: async (ctx, { caller, input: raw }) => {
611
- const actor = await agent(ctx, caller);
612
- const checkedInput = inputOf(ctx, { args: toolArgs(op) }, raw);
613
- const input = paged ? fromCursor(checkedInput) : checkedInput;
614
- const { ctx: checked, settle } = await authorize(ctx, op, actor, input);
615
- const hasCursor = paged && input.paginationOpts.cursor !== null;
616
- const result = await Promise.resolve(op.handler(checked, input)).catch(
617
- (error) => {
618
- if (hasCursor && isCursorFailure(error))
619
- fail(
620
- "INVALID_INPUT",
621
- "cursor: pass the `next` value from the last result exactly, or leave it out for the first page."
622
- );
623
- throw error;
624
- }
625
- );
626
- return {
627
- status: "done",
628
- result: settle(paged ? toCursor(result) : result)
629
- };
615
+ const event = newSeen();
616
+ return observed("query", op.action, event, async () => {
617
+ const actor = await agent(ctx, caller);
618
+ sawActor(event, actor);
619
+ const checkedInput = inputOf(ctx, { args: toolArgs(op) }, raw);
620
+ const input = paged ? fromCursor(checkedInput) : checkedInput;
621
+ const { ctx: checked, settle } = await authorize(ctx, op, actor, input, event);
622
+ const hasCursor = paged && input.paginationOpts.cursor !== null;
623
+ const result = await Promise.resolve(op.handler(checked, input)).catch(
624
+ (error) => {
625
+ if (hasCursor && isCursorFailure(error))
626
+ fail(
627
+ "INVALID_INPUT",
628
+ "cursor: pass the `next` value from the last result exactly, or leave it out for the first page."
629
+ );
630
+ throw error;
631
+ }
632
+ );
633
+ return {
634
+ status: "done",
635
+ result: settle(paged ? toCursor(result) : result)
636
+ };
637
+ });
630
638
  }
631
639
  })
632
640
  );
@@ -641,7 +649,13 @@ function defineTools(fns, modules, options) {
641
649
  },
642
650
  // A replayed result may be the marker `storable` left when the result was too large to keep.
643
651
  returns: v.union(
644
- v.object({ status: v.literal("done"), result: v.union(op.returns, truncated) }),
652
+ v.object({
653
+ status: v.literal("done"),
654
+ result: v.union(op.returns, truncated),
655
+ // Approved work hands its rows and fields to the event of `approve`, which ran it.
656
+ written: v.optional(v.array(v.string())),
657
+ fields: v.optional(v.string())
658
+ }),
645
659
  needsApproval
646
660
  ),
647
661
  handler: async (ctx, {
@@ -651,190 +665,212 @@ function defineTools(fns, modules, options) {
651
665
  approval,
652
666
  renew
653
667
  }) => {
654
- const actor = await agent(ctx, caller, { approved: approval !== void 0 || renew });
655
- const input = inputOf(ctx, op, raw);
656
- const planned = async ({
657
- ctx: checked2,
658
- settle: settle2
659
- }) => {
660
- const plan = frozen(settle2(await planOf(op, checked2, input)));
661
- const ids = /* @__PURE__ */ new Map();
662
- for (const { table, id } of idsIn(jsonOf(v.object(op.args)), input))
663
- if (!table.startsWith("_") && ctx.db.normalizeId(table, id) !== null)
664
- ids.set(id, table);
665
- for (const id of plan.rows ?? []) {
666
- const table = tenants.tableOf(ctx.db, id);
667
- if (table === void 0)
668
- throw new Error(
669
- `The plan of ${op.action} lists ${id}, which is no ID of an app table.`
668
+ const event = newSeen();
669
+ const inner = approval !== void 0 || renew === true;
670
+ return observed(
671
+ "mutation",
672
+ op.action,
673
+ event,
674
+ async () => {
675
+ const actor = await agent(ctx, caller, { approved: approval !== void 0 || renew });
676
+ sawActor(event, actor);
677
+ const input = inputOf(ctx, op, raw);
678
+ const planned = async ({
679
+ ctx: checked2,
680
+ settle: settle2
681
+ }) => {
682
+ const plan = frozen(settle2(await planOf(op, checked2, input)));
683
+ const ids = /* @__PURE__ */ new Map();
684
+ for (const { table, id } of idsIn(jsonOf(v.object(op.args)), input))
685
+ if (!table.startsWith("_") && ctx.db.normalizeId(table, id) !== null)
686
+ ids.set(id, table);
687
+ for (const id of plan.rows ?? []) {
688
+ const table = tenants.tableOf(ctx.db, id);
689
+ if (table === void 0)
690
+ throw new Error(
691
+ `The plan of ${op.action} lists ${id}, which is no ID of an app table.`
692
+ );
693
+ ids.set(id, table);
694
+ }
695
+ if (ids.size > maxSeen) {
696
+ fail(
697
+ "TOO_LARGE",
698
+ `One request may cover at most ${maxSeen} rows, so a person can check them. Ask for fewer at once.`
699
+ );
700
+ }
701
+ const rows = [];
702
+ for (const [id, table] of ids) {
703
+ const row = await checked2.db.get(id);
704
+ if (row === null) fail("NOT_FOUND", `No ${table} with this ID.`);
705
+ rows.push({ table, id, row });
706
+ }
707
+ const seen = await Promise.all(
708
+ rows.map(async ({ id }) => ({
709
+ id,
710
+ hash: await fingerprint(await ctx.db.get(id))
711
+ }))
670
712
  );
671
- ids.set(id, table);
672
- }
673
- if (ids.size > maxSeen) {
674
- fail(
675
- "TOO_LARGE",
676
- `One request may cover at most ${maxSeen} rows, so a person can check them. Ask for fewer at once.`
677
- );
678
- }
679
- const rows = [];
680
- for (const [id, table] of ids) {
681
- const row = await checked2.db.get(id);
682
- if (row === null) fail("NOT_FOUND", `No ${table} with this ID.`);
683
- rows.push({ table, id, row });
684
- }
685
- const seen = await Promise.all(
686
- rows.map(async ({ id }) => ({
687
- id,
688
- hash: await fingerprint(await ctx.db.get(id))
689
- }))
690
- );
691
- return { plan, seen, rows };
692
- };
693
- const requester = actorRecord(actor);
694
- if (approval) {
695
- const row = await lib(ctx).get(approval.id);
696
- if (row?.status !== "executing" || row.requester.key !== requester.key || row.action !== op.action || callKey(row.tool, row.input) !== callKey(op.tool.name, raw)) {
697
- fail("APPROVAL_NOT_FOUND", "This approval does not match the request.");
698
- }
699
- if (row.plan === void 0) fail("STALE", stale);
700
- for (const { id, hash } of row.seen ?? []) {
701
- const now = await ctx.db.get(id);
702
- if (now === null || await fingerprint(now) !== hash) fail("STALE", stale);
703
- }
704
- const {
705
- ctx: checked2,
706
- tenant: tenant2,
707
- settle: settle2,
708
- record: record3
709
- } = await authorize(ctx, op, { ...actor, approvalId: approval.id }, input);
710
- const result = await runForAgent(
711
- ctx,
712
- checked2,
713
- settle2,
714
- op,
715
- input,
716
- frozen(row.plan),
717
- {
718
- tenant: tenant2,
719
- requestId: row.requestId,
720
- approvalId: approval.id,
721
- decidedBy: approval.decidedBy
722
- },
723
- record3
724
- );
725
- return { status: "done", result };
726
- }
727
- if (!renew) await rateLimit(ctx, `${requester.key}|writes`, agentWritesPerMinute);
728
- const authorized = await authorize(ctx, op, actor, input);
729
- const { decision, tenant, settle, mayWrite, record: record2, ctx: checked } = authorized;
730
- if (renew && decision !== "approve") fail("STALE", stale);
731
- const call = callKey(op.tool.name, input);
732
- if (requestId !== void 0) {
733
- const earlier = await lib(ctx).query("activity").withIndex(
734
- "by_actor_request",
735
- (q) => q.eq("actor.key", requester.key).eq("requestId", requestId)
736
- ).first();
737
- if (earlier) {
738
- if (earlier.call !== call)
739
- fail(
740
- "REQUEST_ID_REUSED",
741
- "This request_id was used for a different call. Send a new one."
713
+ return { plan, seen, rows };
714
+ };
715
+ const requester = actorRecord(actor);
716
+ if (approval) {
717
+ const row = await lib(ctx).get(approval.id);
718
+ if (row?.status !== "executing" || row.requester.key !== requester.key || row.action !== op.action || callKey(row.tool, row.input) !== callKey(op.tool.name, raw)) {
719
+ fail("APPROVAL_NOT_FOUND", "This approval does not match the request.");
720
+ }
721
+ if (row.plan === void 0) fail("STALE", stale);
722
+ for (const { id, hash } of row.seen ?? []) {
723
+ const now = await ctx.db.get(id);
724
+ if (now === null || await fingerprint(now) !== hash) fail("STALE", stale);
725
+ }
726
+ const {
727
+ ctx: checked2,
728
+ tenant: tenant2,
729
+ settle: settle2,
730
+ record: record3,
731
+ written
732
+ } = await authorize(ctx, op, { ...actor, approvalId: approval.id }, input, event);
733
+ const result = await runForAgent(
734
+ ctx,
735
+ checked2,
736
+ settle2,
737
+ op,
738
+ input,
739
+ frozen(row.plan),
740
+ {
741
+ tenant: tenant2,
742
+ requestId: row.requestId,
743
+ approvalId: approval.id,
744
+ decidedBy: approval.decidedBy
745
+ },
746
+ record3
742
747
  );
743
- if (earlier.status === "declined")
744
- fail("APPROVAL_DECLINED", "A person declined this request.");
745
- if (earlier.status === "failed") {
746
- const reason = earlier.result;
747
- fail(reason.code, reason.message);
748
+ return {
749
+ status: "done",
750
+ result,
751
+ written: [...written, ...event.innerWritten ?? []],
752
+ ...handedFields(event)
753
+ };
754
+ }
755
+ if (!renew) await rateLimit(ctx, `${requester.key}|writes`, agentWritesPerMinute);
756
+ const authorized = await authorize(ctx, op, actor, input, event);
757
+ const { decision, tenant, settle, mayWrite, record: record2, ctx: checked } = authorized;
758
+ if (renew && decision !== "approve") fail("STALE", stale);
759
+ const call = callKey(op.tool.name, input);
760
+ if (requestId !== void 0) {
761
+ const earlier = await lib(ctx).query("activity").withIndex(
762
+ "by_actor_request",
763
+ (q) => q.eq("actor.key", requester.key).eq("requestId", requestId)
764
+ ).first();
765
+ if (earlier) {
766
+ if (earlier.call !== call)
767
+ fail(
768
+ "REQUEST_ID_REUSED",
769
+ "This request_id was used for a different call. Send a new one."
770
+ );
771
+ if (earlier.status === "declined")
772
+ fail("APPROVAL_DECLINED", "A person declined this request.");
773
+ if (earlier.status === "failed") {
774
+ const reason = earlier.result;
775
+ fail(reason.code, reason.message);
776
+ }
777
+ return { status: "done", result: earlier.result };
778
+ }
779
+ const asked = await lib(ctx).query("approvals").withIndex(
780
+ "by_requester_request",
781
+ (q) => q.eq("requester.key", requester.key).eq("requestId", requestId)
782
+ ).first();
783
+ if (asked && callKey(asked.tool, asked.input) !== call)
784
+ fail(
785
+ "REQUEST_ID_REUSED",
786
+ "This request_id was used for a different call. Send a new one."
787
+ );
788
+ }
789
+ if (decision === "approve") {
790
+ const open = await lib(ctx).query("approvals").withIndex(
791
+ "by_requester_status",
792
+ (q) => q.eq("requester.key", requester.key).eq("status", "pending").gt("expiresAt", Date.now())
793
+ ).take(openApprovals + 1);
794
+ const same = open.find(
795
+ (row) => callKey(row.tool, row.input) === call && (caller.door !== "app" || row.caller.door === "app" && row.caller.runId === caller.runId)
796
+ );
797
+ if (same) {
798
+ event.outcome = "pending";
799
+ event.approval = same._id;
800
+ return {
801
+ status: "needs_approval",
802
+ approvalId: same._id,
803
+ summary: inertMarkdown(same.summary),
804
+ url: approvalUrl(same._id)
805
+ };
806
+ }
807
+ const callHash = await fingerprint(call);
808
+ const declined = await lib(ctx).query("approvals").withIndex(
809
+ "by_requester_call",
810
+ (q) => q.eq("requester.key", requester.key).eq("callHash", callHash).eq("status", "declined").gt("expiresAt", Date.now())
811
+ ).first();
812
+ if (declined) fail("APPROVAL_DECLINED", "A person declined this request.");
813
+ if (open.length >= openApprovals) {
814
+ fail(
815
+ "RATE_LIMITED",
816
+ `${openApprovals} requests already wait for a person. Wait until they are decided.`
817
+ );
818
+ }
819
+ const { plan, seen, rows } = await planned(authorized);
820
+ const summary = oneLine(plan.summary);
821
+ const expiresAt = Date.now() + approvalTtl;
822
+ const approval2 = {
823
+ action: op.action,
824
+ tool: op.tool.name,
825
+ input,
826
+ summary,
827
+ requester,
828
+ caller,
829
+ tenantId: tenant?.id,
830
+ requestId,
831
+ callHash,
832
+ plan,
833
+ seen,
834
+ status: "pending",
835
+ expiresAt
836
+ };
837
+ if (getConvexSize(approval2) > maxApprovalBytes) {
838
+ fail(
839
+ "TOO_LARGE",
840
+ `The plan of ${op.action} is too large to store for approval: a request may hold at most 256 KiB. Make the plan smaller, or split the work into several calls.`
841
+ );
842
+ }
843
+ const approvalId = await lib(ctx).insert("approvals", approval2);
844
+ if (approversFor(policy, op.action).sharedRows) {
845
+ for (const tenantId of await partiesOf(ctx, tenant, rows, mayWrite)) {
846
+ await lib(ctx).insert("approvalParties", { approvalId, tenantId, expiresAt });
847
+ }
848
+ }
849
+ event.outcome = "pending";
850
+ event.approval = approvalId;
851
+ return {
852
+ status: "needs_approval",
853
+ approvalId,
854
+ summary: inertMarkdown(summary),
855
+ url: approvalUrl(approvalId)
856
+ };
748
857
  }
749
- return { status: "done", result: earlier.result };
750
- }
751
- const asked = await lib(ctx).query("approvals").withIndex(
752
- "by_requester_request",
753
- (q) => q.eq("requester.key", requester.key).eq("requestId", requestId)
754
- ).first();
755
- if (asked && callKey(asked.tool, asked.input) !== call)
756
- fail(
757
- "REQUEST_ID_REUSED",
758
- "This request_id was used for a different call. Send a new one."
759
- );
760
- }
761
- if (decision === "approve") {
762
- const open = await lib(ctx).query("approvals").withIndex(
763
- "by_requester_status",
764
- (q) => q.eq("requester.key", requester.key).eq("status", "pending").gt("expiresAt", Date.now())
765
- ).take(openApprovals + 1);
766
- const same = open.find(
767
- (row) => callKey(row.tool, row.input) === call && (caller.door !== "app" || row.caller.door === "app" && row.caller.runId === caller.runId)
768
- );
769
- if (same)
770
858
  return {
771
- status: "needs_approval",
772
- approvalId: same._id,
773
- summary: inertMarkdown(same.summary),
774
- url: approvalUrl(same._id)
859
+ status: "done",
860
+ result: await runForAgent(
861
+ ctx,
862
+ checked,
863
+ settle,
864
+ op,
865
+ input,
866
+ frozen(settle(await planOf(op, checked, input))),
867
+ { tenant, requestId },
868
+ record2
869
+ )
775
870
  };
776
- const callHash = await fingerprint(call);
777
- const declined = await lib(ctx).query("approvals").withIndex(
778
- "by_requester_call",
779
- (q) => q.eq("requester.key", requester.key).eq("callHash", callHash).eq("status", "declined").gt("expiresAt", Date.now())
780
- ).first();
781
- if (declined) fail("APPROVAL_DECLINED", "A person declined this request.");
782
- if (open.length >= openApprovals) {
783
- fail(
784
- "RATE_LIMITED",
785
- `${openApprovals} requests already wait for a person. Wait until they are decided.`
786
- );
787
- }
788
- const { plan, seen, rows } = await planned(authorized);
789
- const summary = oneLine(plan.summary);
790
- const expiresAt = Date.now() + approvalTtl;
791
- const approval2 = {
792
- action: op.action,
793
- tool: op.tool.name,
794
- input,
795
- summary,
796
- requester,
797
- caller,
798
- tenantId: tenant?.id,
799
- requestId,
800
- callHash,
801
- plan,
802
- seen,
803
- status: "pending",
804
- expiresAt
805
- };
806
- if (getConvexSize(approval2) > maxApprovalBytes) {
807
- fail(
808
- "TOO_LARGE",
809
- `The plan of ${op.action} is too large to store for approval: a request may hold at most 256 KiB. Make the plan smaller, or split the work into several calls.`
810
- );
811
- }
812
- const approvalId = await lib(ctx).insert("approvals", approval2);
813
- if (approversFor(policy, op.action).sharedRows) {
814
- for (const tenantId of await partiesOf(ctx, tenant, rows, mayWrite)) {
815
- await lib(ctx).insert("approvalParties", { approvalId, tenantId, expiresAt });
816
- }
817
- }
818
- return {
819
- status: "needs_approval",
820
- approvalId,
821
- summary: inertMarkdown(summary),
822
- url: approvalUrl(approvalId)
823
- };
824
- }
825
- return {
826
- status: "done",
827
- result: await runForAgent(
828
- ctx,
829
- checked,
830
- settle,
831
- op,
832
- input,
833
- frozen(settle(await planOf(op, checked, input))),
834
- { tenant, requestId },
835
- record2
836
- )
837
- };
871
+ },
872
+ inner
873
+ );
838
874
  }
839
875
  })
840
876
  );
@@ -844,23 +880,27 @@ function defineTools(fns, modules, options) {
844
880
  internalQueryGeneric({
845
881
  args: { caller: agentCallerValidator, input: v.any(), requestId: v.optional(v.string()) },
846
882
  handler: async (ctx, { caller, input: raw }) => {
847
- const actor = await agent(ctx, caller);
848
- const input = inputOf(ctx, { args: checkApprovalArgs }, raw);
849
- const id = lib(ctx).normalizeId("approvals", input.approvalId);
850
- const row = id && await lib(ctx).get(id);
851
- if (!row || row.requester.key !== actorRecord(actor).key) {
852
- fail("APPROVAL_NOT_FOUND", "No request with this ID was made by this connection.");
853
- }
854
- const status = requestStatus(row);
855
- return {
856
- status: "done",
857
- result: {
858
- status,
859
- summary: inertMarkdown(row.summary),
860
- result: row.result ?? null,
861
- error: row.error ?? null
883
+ const event = newSeen();
884
+ return observed("query", "agents.check_approval", event, async () => {
885
+ const actor = await agent(ctx, caller);
886
+ sawActor(event, actor);
887
+ const input = inputOf(ctx, { args: checkApprovalArgs }, raw);
888
+ const id = lib(ctx).normalizeId("approvals", input.approvalId);
889
+ const row = id && await lib(ctx).get(id);
890
+ if (!row || row.requester.key !== actorRecord(actor).key) {
891
+ fail("APPROVAL_NOT_FOUND", "No request with this ID was made by this connection.");
862
892
  }
863
- };
893
+ const status = requestStatus(row);
894
+ return {
895
+ status: "done",
896
+ result: {
897
+ status,
898
+ summary: inertMarkdown(row.summary),
899
+ result: row.result ?? null,
900
+ error: row.error ?? null
901
+ }
902
+ };
903
+ });
864
904
  }
865
905
  })
866
906
  );
@@ -876,59 +916,64 @@ function defineTools(fns, modules, options) {
876
916
  const request_upload = guarded(
877
917
  internalMutationGeneric({
878
918
  args: { caller: agentCallerValidator, input: v.any(), requestId: v.optional(v.string()) },
879
- handler: async (ctx, { caller, input: raw }) => {
880
- if (!uploads) return fail("FORBIDDEN", "This app takes no uploads.");
881
- const actor = await agent(ctx, caller);
882
- if (actor.door !== "mcp" || !uploads.scopes.some((scope) => actor.scopes.includes(scope)))
883
- fail("FORBIDDEN", "This connection may not upload files.");
884
- const { count = 1 } = inputOf(ctx, { args: requestUploadArgs }, raw);
885
- if (!Number.isSafeInteger(count) || count < 1 || count > uploadsPerRequest)
886
- fail("INVALID_INPUT", `count: a whole number from 1 to ${uploadsPerRequest}.`);
887
- const owner = actorRecord(actor);
888
- await rateLimit(ctx, `${owner.key}|writes`, agentWritesPerMinute);
889
- let waiting = 0;
890
- const now = Date.now();
891
- for (const status of ["open", "stored"]) {
892
- const rows = await lib(ctx).query("uploads").withIndex(
893
- "by_owner_status_expires",
894
- (q) => q.eq("owner.key", owner.key).eq("status", status).gt("expiresAt", now)
895
- ).take(unclaimedPerActor + 1);
896
- waiting += rows.length;
897
- }
898
- if (waiting + count > unclaimedPerActor)
899
- fail(
900
- "RATE_LIMITED",
901
- `${waiting} upload links or files of this connection wait for a claim; at most ${unclaimedPerActor} may. Use them, or wait until they expire.`
902
- );
903
- const site = process.env.CONVEX_SITE_URL;
904
- if (!site) throw new Error("CONVEX_SITE_URL is not set, so no upload link can be made.");
905
- const expiresAt = now + uploadLinkMs;
906
- const tokens = [];
907
- for (let index = 0; index < count; index++) {
908
- const token = newToken();
909
- tokens.push(token);
910
- await lib(ctx).insert("uploads", {
911
- tokenHash: await sha256Hex(new TextEncoder().encode(token)),
912
- owner,
913
- status: "open",
914
- expiresAt,
915
- maxBytes: uploads.maxBytes,
916
- types: [...uploads.types]
917
- });
918
- }
919
- return {
920
- status: "done",
921
- result: {
922
- url: new URL(uploads.path, site).toString(),
923
- method: "POST",
924
- tokens,
925
- expiresAt: new Date(expiresAt).toISOString(),
926
- maxBytes: uploads.maxBytes,
927
- types: uploads.types,
928
- howTo: 'Send each file as the raw request body, one token per file, with the header "Authorization: Bearer <token>" (curl -X POST --data-binary @file -H "Authorization: Bearer <token>" <url>). The answer has an uploadId; pass it to the tool that takes the file within 24 hours. A 401 means the token expired or was used: ask for a new one.'
919
+ handler: withEvent(
920
+ "mutation",
921
+ "agents.request_upload",
922
+ async (ctx, { caller, input: raw }, event) => {
923
+ if (!uploads) return fail("FORBIDDEN", "This app takes no uploads.");
924
+ const actor = await agent(ctx, caller);
925
+ sawActor(event, actor);
926
+ if (actor.door !== "mcp" || !uploads.scopes.some((scope) => actor.scopes.includes(scope)))
927
+ fail("FORBIDDEN", "This connection may not upload files.");
928
+ const { count = 1 } = inputOf(ctx, { args: requestUploadArgs }, raw);
929
+ if (!Number.isSafeInteger(count) || count < 1 || count > uploadsPerRequest)
930
+ fail("INVALID_INPUT", `count: a whole number from 1 to ${uploadsPerRequest}.`);
931
+ const owner = actorRecord(actor);
932
+ await rateLimit(ctx, `${owner.key}|writes`, agentWritesPerMinute);
933
+ let waiting = 0;
934
+ const now = Date.now();
935
+ for (const status of ["open", "stored"]) {
936
+ const rows = await lib(ctx).query("uploads").withIndex(
937
+ "by_owner_status_expires",
938
+ (q) => q.eq("owner.key", owner.key).eq("status", status).gt("expiresAt", now)
939
+ ).take(unclaimedPerActor + 1);
940
+ waiting += rows.length;
929
941
  }
930
- };
931
- }
942
+ if (waiting + count > unclaimedPerActor)
943
+ fail(
944
+ "RATE_LIMITED",
945
+ `${waiting} upload links or files of this connection wait for a claim; at most ${unclaimedPerActor} may. Use them, or wait until they expire.`
946
+ );
947
+ const site = process.env.CONVEX_SITE_URL;
948
+ if (!site) throw new Error("CONVEX_SITE_URL is not set, so no upload link can be made.");
949
+ const expiresAt = now + uploadLinkMs;
950
+ const tokens = [];
951
+ for (let index = 0; index < count; index++) {
952
+ const token = newToken();
953
+ tokens.push(token);
954
+ await lib(ctx).insert("uploads", {
955
+ tokenHash: await sha256Hex(new TextEncoder().encode(token)),
956
+ owner,
957
+ status: "open",
958
+ expiresAt,
959
+ maxBytes: uploads.maxBytes,
960
+ types: [...uploads.types]
961
+ });
962
+ }
963
+ return {
964
+ status: "done",
965
+ result: {
966
+ url: new URL(uploads.path, site).toString(),
967
+ method: "POST",
968
+ tokens,
969
+ expiresAt: new Date(expiresAt).toISOString(),
970
+ maxBytes: uploads.maxBytes,
971
+ types: uploads.types,
972
+ howTo: 'Send each file as the raw request body, one token per file, with the header "Authorization: Bearer <token>" (curl -X POST --data-binary @file -H "Authorization: Bearer <token>" <url>). The answer has an uploadId; pass it to the tool that takes the file within 24 hours. A 401 means the token expired or was used: ask for a new one.'
973
+ }
974
+ };
975
+ }
976
+ )
932
977
  })
933
978
  );
934
979
  const upload_ticket = guarded(
@@ -1039,10 +1084,17 @@ function defineTools(fns, modules, options) {
1039
1084
  for (const party of parties) if (await approverIn(party.tenantId)) return true;
1040
1085
  return false;
1041
1086
  }
1042
- async function decidable(ctx, approvalId) {
1087
+ async function decidable(ctx, approvalId, event) {
1043
1088
  const actor = await person(ctx);
1089
+ sawActor(event, actor);
1044
1090
  const id = lib(ctx).normalizeId("approvals", approvalId);
1045
1091
  const row = id && await lib(ctx).get(id);
1092
+ if (row) {
1093
+ event.action = row.action;
1094
+ event.agent = row.requester.key;
1095
+ event.approval = row._id;
1096
+ if (row.tenantId !== void 0) event.tenant = row.tenantId;
1097
+ }
1046
1098
  if (!row || row.status !== "pending" || !await mayDecide(ctx, actor, row)) {
1047
1099
  fail("APPROVAL_NOT_FOUND", "No open request with this ID is yours to decide.");
1048
1100
  }
@@ -1113,162 +1165,192 @@ function defineTools(fns, modules, options) {
1113
1165
  pending: guarded(
1114
1166
  queryGeneric({
1115
1167
  args: { tenantId: v.optional(v.string()) },
1116
- handler: async (ctx, { tenantId }) => {
1117
- const actor = await person(ctx);
1118
- const now = Date.now();
1119
- const listBudget = readBudget();
1120
- const { rows: mine } = await within(
1121
- lib(ctx).query("approvals").withIndex(
1122
- "by_user_status",
1123
- (q) => q.eq("requester.userId", actor.user._id).eq("status", "pending").gt("expiresAt", now)
1124
- ),
1125
- listBudget
1126
- );
1127
- const out = mine.map((row) => requestView(row, true));
1128
- if (tenantId !== void 0) {
1129
- const { rows: team } = await within(
1168
+ handler: withEvent(
1169
+ "query",
1170
+ "agents.pending",
1171
+ async (ctx, { tenantId }, event) => {
1172
+ const actor = await person(ctx);
1173
+ sawActor(event, actor);
1174
+ const now = Date.now();
1175
+ const listBudget = readBudget();
1176
+ const { rows: mine } = await within(
1130
1177
  lib(ctx).query("approvals").withIndex(
1131
- "by_tenant_status",
1132
- (q) => q.eq("tenantId", tenantId).eq("status", "pending").gt("expiresAt", now)
1178
+ "by_user_status",
1179
+ (q) => q.eq("requester.userId", actor.user._id).eq("status", "pending").gt("expiresAt", now)
1133
1180
  ),
1134
1181
  listBudget
1135
1182
  );
1136
- const { rows: parties } = await within(
1137
- lib(ctx).query("approvalParties").withIndex("by_tenant", (q) => q.eq("tenantId", tenantId).gt("expiresAt", now)),
1138
- listBudget
1139
- );
1140
- for (const party of parties) {
1141
- if (listBudget.spent) break;
1142
- const row = await lib(ctx).get(party.approvalId);
1143
- if (row) listBudget.count(row);
1144
- if (row?.status === "pending") team.push(row);
1145
- }
1146
- for (const row of team) {
1147
- if (row.requester.userId !== actor.user._id && await mayDecide(ctx, actor, row))
1148
- out.push(requestView(row, false));
1183
+ const out = mine.map((row) => requestView(row, true));
1184
+ if (tenantId !== void 0) {
1185
+ const { rows: team } = await within(
1186
+ lib(ctx).query("approvals").withIndex(
1187
+ "by_tenant_status",
1188
+ (q) => q.eq("tenantId", tenantId).eq("status", "pending").gt("expiresAt", now)
1189
+ ),
1190
+ listBudget
1191
+ );
1192
+ const { rows: parties } = await within(
1193
+ lib(ctx).query("approvalParties").withIndex("by_tenant", (q) => q.eq("tenantId", tenantId).gt("expiresAt", now)),
1194
+ listBudget
1195
+ );
1196
+ for (const party of parties) {
1197
+ if (listBudget.spent) break;
1198
+ const row = await lib(ctx).get(party.approvalId);
1199
+ if (row) listBudget.count(row);
1200
+ if (row?.status === "pending") team.push(row);
1201
+ }
1202
+ for (const row of team) {
1203
+ if (row.requester.userId !== actor.user._id && await mayDecide(ctx, actor, row))
1204
+ out.push(requestView(row, false));
1205
+ }
1149
1206
  }
1207
+ return out;
1150
1208
  }
1151
- return out;
1152
- }
1209
+ )
1153
1210
  })
1154
1211
  ),
1155
1212
  /** One request, for the approval page: what it is and whether this person may decide it. */
1156
1213
  get: guarded(
1157
1214
  queryGeneric({
1158
1215
  args: { approvalId: v.string() },
1159
- handler: async (ctx, { approvalId }) => {
1160
- const actor = await person(ctx);
1161
- const id = lib(ctx).normalizeId("approvals", approvalId);
1162
- const row = id && await lib(ctx).get(id);
1163
- if (!row || !await mayDecide(ctx, actor, row)) return null;
1164
- const status = requestStatus(row);
1165
- return {
1166
- ...requestView(row, row.requester.userId === actor.user._id),
1167
- status,
1168
- error: row.error ?? null
1169
- };
1170
- }
1216
+ handler: withEvent(
1217
+ "query",
1218
+ "agents.get",
1219
+ async (ctx, { approvalId }, event) => {
1220
+ const actor = await person(ctx);
1221
+ sawActor(event, actor);
1222
+ const id = lib(ctx).normalizeId("approvals", approvalId);
1223
+ const row = id && await lib(ctx).get(id);
1224
+ if (!row || !await mayDecide(ctx, actor, row)) return null;
1225
+ const status = requestStatus(row);
1226
+ return {
1227
+ ...requestView(row, row.requester.userId === actor.user._id),
1228
+ status,
1229
+ error: row.error ?? null
1230
+ };
1231
+ }
1232
+ )
1171
1233
  })
1172
1234
  ),
1173
1235
  /** Runs the request as the agent, with the person's approval, in this transaction. */
1174
1236
  approve: guarded(
1175
1237
  mutationGeneric({
1176
1238
  args: { approvalId: v.string() },
1177
- handler: async (ctx, { approvalId }) => {
1178
- const { actor: approver, row } = await decidable(ctx, approvalId);
1179
- let outcome;
1180
- {
1181
- const followUp = crypto.randomUUID();
1182
- await lib(ctx).patch(row._id, { status: "executing", followUp });
1183
- const ran = await ctx.runMutation(ownRef(row.tool), {
1184
- caller: row.caller,
1185
- input: row.input,
1186
- approval: { id: row._id, decidedBy: approver.user._id }
1187
- }).then(
1188
- (output) => ({ ok: true, output }),
1189
- (error) => ({ ok: false, error })
1190
- );
1191
- if (ran.ok) {
1192
- const decided = {
1193
- status: "approved",
1194
- decidedBy: approver.user._id,
1195
- decidedAt: Date.now()
1196
- };
1197
- const room = maxApprovalBytes - getConvexSize({ ...row, ...decided, followUp });
1198
- await lib(ctx).patch(row._id, {
1199
- ...decided,
1200
- result: storable(ran.output.result, Math.min(64 * 1024, room))
1201
- });
1202
- outcome = { status: "approved" };
1203
- } else {
1204
- const failure = toolFailure(ran.error);
1205
- const room = maxApprovalBytes - getConvexSize({
1206
- ...row,
1207
- status: "failed",
1208
- decidedBy: approver.user._id,
1209
- followUp,
1210
- error: { code: failure.code, message: "" }
1211
- });
1212
- const reason = boundedFailure(failure, room);
1213
- await lib(ctx).patch(row._id, {
1214
- status: "failed",
1215
- error: reason,
1216
- decidedBy: approver.user._id
1217
- });
1218
- const next = reason.code === "STALE" ? await askAgain(ctx, row) : void 0;
1219
- await record(
1220
- ctx,
1221
- next ? { ...row, requestId: void 0 } : row,
1222
- "failed",
1223
- approver.user._id,
1224
- reason
1239
+ // One transaction, one line: the work runs inside it and writes none of its own. Its
1240
+ // outcome, rows and fields are this line's; a failure after it fails the whole line.
1241
+ handler: withEvent(
1242
+ "mutation",
1243
+ "agents.approve",
1244
+ async (ctx, { approvalId }, event) => {
1245
+ const { actor: approver, row } = await decidable(ctx, approvalId, event);
1246
+ let outcome;
1247
+ {
1248
+ const followUp = crypto.randomUUID();
1249
+ await lib(ctx).patch(row._id, { status: "executing", followUp });
1250
+ const ran = await ctx.runMutation(ownRef(row.tool), {
1251
+ caller: row.caller,
1252
+ input: row.input,
1253
+ approval: { id: row._id, decidedBy: approver.user._id }
1254
+ }).then(
1255
+ (output) => ({ ok: true, output }),
1256
+ (error) => ({ ok: false, error })
1225
1257
  );
1226
- outcome = { status: "failed", error: reason, ...next ? { next } : {} };
1258
+ if (ran.ok) {
1259
+ const { written, fields } = ran.output;
1260
+ event.innerWritten = new Set(written);
1261
+ if (fields) tookFields(event, fields);
1262
+ const decided = {
1263
+ status: "approved",
1264
+ decidedBy: approver.user._id,
1265
+ decidedAt: Date.now()
1266
+ };
1267
+ const room = maxApprovalBytes - getConvexSize({ ...row, ...decided, followUp });
1268
+ await lib(ctx).patch(row._id, {
1269
+ ...decided,
1270
+ result: storable(ran.output.result, Math.min(64 * 1024, room))
1271
+ });
1272
+ outcome = { status: "approved" };
1273
+ } else {
1274
+ const failure = toolFailure(ran.error);
1275
+ const room = maxApprovalBytes - getConvexSize({
1276
+ ...row,
1277
+ status: "failed",
1278
+ decidedBy: approver.user._id,
1279
+ followUp,
1280
+ error: { code: failure.code, message: "" }
1281
+ });
1282
+ const reason = boundedFailure(failure, room);
1283
+ event.outcome = { code: failure.code };
1284
+ await lib(ctx).patch(row._id, {
1285
+ status: "failed",
1286
+ error: reason,
1287
+ decidedBy: approver.user._id
1288
+ });
1289
+ const next = reason.code === "STALE" ? await askAgain(ctx, row) : void 0;
1290
+ await record(
1291
+ ctx,
1292
+ next ? { ...row, requestId: void 0 } : row,
1293
+ "failed",
1294
+ approver.user._id,
1295
+ reason
1296
+ );
1297
+ outcome = { status: "failed", error: reason, ...next ? { next } : {} };
1298
+ }
1227
1299
  }
1300
+ await resume(ctx, row.caller);
1301
+ return outcome;
1228
1302
  }
1229
- await resume(ctx, row.caller);
1230
- return outcome;
1231
- }
1303
+ )
1232
1304
  })
1233
1305
  ),
1234
1306
  decline: guarded(
1235
1307
  mutationGeneric({
1236
1308
  args: { approvalId: v.string() },
1237
- handler: async (ctx, { approvalId }) => {
1238
- const { actor, row } = await decidable(ctx, approvalId);
1239
- await lib(ctx).patch(row._id, { status: "declined", decidedBy: actor.user._id });
1240
- await record(ctx, row, "declined", actor.user._id);
1241
- await resume(ctx, row.caller);
1242
- return null;
1243
- }
1309
+ handler: withEvent(
1310
+ "mutation",
1311
+ "agents.decline",
1312
+ async (ctx, { approvalId }, event) => {
1313
+ const { actor, row } = await decidable(ctx, approvalId, event);
1314
+ await lib(ctx).patch(row._id, { status: "declined", decidedBy: actor.user._id });
1315
+ await record(ctx, row, "declined", actor.user._id);
1316
+ await resume(ctx, row.caller);
1317
+ event.outcome = "declined";
1318
+ return null;
1319
+ }
1320
+ )
1244
1321
  })
1245
1322
  )
1246
1323
  };
1247
1324
  const activity = guarded(
1248
1325
  queryGeneric({
1249
1326
  args: { tenantId: v.optional(v.string()), limit: v.optional(v.number()) },
1250
- handler: async (ctx, { tenantId, limit }) => {
1251
- const actor = await person(ctx);
1252
- const take = Math.min(Math.max(1, limit ?? 50), 200);
1253
- let rows;
1254
- if (tenantId !== void 0) {
1255
- const tenant = tenants.refOf(ctx.db, tenantId);
1256
- if (!tenant || await roleOf(readOnly(ctx), actor.user, tenant) === null)
1257
- fail("NOT_FOUND", "Nothing with these IDs was found.");
1258
- rows = await lib(ctx).query("activity").withIndex("by_tenant", (q) => q.eq("tenantId", tenantId)).order("desc").take(take);
1259
- } else {
1260
- rows = await lib(ctx).query("activity").withIndex("by_user", (q) => q.eq("actor.userId", actor.user._id)).order("desc").take(take);
1327
+ handler: withEvent(
1328
+ "query",
1329
+ "agents.activity",
1330
+ async (ctx, { tenantId, limit }, event) => {
1331
+ const actor = await person(ctx);
1332
+ sawActor(event, actor);
1333
+ const take = Math.min(Math.max(1, limit ?? 50), 200);
1334
+ let rows;
1335
+ if (tenantId !== void 0) {
1336
+ const tenant = tenants.refOf(ctx.db, tenantId);
1337
+ if (!tenant || await roleOf(readOnly(ctx), actor.user, tenant) === null)
1338
+ fail("NOT_FOUND", "Nothing with these IDs was found.");
1339
+ rows = await lib(ctx).query("activity").withIndex("by_tenant", (q) => q.eq("tenantId", tenantId)).order("desc").take(take);
1340
+ } else {
1341
+ rows = await lib(ctx).query("activity").withIndex("by_user", (q) => q.eq("actor.userId", actor.user._id)).order("desc").take(take);
1342
+ }
1343
+ return rows.map((row) => ({
1344
+ id: row._id,
1345
+ at: row._creationTime,
1346
+ actor: row.actor,
1347
+ action: row.action,
1348
+ tool: row.tool ?? null,
1349
+ status: row.status,
1350
+ decidedBy: row.decidedBy ?? null
1351
+ }));
1261
1352
  }
1262
- return rows.map((row) => ({
1263
- id: row._id,
1264
- at: row._creationTime,
1265
- actor: row.actor,
1266
- action: row.action,
1267
- tool: row.tool ?? null,
1268
- status: row.status,
1269
- decidedBy: row.decidedBy ?? null
1270
- }));
1271
- }
1353
+ )
1272
1354
  })
1273
1355
  );
1274
1356
  const housekeeping = markHousekeeping(