HyperXosist-Agent AGENTS.md

AGENTS.md — HyperXosist Agent

Instructions for any AI coding / research agent (GPT, Claude, Grok, Llama, local tool-callers).

What this is

HyperXosist builds high-signal X (Twitter) advanced search queries with noise reduction.
It does not scrape X. It produces queries + official search URLs.
Planning, filtering, and handoff are free. Automated production execution uses x402.

Default mode: universal. Grok Build is an optional powerful mode (mode: "grok").

Dual output

Core methods return structured JSON and often attach:

• .markdown — human/LLM-readable summary
• .asMarkdown() / .asJson() helpers

Prefer JSON for tool dispatch; use markdown when pasting into a chat model.

Fast path (copy this)

A) Tool-calling agents (OpenAI / Anthropic / Grok / Llama)

// Register tools (pick one schema):
const openaiTools = HyperXosistAgent.toOpenAITools();       // Chat Completions
const anthropicTools = HyperXosistAgent.toAnthropicTools(); // Messages API

// On every tool call from the model — ONE dispatcher for all runtimes:
const out = HyperXosistAgent.dispatchToolCall(toolName, toolArgs);
// also accepts OpenAI { function: { name, arguments } } and Anthropic { name, input }
// → out.ok, out.result

B) Shell / CLI agents (no embed required)

npx hyperxosist plan "Find product feedback about <PRODUCT> for PR specs" --json
npx hyperxosist dispatch hyperxosist_plan_from_intent --args '{"intent":"Find feedback about <PRODUCT>"}' --json
npx hyperxosist tools --format openai --json
npx hyperxosist tools --format anthropic --json
npx hyperxosist keep --product <PRODUCT> --feedback '["post1","post2"]' --export-keep-only --json
npx hyperxosist handoff --product <PRODUCT> --feedback '["…"]' --json

C) Library sticky loop

// 1) Bootstrap (universal — all LLMs)
const session = HyperXosistAgent.startAgentSession({
  intent: 'Find product feedback about <PRODUCT> for PR specs'
});

// 2) Plan
const plan = session.plan; // planFromIntent
const step = plan.primaryStep;

// 3) Score gate
if (!step.score.recommendPay) {
  // try plan.refinements.best.input
}

// 4) Pay (x402) then search
const paid = step.paidRequest;
// POST paid.body → paid.endpoint  (402 until payment proof)
// After 200: open step.searchUrl, collect candidate post texts

// 5) Self-heal if empty
// HyperXosistAgent.suggestRefinements(step.input, { tooSparse: true })

// 6) Keep-only export (any coding agent) + Signal-to-Fix
const keepOnly = HyperXosistAgent.exportKeepOnlyJson(feedback, {
  productName: '<PRODUCT>',
  targetArea: 'auth'
});
// → keepOnly.texts / keepOnly.signalToFixInput / keepOnly.agentPrompt

const pipeline = HyperXosistAgent.buildSignalToFixPipeline({
  productName: '<PRODUCT>',
  feedback: [/* posts */],
  targetArea: 'auth',
  context: 'optional product context'
});
// → pipeline.humanManual — show humans the free browser steps
// → pipeline.agentAuto.steps — ordered auto execution
// → pipeline.handoff.signalToFix.input → Signal-to-Fix (keep-only)
// Or:
const handoff = HyperXosistAgent.buildHandoffPackage({
  productName: '<PRODUCT>',
  feedback: [/* posts */],
  context: 'optional product context'
});
// → handoff.signalToFix.input → Signal-to-Fix
// → handoff.agentPrompt.markdown → any coding LLM

// Optional: model-agnostic implementation prompt only
const prompt = HyperXosistAgent.buildAgentPrompt({
  productName: '<PRODUCT>',
  targetArea: 'auth',
  feedback
});

// 7) Receipt
HyperXosistAgent.buildRunReceipt({
  input: step.input,
  paymentCompleted: true,
  resultCount: feedback.length,
  missionId: plan.missionId
});