feat(ai): actions opt in to AI tools via ai: block (ADR-0011)#1581
Merged
Conversation
Realign ADR-0011 with its original opt-in design and finalise the implementation. An Action becomes an AI-callable tool only when it sets `ai.exposed: true`, which requires an explicit LLM-facing `ai.description` (distinct from the UI `label`). No heuristic auto-exposure, no label-derived descriptions — a clean break from the first implementation's opt-out `aiExposed` flag, which is removed outright (no compat shim; not yet shipped). - spec: ActionAiSchema (exposed/description/category/paramHints/outputSchema/ requiresConfirmation) + refines; remove aiExposed; extend AIToolDefinition with category/outputSchema/objectName/requiresConfirmation; update action.form. - service-ai: bridge gates on opt-in, uses ai.description, merges paramHints, summarises outputSchema into the description, honours requiresConfirmation override, and warns on exposed destructive actions asserted safe. - examples/app-todo: migrate script actions to opt-in (testbed). - docs: rewrite ADR-0011 to Accepted/Implemented with the AI-author rationale. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
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.
What
Implements ADR-0011 (Actions as AI Tools) with the opt-in
ai:block design, and realigns the ADR doc with what's now built.An Action becomes an AI-callable tool only when it opts in (
ai.exposed: true), which requires an explicit, LLM-facingai.description(≥40 chars, distinct from the UIlabel). No heuristic auto-exposure, no label-derived descriptions.Why opt-in (and why now)
The first implementation (same day as the original draft) shortcut to opt-out + heuristic auto-exposure + label-derived descriptions — contradicting two explicit points of the ADR. In an AI-authoring world, writing a description is no longer a burden (the AI author writes it for free), so the only thing opt-in costs is friction that no longer exists — while the governance gate it provides (a human decides which capabilities the agent fleet may invoke) becomes the platform's core value. Since the platform has not yet shipped, this is a clean break: the
aiExposedfield is removed outright, no compat shim.Changes
ActionAiSchema(exposed/description/category/paramHints/outputSchema/requiresConfirmation) onActionSchema+ refine rules (exposed⇒description; paramHints keys ⊆ params); remove flataiExposed; extendAIToolDefinitionwithcategory/outputSchema/objectName/requiresConfirmation; Studioaction.formaiExposed→aiblock.action-tools.tsbridge gates on opt-in, usesai.description, mergesparamHints, summarisesoutputSchemainto the description, honours therequiresConfirmationoverride (reuses the existing HITL approval queue), and emits a lint warning when an exposed destructive-looking action asserts itself safe.Verification
@objectstack/specand@objectstack/service-aibuild + DTS clean.delete_completedonly when approval is wired. (The demo'ssys_user"no such table" exit is pre-existing — confirmed identical on baseline with these changes stashed — and unrelated to exposure.)🤖 Generated with Claude Code