{"type":"dev.nipmod.agent-package-advisor.v1","status":"live","updatedAt":"2026-06-06","purpose":"Plan package decisions before ranking. Broad requests get clarification questions first; specific requests move to /api/decision with the right source families and no hosted execution.","supportedSourceCount":20,"supportedSources":["npm","jsr","pypi","cratesio","go","maven","nuget","rubygems","packagist","dockerhub","homebrew","terraform","helm","conda","openvsx","cran","github","huggingface-model","huggingface-dataset","mcp"],"sourceDepthChecklist":[{"id":"source-identity","requirement":"Bind the selected package to source, name, version, original URL, owner and repository when returned.","readFrom":["selected","decision.provenance.identity","decision.provenance.sourceBinding"]},{"id":"install-boundary","requirement":"Treat install commands as review data only until approvalPacket and approvalGate allow the local host to continue.","readFrom":["installPlan","approvalPacket.commands","approvalGate"]},{"id":"source-evidence","requirement":"Review per-source checks, missing evidence and depth score before trusting the recommendation.","readFrom":["sourceEvidenceBundle","decision.sourceEvidenceReview","decision.evidence.selected.sourceChecks"]},{"id":"security-review","requirement":"Read advisory, license, dependency, malware, metadata-instruction and confusion review before approval.","readFrom":["decision.advisoryReview","decision.licenseReview","decision.dependencyRiskReview","decision.malwarePatternReview","decision.confusionReview"]},{"id":"permission-scope","requirement":"For MCP, browser, GitHub, infrastructure, model or wallet-related tasks, state permissions before enabling tools.","readFrom":["queryClarification","decision.hostActionPolicy","approvalPacket.approval.requirementsBeforeApproval"]},{"id":"revalidation","requirement":"Refresh before local action when cache, version, source identity or provenance freshness changed.","readFrom":["decision.revalidationPolicy","decision.integrity.compareBeforeApproval","approvalPacket.compareBeforeApproval"]}],"defaultFlow":["Read the user's package, model, repository, SDK, CLI, MCP or workflow request.","Call /api/advisor or apply the same advisor rules locally.","If mode is ask-first, ask the returned questions before ranking a package.","When the user answers, create an AgentPackageAdvisorFollowUp by merging the original request with the answer text.","If followUp.readyForDecision is true, call /api/decision with followUp.apiPlan.decisionRequestBody instead of asking the same questions again.","If mode is provisional-shortlist, show a provisional shortlist only and ask the missing risk or stack question before approval.","Call /api/decision with x-nipmod-api-key after enough stack, feature and risk context exists.","Read agentHandoff, decisionBrief, comparisonMatrix, approvalPacket and approvalGate before any local action.","Do not install, clone, enable tools, load models, run containers, apply infrastructure or write files before approval."],"examples":[{"label":"Too broad","query":"hey what package do I need for websites?","expectedMode":"ask-first","expectedBehavior":"Ask what the website does, which stack will use it and whether production, credentials or user data are involved."},{"label":"Specific enough","query":"Next.js auth package for production OAuth login","expectedMode":"ready-for-decision","expectedBehavior":"Run a decision across web app sources, then keep install blocked until the approval packet is reviewed."},{"label":"Agent tool risk","query":"MCP server for GitHub issues with read-only permissions","expectedMode":"ready-for-decision","expectedBehavior":"Focus MCP, GitHub, npm and PyPI sources, then show permission scope before enablement."}],"publicEndpoints":{"advisor":"GET https://nipmod.com/api/advisor?q=<query>&sources=<optional>&limit=5","advisorFollowUp":"POST https://nipmod.com/api/advisor with { query, answers, sources?, limit? }","decision":"GET https://nipmod.com/api/decision?q=<query>&sources=<sources>&limit=5 with x-nipmod-api-key","machinePack":"GET https://nipmod.com/agent-package-advisor.json"}}