1 line
11 KiB
JavaScript
1 line
11 KiB
JavaScript
"use strict";(globalThis.webpackChunkproject_public_docs=globalThis.webpackChunkproject_public_docs||[]).push([[203],{1154(e,n,t){t.r(n),t.d(n,{assets:()=>d,contentTitle:()=>r,default:()=>h,frontMatter:()=>l,metadata:()=>s,toc:()=>a});const s=JSON.parse('{"id":"reference/meta-tools","title":"Meta-Tools: Tools That Call Other Tools","description":"Meta-tools are CmdForge tools that can invoke other tools as steps in their workflow. This enables powerful composition and reuse of existing tools.","source":"@site/docs/reference/meta-tools.md","sourceDirName":"reference","slug":"/reference/meta-tools","permalink":"/rob/CmdForge/reference/meta-tools","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"sidebar_label":"Meta-Tools","sidebar_position":2,"format":"md"},"sidebar":"docs","previous":{"title":"Registry API","permalink":"/rob/CmdForge/reference/registry-spec"},"next":{"title":"Collections","permalink":"/rob/CmdForge/reference/collections"}}');var o=t(4848),i=t(8453);const l={sidebar_label:"Meta-Tools",sidebar_position:2,format:"md"},r="Meta-Tools: Tools That Call Other Tools",d={},a=[{value:"Step Type: <code>tool</code>",id:"step-type-tool",level:2},{value:"Manifest Format",id:"manifest-format",level:3},{value:"Resolution Order",id:"resolution-order",level:3},{value:"Tool Step Properties",id:"tool-step-properties",level:3},{value:"Execution",id:"execution",level:3},{value:"Error Handling",id:"error-handling",level:3},{value:"Dependency Resolution",id:"dependency-resolution",level:2},{value:"Declaring Dependencies",id:"declaring-dependencies",level:3},{value:"CLI Integration",id:"cli-integration",level:3},{value:"Dependency Checking",id:"dependency-checking",level:3},{value:"Security Considerations",id:"security-considerations",level:2},{value:"Example: Multi-Step Analysis Pipeline",id:"example-multi-step-analysis-pipeline",level:2},{value:"Future Enhancements",id:"future-enhancements",level:2}];function c(e){const n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"meta-tools-tools-that-call-other-tools",children:"Meta-Tools: Tools That Call Other Tools"})}),"\n",(0,o.jsx)(n.p,{children:"Meta-tools are CmdForge tools that can invoke other tools as steps in their workflow. This enables powerful composition and reuse of existing tools."}),"\n",(0,o.jsxs)(n.h2,{id:"step-type-tool",children:["Step Type: ",(0,o.jsx)(n.code,{children:"tool"})]}),"\n",(0,o.jsxs)(n.p,{children:["A step type ",(0,o.jsx)(n.code,{children:"tool"})," allows calling another CmdForge tool from within a tool's workflow."]}),"\n",(0,o.jsx)(n.h3,{id:"manifest-format",children:"Manifest Format"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-yaml",children:'name: summarize-and-translate\ndescription: Summarize text then translate the summary\nversion: 1.0.0\ncategory: Text\n\nsteps:\n - type: tool\n tool: official/summarize # Tool to call (owner/name or just name for local)\n input: "{input}" # What to pass as input (supports variable substitution)\n args: # Optional arguments to pass to the tool\n max_words: "100"\n output_var: summary # Variable to store the output\n\n - type: tool\n tool: official/translate\n input: "{summary}" # Use output from previous step\n args:\n target_language: "{language}" # Can use tool\'s own arguments\n output_var: translated\n\noutput: "{translated}"\n\narguments:\n - flag: "--language"\n variable: language\n default: "Spanish"\n description: "Target language for translation"\n'})}),"\n",(0,o.jsx)(n.h3,{id:"resolution-order",children:"Resolution Order"}),"\n",(0,o.jsxs)(n.p,{children:["When resolving a tool reference in a ",(0,o.jsx)(n.code,{children:"tool"})," step:"]}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Fully qualified"}),": ",(0,o.jsx)(n.code,{children:"owner/name"})," - looks up in registry or installed tools"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Local tool"}),": Just ",(0,o.jsx)(n.code,{children:"name"})," - checks local ",(0,o.jsx)(n.code,{children:"~/.cmdforge/<name>/config.yaml"})," first"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Registry fallback"}),": If not found locally, checks installed registry tools"]}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"tool-step-properties",children:"Tool Step Properties"}),"\n",(0,o.jsxs)(n.table,{children:[(0,o.jsx)(n.thead,{children:(0,o.jsxs)(n.tr,{children:[(0,o.jsx)(n.th,{children:"Property"}),(0,o.jsx)(n.th,{children:"Required"}),(0,o.jsx)(n.th,{children:"Description"})]})}),(0,o.jsxs)(n.tbody,{children:[(0,o.jsxs)(n.tr,{children:[(0,o.jsx)(n.td,{children:(0,o.jsx)(n.code,{children:"type"})}),(0,o.jsx)(n.td,{children:"Yes"}),(0,o.jsxs)(n.td,{children:["Must be ",(0,o.jsx)(n.code,{children:'"tool"'})]})]}),(0,o.jsxs)(n.tr,{children:[(0,o.jsx)(n.td,{children:(0,o.jsx)(n.code,{children:"tool"})}),(0,o.jsx)(n.td,{children:"Yes"}),(0,o.jsx)(n.td,{children:"Tool reference (owner/name or name)"})]}),(0,o.jsxs)(n.tr,{children:[(0,o.jsx)(n.td,{children:(0,o.jsx)(n.code,{children:"input"})}),(0,o.jsx)(n.td,{children:"No"}),(0,o.jsxs)(n.td,{children:["Input to pass to the tool (default: current ",(0,o.jsx)(n.code,{children:"{input}"}),")"]})]}),(0,o.jsxs)(n.tr,{children:[(0,o.jsx)(n.td,{children:(0,o.jsx)(n.code,{children:"args"})}),(0,o.jsx)(n.td,{children:"No"}),(0,o.jsx)(n.td,{children:"Dictionary of arguments to pass"})]}),(0,o.jsxs)(n.tr,{children:[(0,o.jsx)(n.td,{children:(0,o.jsx)(n.code,{children:"output_var"})}),(0,o.jsx)(n.td,{children:"Yes"}),(0,o.jsx)(n.td,{children:"Variable name to store the tool's output"})]}),(0,o.jsxs)(n.tr,{children:[(0,o.jsx)(n.td,{children:(0,o.jsx)(n.code,{children:"provider"})}),(0,o.jsx)(n.td,{children:"No"}),(0,o.jsx)(n.td,{children:"Override provider for the called tool"})]})]})]}),"\n",(0,o.jsx)(n.h3,{id:"execution",children:"Execution"}),"\n",(0,o.jsxs)(n.p,{children:["When a ",(0,o.jsx)(n.code,{children:"tool"})," step executes:"]}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsx)(n.li,{children:"Resolve the tool reference to find the tool definition"}),"\n",(0,o.jsxs)(n.li,{children:["Substitute variables in ",(0,o.jsx)(n.code,{children:"input"})," and ",(0,o.jsx)(n.code,{children:"args"})," values"]}),"\n",(0,o.jsx)(n.li,{children:"Execute the tool with the resolved input and arguments"}),"\n",(0,o.jsxs)(n.li,{children:["Capture the output in the specified ",(0,o.jsx)(n.code,{children:"output_var"})]}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"error-handling",children:"Error Handling"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"If a called tool fails, the parent tool fails with an appropriate error"}),"\n",(0,o.jsx)(n.li,{children:"Tool not found errors include helpful installation suggestions"}),"\n",(0,o.jsx)(n.li,{children:"Circular dependencies are detected and prevented"}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"dependency-resolution",children:"Dependency Resolution"}),"\n",(0,o.jsx)(n.h3,{id:"declaring-dependencies",children:"Declaring Dependencies"}),"\n",(0,o.jsx)(n.p,{children:"Tools can declare their dependencies in the config:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-yaml",children:"name: my-meta-tool\ndependencies:\n - official/summarize\n - official/translate@^1.0.0 # With version constraint\n"})}),"\n",(0,o.jsx)(n.h3,{id:"cli-integration",children:"CLI Integration"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"# Install a tool and its dependencies\ncmdforge install official/summarize-and-translate\n\n# Check if dependencies are satisfied\ncmdforge check my-meta-tool\n\n# Install missing dependencies\ncmdforge install --deps my-meta-tool\n"})}),"\n",(0,o.jsx)(n.h3,{id:"dependency-checking",children:"Dependency Checking"}),"\n",(0,o.jsx)(n.p,{children:"Before running a meta-tool, the runner verifies all dependencies are installed:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-python",children:'def check_dependencies(tool: Tool) -> List[str]:\n """Returns list of missing dependencies."""\n missing = []\n for dep in tool.dependencies:\n if not is_tool_installed(dep):\n missing.append(dep)\n return missing\n'})}),"\n",(0,o.jsx)(n.h2,{id:"security-considerations",children:"Security Considerations"}),"\n",(0,o.jsxs)(n.ol,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Sandboxing"}),": Called tools run in the same process context as the parent"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Input validation"}),": All inputs are treated as untrusted strings"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"No shell execution"}),": Tool references cannot contain shell commands"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Depth limit"}),": Maximum nesting depth (default: 10) prevents runaway recursion"]}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"example-multi-step-analysis-pipeline",children:"Example: Multi-Step Analysis Pipeline"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-yaml",children:'name: code-review-pipeline\ndescription: Comprehensive code review using multiple specialized tools\nversion: 1.0.0\ncategory: Developer\n\ndependencies:\n - official/analyze-complexity\n - official/find-bugs\n - official/suggest-improvements\n\nsteps:\n # Step 1: Analyze code complexity\n - type: tool\n tool: official/analyze-complexity\n input: "{input}"\n output_var: complexity_report\n\n # Step 2: Find potential bugs\n - type: tool\n tool: official/find-bugs\n input: "{input}"\n output_var: bug_report\n\n # Step 3: Generate improvement suggestions based on findings\n - type: tool\n tool: official/suggest-improvements\n input: |\n ## Code:\n {input}\n\n ## Complexity Analysis:\n {complexity_report}\n\n ## Bug Report:\n {bug_report}\n output_var: suggestions\n\noutput: |\n # Code Review Results\n\n ## Complexity Analysis\n {complexity_report}\n\n ## Potential Issues\n {bug_report}\n\n ## Improvement Suggestions\n {suggestions}\n'})}),"\n",(0,o.jsx)(n.h2,{id:"future-enhancements",children:"Future Enhancements"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Parallel tool execution"}),": Run independent tool steps concurrently"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Conditional execution"}),": Skip steps based on conditions"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Tool aliases"}),": Define shorthand names for frequently used tools"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.strong,{children:"Caching"}),": Cache tool outputs for identical inputs"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(c,{...e})}):c(e)}},8453(e,n,t){t.d(n,{R:()=>l,x:()=>r});var s=t(6540);const o={},i=s.createContext(o);function l(e){const n=s.useContext(i);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:l(e.components),s.createElement(i.Provider,{value:n},e.children)}}}]); |