feat(backend,shared): Add AgentAction resource types - #9542
Draft
wyattjoh wants to merge 6 commits into
Draft
Conversation
Chunk 1 of the clerk.policy surface: the wire interfaces, resource classes, and deserializer arms for agent actions. No consumer yet — the PolicyAPI endpoint class that returns these lands in the next layer.
🦋 Changeset detectedLatest commit: a3bdca7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 23 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-google-signin
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
wyattjoh
changed the title
- @experimental tags carry the version-pin recommendation, matching the agentTasks and billing pattern impl-sdk.md §8 names - cross-resource JSDoc links use {@link} rather than same-page anchors, which resolved to nothing because each type gets its own docs page - approval and resolution map to null rather than undefined when the key is absent, and parameters_display tolerates omission - the evaluation-errors mapping is shared by both fromJSON implementations - tests cover the approval block surviving resolution, a never-pending expiresAt, an absent evaluation_errors, and a deny decision
Convert `AgentActionApproval`, `AgentActionResolution`, and `AgentActionEvaluationError` from plain object types to classes with their own `fromJSON`, matching how every other nested wire object in `resources/` is modelled (`SessionActivity`, `IdentificationLink`, `Verification`). Each type's snake-to-camel mapping now sits beside its declaration instead of inlined into the `AgentAction` constructor call, and both ternaries there collapse to the `data.x && Class.fromJSON(data.x)` shape used elsewhere in the package. `AgentActionParametersDisplay` stays a plain type: its wire and domain shapes are identical, so a class would need an identity `fromJSON`. For the same reason `parameters_display` now passes through by reference rather than being rebuilt field by field — the wire type declares it neither optional nor nullable, and passing it untouched is the most literal expression of the rule that a display key's spelling is never transformed. Also documents the status-versus-effect split on `AgentActionStatus.effect`, where a polling caller is most likely to reach for the wrong field, and trims five multi-line comment blocks to single lines per the repo's comment rule. No behaviour change; the existing tests pass unmodified.
Remove test comments citing `api-contracts-v1` and `§3.2`: those documents are not reachable from this repository, so the citation cannot be followed by anyone reading here. The behaviours they described are already named by the test titles and asserted by the tests themselves. Remove the Deserializer note about the absent `agent_action_decision` arm. A test asserts the fall-through and fails if the arm is ever added, which makes the comment a second, non-enforcing copy of a claim already pinned in code. Remove the "Not to be confused with" sentences from `AgentAction` and `AgentTask`. They documented an alphabetical adjacency in `ObjectType` rather than anything about either class, and one of them altered the published JSDoc of an existing resource to point at a type no release contains yet. Merge the two changesets into one entry covering both packages, and name the `AgentActionStatus` / `AgentActionStatusValue` split so consumers know which export carries the union.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Applications that let an agent act for a user need to ask, before the agent does something consequential, whether policy allows it or whether a human has to approve first.
clerk.policyis that surface in@clerk/backend. It is being built as four stacked PRs, and this is the bottom one: data types only, so nothing in the package calls them yet.parametersand eachparametersDisplay[].keyare copied throughfromJSONexactly as the API sent them. The key spelling an application passes tocheck()is the same spelling its policy rules use to address that value, so camelCasingrefund_amounthere would produce a rule that quietly never matches. It is the one place the package's usual camelCase habit is wrong.The status union lands in
@clerk/sharedrather than@clerk/backendbecause the approval review UI projects the same column and the two should not drift.Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change