@sdods/agents 0.2.0

package/dist/roles/index.js

@@ -0,0 +1,125 @@
+import { renderPrompt, ROLE_PROMPTS } from '@sdods/mcp/prompts';
+import { toAgentSdkTools } from '@sdods/mcp';
+export { ROLE_PROMPTS };
+const COMMON_READ = [
+    'project_',
+    'workspace_',
+    'process_',
+    'feature_list',
+    'feature_read',
+    'feature_parse',
+    'feature_lint',
+    'step_',
+    'run_get',
+    'run_list',
+    'run_last_failed',
+    'heal_',
+    'data_',
+    'analyze_',
+    'proposal_list',
+    'proposal_get',
+];
+export const ROLES = {
+    planner: {
+        role: 'planner',
+        toolPrefixes: [...COMMON_READ, 'feature_write'],
+        smallTools: [
+            'project_get_config',
+            'feature_list',
+            'analyze_routes',
+            'analyze_coverage',
+            'step_find',
+            'feature_write',
+        ],
+        needsBrowser: true,
+        defaults: { maxTurns: 30, budgetUsd: 5 },
+        buildPrompt: (i) => `Plan test coverage for project ${i.project ?? '<unknown>'}${i.env ? ` on ${i.env}` : ''}.\nGoal: ${i.goal ?? 'cover the main user journeys'}.\nWrite the plan as docs/test-plans/<name>.md through feature_write's extraFiles (path relative to the project root: ../../docs/test-plans is NOT allowed; use docs/test-plans/<name>.md under the project).`,
+        buildSmallPrompt: (i) => `Write a test plan for project ${i.project ?? '<unknown>'}.\nGoal: ${i.goal ?? 'cover the main user journeys'}.\nCall feature_write once, with the plan as an extra file named docs/test-plans/plan.md.`,
+    },
+    generator: {
+        role: 'generator',
+        toolPrefixes: [...COMMON_READ, 'feature_write', 'run_tests'],
+        // run_tests is deliberately absent: it carries the two largest schemas in the registry and a
+        // small model that calls it spends minutes on output it cannot read. A person reviews the
+        // proposal anyway.
+        smallTools: ['step_find', 'feature_list', 'feature_read', 'feature_parse', 'feature_write'],
+        needsBrowser: true,
+        defaults: { maxTurns: 40, budgetUsd: 3 },
+        buildPrompt: (i) => `Generate feature files for project ${i.project ?? '<unknown>'}${i.env ? ` on ${i.env}` : ''}.\n${i.plan ? `Plan:\n${i.plan}\n` : ''}${i.spec ? `Recorded spec to convert:\n\`\`\`ts\n${i.spec}\n\`\`\`\n` : ''}Goal: ${i.goal ?? 'implement the plan'}.\nCall step_list first, then feature_parse on your draft, then feature_write.`,
+        buildSmallPrompt: (i) => `Write one feature file for project ${i.project ?? '<unknown>'}.\nGoal: ${i.goal ?? 'implement the plan'}.\n${i.spec ? `Base it on this recording:\n\`\`\`ts\n${i.spec}\n\`\`\`\n` : ''}Call feature_write now, using only the step patterns listed above.`,
+    },
+    healer: {
+        role: 'healer',
+        toolPrefixes: [...COMMON_READ, 'feature_write', 'run_tests', 'analyze_failure'],
+        smallTools: [
+            'analyze_failure',
+            'run_get_scenario',
+            'heal_events',
+            'feature_read',
+            'feature_write',
+        ],
+        needsBrowser: true,
+        defaults: { maxTurns: 30, budgetUsd: 2 },
+        buildPrompt: (i) => `Heal scenario ${i.scenario ?? '<fingerprint>'} of run ${i.runId ?? 'last'} in project ${i.project ?? '<unknown>'}.\nStart with analyze_failure and run_get_scenario. Propose the minimal fix via feature_write (extraFiles for page objects/steps).`,
+        buildSmallPrompt: (i) => `Scenario "${i.scenario ?? '<fingerprint>'}" of run ${i.runId ?? 'last'} in project ${i.project ?? '<unknown>'} is failing.\nCall analyze_failure now to find out why.`,
+    },
+    upgrader: {
+        role: 'upgrader',
+        toolPrefixes: [...COMMON_READ, 'feature_write'],
+        smallTools: [
+            'analyze_change_impact',
+            'analyze_coverage',
+            'feature_list',
+            'feature_read',
+            'feature_write',
+        ],
+        needsBrowser: false,
+        defaults: { maxTurns: 30, budgetUsd: 3 },
+        buildPrompt: (i) => `Upgrade the tests of project ${i.project ?? '<unknown>'} for the change ${i.diff ?? 'HEAD~1..HEAD'}.\nStart with analyze_change_impact and analyze_coverage.${i.goal ? `\nFocus: ${i.goal}` : ''}`,
+        buildSmallPrompt: (i) => `Code changed in project ${i.project ?? '<unknown>'} (${i.diff ?? 'HEAD~1..HEAD'}).\nCall analyze_change_impact now to find the scenarios it affects.`,
+    },
+    reviewer: {
+        role: 'reviewer',
+        toolPrefixes: [...COMMON_READ, 'feature_write'],
+        smallTools: [
+            'feature_list',
+            'feature_read',
+            'analyze_best_practices',
+            'analyze_locators',
+            'feature_parse',
+        ],
+        needsBrowser: false,
+        defaults: { maxTurns: 15, budgetUsd: 1 },
+        buildPrompt: (i) => `Review ${i.files?.length ? i.files.join(', ') : 'all feature files'} of project ${i.project ?? '<unknown>'}.\nUse analyze_best_practices, analyze_locators and feature_parse.${i.goal ? `\nFocus: ${i.goal}` : ''}`,
+        buildSmallPrompt: (i) => `Review the feature files of project ${i.project ?? '<unknown>'}${i.goal ? ` for: ${i.goal}` : ''}.\nCall feature_list now, then read the files it names.`,
+    },
+};
+/** The user-facing request for a role, in the shape the profile can act on. */
+export function rolePrompt(role, input, profile = 'full') {
+    const def = ROLES[role];
+    return profile === 'small' ? def.buildSmallPrompt(input) : def.buildPrompt(input);
+}
+export function roleSystemPrompt(role, input, steps, profile = 'full') {
+    return renderPrompt(role, {
+        project: input.project,
+        env: input.env,
+        goal: input.goal,
+        steps,
+        profile,
+    });
+}
+/**
+ * Tools visible to a role. The full profile filters by prefix; the small profile takes the
+ * role's named allowlist, in its declared order, so the model reads a short list of things it is
+ * expected to do rather than a catalogue.
+ */
+export function roleTools(role, registry, ctx, profile = 'full') {
+    const def = ROLES[role];
+    const all = toAgentSdkTools(registry, ctx);
+    if (profile === 'small') {
+        const byName = new Map(all.map((t) => [t.name, t]));
+        return def.smallTools.map((n) => byName.get(n)).filter((t) => !!t);
+    }
+    return all.filter((t) => def.toolPrefixes.some((p) => t.name.startsWith(p)));
+}
+//# sourceMappingURL=index.js.map

package/dist/roles/steps.d.ts

@@ -0,0 +1,28 @@
+import { type ToolContext, type ToolRegistry } from '@sdods/mcp';
+/**
+ * The project's real step vocabulary, for the system prompt.
+ *
+ * A model that has not been shown the steps invents them, and an invented step is a scenario that
+ * cannot run. Every role prompt says "reuse existing steps", and until now nothing put the steps
+ * in front of the model on the agents path — `renderPrompt` accepted them and no caller passed
+ * any. Small models need this most, but nothing about it is small-model specific.
+ *
+ * Producing the list runs `sdods steps list`, which compiles the project and takes seconds, so it
+ * is cached against the modification time of the project's `steps/` directory.
+ */
+export interface StepVocabulary {
+    /** Every pattern the project knows. */
+    all: string[];
+    /** The subset put in the prompt, ranked against the goal when there is one. */
+    selected: string[];
+    fromCache: boolean;
+}
+export declare function stepVocabulary(o: {
+    registry: ToolRegistry;
+    ctx: ToolContext;
+    project?: string;
+    /** Goal, plan or spec text: the patterns closest to it go first. */
+    focus?: string;
+    limit?: number;
+}): Promise<StepVocabulary>;
+//# sourceMappingURL=steps.d.ts.map

package/dist/roles/steps.js

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { similarity } from '@sdods/mcp';
+const CACHE_DIR = join('.sdods', 'cache');
+const TTL_MS = 10 * 60_000;
+export async function stepVocabulary(o) {
+    const empty = { all: [], selected: [], fromCache: false };
+    if (!o.project || !o.limit)
+        return empty;
+    const cached = readCache(o.ctx.rootDir, o.project);
+    const all = cached ?? (await listSteps(o.registry, o.ctx, o.project));
+    if (!all.length)
+        return empty;
+    if (!cached)
+        writeCache(o.ctx.rootDir, o.project, all);
+    const selected = o.focus
+        ? [...all]
+            .map((pattern) => ({ pattern, score: similarity(o.focus, pattern) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, o.limit)
+            .map((s) => s.pattern)
+        : all.slice(0, o.limit);
+    return { all, selected, fromCache: Boolean(cached) };
+}
+async function listSteps(registry, ctx, project) {
+    try {
+        const result = await registry.call('step_list', { project }, ctx);
+        // The registry wraps a tool's data as `structuredContent.items` for a list.
+        const structured = result
+            .structuredContent;
+        const data = structured?.items ?? structured?.data;
+        if (!Array.isArray(data))
+            return [];
+        return data
+            .map((s) => {
+            const step = s;
+            return `${step.keyword ?? ''} ${step.pattern ?? ''}`.trim();
+        })
+            .filter(Boolean);
+    }
+    catch {
+        // A project that will not compile still deserves a job; the model is simply less grounded.
+        return [];
+    }
+}
+function cacheFile(rootDir, project) {
+    return join(rootDir, CACHE_DIR, `steps-${project}.json`);
+}
+function readCache(rootDir, project) {
+    const file = cacheFile(rootDir, project);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        if (Date.now() - raw.at > TTL_MS)
+            return undefined;
+        const stepsDir = join(rootDir, 'projects', project, 'steps');
+        if (existsSync(stepsDir) && statSync(stepsDir).mtimeMs > raw.at)
+            return undefined;
+        return raw.steps;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(rootDir, project, steps) {
+    try {
+        mkdirSync(join(rootDir, CACHE_DIR), { recursive: true });
+        writeFileSync(cacheFile(rootDir, project), JSON.stringify({ at: Date.now(), steps }));
+    }
+    catch {
+        /* a cache that cannot be written is not an error */
+    }
+}
+//# sourceMappingURL=steps.js.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sdods/agents",
+  "version": "0.2.0",
+  "description": "SDODS AI agents: planner, generator, healer, upgrader and reviewer over a provider-agnostic adapter.",
+  "license": "Apache-2.0",
+  "author": "SDODS <admin@sdods.com>",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./adapters": "./dist/adapter/index.js",
+    "./roles": "./dist/roles/index.js",
+    "./jobs": "./dist/jobs/runner.js",
+    "./install-claude": "./dist/claude-code/install.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.259",
+    "@anthropic-ai/sdk": "^0.123.0",
+    "@sdods/contracts": "0.2.0",
+    "@sdods/mcp": "0.2.0",
+    "zod": "^4.5.4",
+    "@modelcontextprotocol/client": "^2.0.0"
+  },
+  "homepage": "https://sdods.com",
+  "bugs": {
+    "url": "https://github.com/siri1410/SDODS/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siri1410/SDODS.git",
+    "directory": "packages/agents"
+  },
+  "keywords": [
+    "sdods",
+    "automation",
+    "orchestration",
+    "testing",
+    "bdd",
+    "ai-agents",
+    "mcp"
+  ]
+}