Add @describe capability to describe agent / actions#2671
Merged
Conversation
… natural language
- Fix CodeQL-flagged incomplete escaping in escapeTableCell: escape backslashes before pipes so a literal backslash can't combine with the pipe-escape into an ambiguous sequence. - Rename shadowing local variable in describeActionHandler.ts (describeAction -> nlAction) to avoid confusion with the describeCore.ts function of the same name. - Restructure resolveAction's dotted schema.action lookup to make the 'schema names are unique across agents' invariant explicit instead of implied by a loop-with-early-return. - Inline the single-use isSchemaEnabledFn factory at its one call site. - Split extractActionParameters into findParametersBlock (structural brace-matching scan) and parseParameterFields (line-based field parsing) - two independently-testable concerns that were glued into one function. - Add a one-line rationale comment for the closestMatch edit-distance threshold formula. - Add regression tests for the escaping fix. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Code-quality pass on the @Describe core: - Extract agentTitle() so the deterministic summary and LLM-polished header share one bolded heading (fixes divergent punctuation). - Extract didYouMean() and renderAndPolishAction() to remove duplication. - Derive the agent table header/separator from a single columns array. - Drop the dead 'nameMatch === undefined' branch (exec() returns null). - Rename complete() -> tryComplete() to signal its graceful-failure contract. - Use strict '!== undefined' for the optional agentName filter. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…scribe The system.describe NL handler forwards to the @Describe command (which renders the markdown itself) and previously returned undefined, so the dispatcher appended its generic 'Action <name> completed.' fallback on top of the real output. Return a no-display ActionResult instead so only the describe markdown is shown; record a concise historyText for memory. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace the full O(a*b)-space matrix with the O(min(a,b))-space two-row form (matching the proven @typeagent/agent-flows levenshtein). Behavior is identical; kept local rather than adding a dispatcher -> agent-flows dependency for a ~15-line primitive. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace the inline schemaName.split('.')[0] with the canonical
getAppAgentName() helper (translation/agentTranslators.ts) used by 40+
other dispatcher call sites. Self-documenting and consistent; the grouping
loop itself stays local (only bucket-all caller, not worth a shared abstraction).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Member
|
there is also the |
…ndler calls core directly The describe files introduced 5 new circular-dependency cycles that failed the CI ratchet. Four closed via CommandHandlerContext imported as a value but used only as a type; the fifth via describeActionHandler forwarding through the \@Describe\ command (processCommandNoLock in command.ts). Fixes: - Import CommandHandlerContext with \import type\ in the four describe files (madge's skipTypeImports drops type-only edges), breaking the first four cycles. - Have the NL handler (describeActionHandler) call describeCore directly and append the markdown itself, instead of string-forwarding through the command. This removes the command.ts edge (breaks the fifth cycle), drops the quoteArg escaping, and makes describeCore the single shared implementation for both entry points. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
curtisman
reviewed
Jul 14, 2026
curtisman
reviewed
Jul 14, 2026
curtisman
reviewed
Jul 14, 2026
curtisman
approved these changes
Jul 14, 2026
…llback Adds a getActionDescription(actionType) helper to @typeagent/action-schema (the action description is the first line of its doc comment, else undefined) and reuses it in both agentSchemaInfo.extractActions and unknownSwitcher, per review feedback. Also drops extractActions' name-derived description fallback: a camelCase->spaced rendering of the action name (e.g. sendEmail -> 'Send Email') just duplicates the Name column in the table and adds no signal to the LLM prompt. Actions with no comment now get an empty description; renderActionView omits the trailing em dash in that case. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Author
I've been thinking about it and I do agree that instinctively @help feels like it should be merged. They function differently under the hood and operate on different sources (command tree vs action schema). I might do a follow up PR that adds a similar NL rule to allow @help to function the same way and let @Describe also describe the agent commands. But I'm not entirely convinced yet that we should merge their scopes |
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
4 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.
Add
@describe— capability discovery for agents and actionsSummary
Adds a new
@describecommand (and matchingsystem.describenatural-language schema) that answers "what can this do?" — a read-only capability summary, distinct from@actionwhich executes. It works even for installed-but-disabled agents, so users can discover what an agent offers before enabling it. Intended for new users who may or may not visit our repo and have no familiarity with our agents/actions.Usage
@describe <agent>— agent summary + a table of its first 10 actions@describe <agent> --all/-a— full action table, no truncation@describe <agent> <action>— detailed explanation of one action, including its parameters@describe <action>— same, when the action name alone is unambiguous across agentsAgent Describe Command
Agent Describe NL
Action Description
