@rlynjb/aptkit-core 0.1.0

package/node_modules/@aptkit/agent-anomaly-monitoring/fixtures/sp-revenue-monitoring.json

@@ -0,0 +1,136 @@
+{
+  "id": "sp-revenue-monitoring",
+  "description": "Detect a seeded SP revenue drop from a deterministic Olist-style monitoring fixture.",
+  "workspace": {
+    "projectId": "olist",
+    "projectName": "Olist Brazilian ecommerce fixture",
+    "events": [
+      { "name": "purchase", "properties": ["state", "category", "total_price"], "eventCount": 50000 },
+      { "name": "session_start", "properties": ["utm_source"], "eventCount": 80000 },
+      { "name": "checkout", "properties": ["state"], "eventCount": 35000 },
+      { "name": "view_item", "properties": ["category"], "eventCount": 120000 }
+    ],
+    "customerProperties": ["state", "city"],
+    "catalogs": [],
+    "totalCustomers": 125000,
+    "totalEvents": 285000,
+    "oldestTimestamp": 1764547200000,
+    "dataHorizon": { "from": "2025-12-01", "to": "2026-06-01", "durationDays": 182 }
+  },
+  "tools": [
+    {
+      "name": "get_metric_timeseries",
+      "description": "Return metric timeseries for an optional dimension.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "metric": { "type": "string" },
+          "dimension": { "type": "string" },
+          "time_range": { "type": "object" },
+          "granularity": { "type": "string" }
+        },
+        "required": ["metric", "time_range"]
+      },
+      "result": {
+        "periodComparison": {
+          "metric": "revenue",
+          "dimension": "state",
+          "segment": "SP",
+          "recentWindow": { "from": "2026-05-04", "to": "2026-06-01" },
+          "baselineWindow": { "from": "2026-02-09", "to": "2026-05-04" },
+          "recentValue": 28550000,
+          "baselineAverage": 40800000,
+          "pctChange": -0.300245,
+          "relatedSegments": [
+            { "name": "RJ", "pctChange": -0.02 },
+            { "name": "MG", "pctChange": 0.01 }
+          ]
+        },
+        "points": [
+          { "ts": "2026-05-04", "segment": "SP", "value": 7400000 },
+          { "ts": "2026-05-11", "segment": "SP", "value": 7200000 },
+          { "ts": "2026-05-18", "segment": "SP", "value": 7050000 },
+          { "ts": "2026-05-25", "segment": "SP", "value": 6900000 },
+          { "ts": "2026-05-04", "segment": "RJ", "value": 4300000 },
+          { "ts": "2026-05-11", "segment": "RJ", "value": 4350000 }
+        ],
+        "totalCount": 4200
+      }
+    },
+    {
+      "name": "get_anomaly_context",
+      "description": "Return context for a selected anomaly window and baseline.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "metric": { "type": "string" },
+          "dimension": { "type": "string" },
+          "segment": { "type": "string" },
+          "anomaly_window": { "type": "object" },
+          "baseline_window": { "type": "object" }
+        },
+        "required": ["metric", "dimension", "segment"]
+      },
+      "result": {
+        "anomaly_summary": {
+          "metric": "revenue",
+          "segment": "SP",
+          "anomaly_value": 28550000,
+          "baseline_avg": 40800000,
+          "pct_change": -0.300245
+        },
+        "related_segments": [
+          { "name": "RJ", "pct_change": -0.02 },
+          { "name": "MG", "pct_change": 0.01 }
+        ]
+      }
+    }
+  ],
+  "modelResponses": [
+    {
+      "content": [
+        {
+          "type": "tool_use",
+          "id": "tool-1",
+          "name": "get_metric_timeseries",
+          "input": {
+            "metric": "revenue",
+            "dimension": "state",
+            "time_range": { "from": "2026-05-04", "to": "2026-06-01" },
+            "granularity": "week"
+          }
+        }
+      ],
+      "usage": { "inputTokens": 900, "outputTokens": 80 },
+      "model": "fixture-model"
+    },
+    {
+      "content": [
+        {
+          "type": "tool_use",
+          "id": "tool-2",
+          "name": "get_anomaly_context",
+          "input": {
+            "metric": "revenue",
+            "dimension": "state",
+            "segment": "SP",
+            "anomaly_window": { "from": "2026-05-04", "to": "2026-06-01" },
+            "baseline_window": { "from": "2026-02-09", "to": "2026-05-04" }
+          }
+        }
+      ],
+      "usage": { "inputTokens": 760, "outputTokens": 75 },
+      "model": "fixture-model"
+    },
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "```json\n[{\"metric\":\"revenue\",\"category\":\"revenue_drop\",\"scope\":[\"state:SP\"],\"change\":{\"value\":30,\"direction\":\"down\",\"baseline\":\"recent 4w vs prior 12w\"},\"severity\":\"critical\",\"impact\":\"Sao Paulo revenue is down about 30% while nearby states are stable, putting the largest regional topline segment at risk if the trend continues.\",\"evidence\":[{\"tool\":\"get_anomaly_context\",\"result\":{\"segment\":\"SP\",\"pct_change\":-0.300245,\"anomaly_value\":28550000,\"baseline_avg\":40800000}}]}]\n```"
+        }
+      ],
+      "usage": { "inputTokens": 1020, "outputTokens": 210 },
+      "model": "fixture-model"
+    }
+  ]
+}

package/node_modules/@aptkit/agent-anomaly-monitoring/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@aptkit/agent-anomaly-monitoring",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "README.md",
+    "dist/src",
+    "fixtures"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "replay:fixture": "npm run build && node dist/scripts/replay-fixture.js",
+    "replay:promoted": "npm run build && node ../../../scripts/replay-promoted-fixtures.mjs --count anomalyCount --empty \"no promoted monitoring fixtures found\""
+  },
+  "dependencies": {
+    "@aptkit/context": "0.0.0",
+    "@aptkit/prompts": "0.0.0",
+    "@aptkit/runtime": "0.0.0",
+    "@aptkit/tools": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  }
+}

package/node_modules/@aptkit/agent-diagnostic-investigation/README.md

@@ -0,0 +1,11 @@
+# Diagnostic Investigation Agent
+
+Extracted from the Blooming Insights diagnostic agent as a reusable AptKit capability.
+
+This package investigates a single anomaly, tests competing hypotheses through a `ToolRegistry`, and returns a structured diagnosis with evidence and confidence.
+
+```ts
+import { DiagnosticInvestigationAgent } from '@aptkit/agent-diagnostic-investigation';
+```
+
+The first fixture covers a seeded Sao Paulo revenue drop over an Olist-style ecommerce workspace.

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/diagnostic-agent.d.ts

@@ -0,0 +1,27 @@
+import { type CapabilityTraceSink, type ModelProvider } from '@aptkit/runtime';
+import { type ToolRegistry } from '@aptkit/tools';
+import type { Anomaly, Diagnosis, WorkspaceDescriptor } from './types.js';
+export declare const DIAGNOSTIC_INVESTIGATION_CAPABILITY_ID = "diagnostic-investigation-agent";
+/** Least-privilege tool grant for evidence-gathering during diagnostic investigation. */
+export declare const diagnosticInvestigationToolPolicy: {
+    capabilityId: string;
+    allowedTools: readonly ["execute_analytics_eql", "get_event_segmentation", "list_email_campaigns", "list_experiments", "list_scenarios", "list_banners", "list_customers", "get_customer_prediction_score", "get_metric_timeseries", "get_segments", "get_anomaly_context"];
+};
+export type DiagnosticAgentOptions = {
+    model: ModelProvider;
+    tools: ToolRegistry;
+    workspace: WorkspaceDescriptor;
+    trace?: CapabilityTraceSink;
+    prompt?: string;
+};
+export type DiagnosticRunOptions = {
+    signal?: AbortSignal;
+};
+export declare class DiagnosticInvestigationAgent {
+    private readonly options;
+    private readonly prompt;
+    constructor(options: DiagnosticAgentOptions);
+    /** Investigates one anomaly and returns a validated diagnosis with evidence and confidence. */
+    investigate(anomaly: Anomaly, runOptions?: DiagnosticRunOptions): Promise<Diagnosis>;
+}
+export declare function diagnosisConfidence(diagnosis: Diagnosis): 'high' | 'medium' | 'low';

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/diagnostic-agent.js

@@ -0,0 +1,95 @@
+import { diagnosticPromptPackage, renderPromptTemplate } from '@aptkit/prompts';
+import { buildSynthesisInstruction, runAgentLoop } from '@aptkit/runtime';
+import { filterToolsForPolicy } from '@aptkit/tools';
+import { schemaSummary } from './schema-summary.js';
+import { tryParseDiagnosis } from './validate.js';
+export const DIAGNOSTIC_INVESTIGATION_CAPABILITY_ID = 'diagnostic-investigation-agent';
+/** Least-privilege tool grant for evidence-gathering during diagnostic investigation. */
+export const diagnosticInvestigationToolPolicy = {
+    capabilityId: DIAGNOSTIC_INVESTIGATION_CAPABILITY_ID,
+    allowedTools: [
+        'execute_analytics_eql',
+        'get_event_segmentation',
+        'list_email_campaigns',
+        'list_experiments',
+        'list_scenarios',
+        'list_banners',
+        'list_customers',
+        'get_customer_prediction_score',
+        'get_metric_timeseries',
+        'get_segments',
+        'get_anomaly_context',
+    ],
+};
+const FALLBACK_DIAGNOSIS = {
+    conclusion: 'Insufficient data to determine a cause for this change.',
+    evidence: [],
+    hypothesesConsidered: [],
+    confidence: 'low',
+};
+export class DiagnosticInvestigationAgent {
+    options;
+    prompt;
+    constructor(options) {
+        this.options = options;
+        this.prompt = options.prompt ?? diagnosticPromptPackage.system;
+    }
+    /** Investigates one anomaly and returns a validated diagnosis with evidence and confidence. */
+    async investigate(anomaly, runOptions = {}) {
+        const allTools = await this.options.tools.listTools();
+        const toolSchemas = filterToolsForPolicy(allTools, diagnosticInvestigationToolPolicy);
+        const system = renderPromptTemplate(this.prompt, {
+            schema: schemaSummary(this.options.workspace),
+            project_id: this.options.workspace.projectId,
+            anomaly: JSON.stringify(anomaly),
+        });
+        const { toolCalls, parsed } = await runAgentLoop({
+            capabilityId: DIAGNOSTIC_INVESTIGATION_CAPABILITY_ID,
+            model: this.options.model,
+            tools: this.options.tools,
+            system,
+            userPrompt: 'Investigate the anomaly and return the diagnosis JSON object.',
+            toolSchemas,
+            trace: this.options.trace,
+            signal: runOptions.signal,
+            maxTurns: 8,
+            maxToolCalls: 6,
+            synthesisInstruction: buildSynthesisInstruction('Stop investigating now and output your final answer. Respond with ONLY a single JSON object in a json fence matching the diagnosis shape: conclusion, evidence, hypothesesConsidered, and any supported optional fields. Base it only on the evidence already gathered.'),
+            parseResult: tryParseDiagnosis,
+            recoveryPrompt: (calls) => buildRecoveryPrompt(anomaly, calls),
+        });
+        const diagnosis = parsed ?? FALLBACK_DIAGNOSIS;
+        const confidence = diagnosisConfidence(diagnosis);
+        const hadErrors = toolCalls.some((call) => call.error);
+        return { ...diagnosis, confidence: confidence === 'high' && hadErrors ? 'medium' : confidence };
+    }
+}
+export function diagnosisConfidence(diagnosis) {
+    if (diagnosis.confidence)
+        return diagnosis.confidence;
+    const hypotheses = diagnosis.hypothesesConsidered ?? [];
+    if (hypotheses.length === 0)
+        return 'low';
+    const supported = hypotheses.filter((item) => item.supported).length;
+    const tested = hypotheses.filter((item) => item.reasoning.trim().length > 0).length;
+    if (supported >= 1 && tested === hypotheses.length)
+        return 'high';
+    if (supported >= 1)
+        return 'medium';
+    return 'low';
+}
+function buildRecoveryPrompt(anomaly, toolCalls) {
+    const evidence = toolCalls
+        .map((call, index) => {
+        const payload = call.error ? { error: call.error } : call.result;
+        return `Query ${index + 1}: ${call.toolName} ${JSON.stringify(call.args).slice(0, 200)}\nResult: ${JSON.stringify(payload).slice(0, 900)}`;
+    })
+        .join('\n\n') || '(no successful queries were completed)';
+    return [
+        `Anomaly investigated:\n${JSON.stringify(anomaly)}`,
+        `Queries run and their results:\n${evidence}`,
+        'Based ONLY on the evidence above, output your best-supported diagnosis as a single JSON object in a json fence.',
+        'Use this shape: {"conclusion": string, "evidence": string[], "hypothesesConsidered": [{"hypothesis": string, "supported": boolean, "reasoning": string}]}.',
+        'Give a concrete conclusion grounded in observed values. If the data was inconclusive, say what was inconclusive. Do NOT request more queries.',
+    ].join('\n\n');
+}

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/fixture-provider.d.ts

@@ -0,0 +1,10 @@
+import type { ModelProvider, ModelRequest, ModelResponse } from '@aptkit/runtime';
+export declare class FixtureModelProvider implements ModelProvider {
+    private readonly responses;
+    readonly id = "fixture";
+    readonly defaultModel = "fixture-model";
+    readonly requests: ModelRequest[];
+    private index;
+    constructor(responses: ModelResponse[]);
+    complete(request: ModelRequest): Promise<ModelResponse>;
+}

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/fixture-provider.js

@@ -0,0 +1,18 @@
+export class FixtureModelProvider {
+    responses;
+    id = 'fixture';
+    defaultModel = 'fixture-model';
+    requests = [];
+    index = 0;
+    constructor(responses) {
+        this.responses = responses;
+    }
+    async complete(request) {
+        this.requests.push(request);
+        const response = this.responses[this.index];
+        this.index += 1;
+        if (!response)
+            throw new Error(`fixture model exhausted after ${this.index - 1} responses`);
+        return response;
+    }
+}

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './diagnostic-agent.js';
+export * from './fixture-provider.js';
+export * from './schema-summary.js';
+export * from './types.js';
+export * from './validate.js';

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/index.js

@@ -0,0 +1,5 @@
+export * from './diagnostic-agent.js';
+export * from './fixture-provider.js';
+export * from './schema-summary.js';
+export * from './types.js';
+export * from './validate.js';

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/schema-summary.d.ts

@@ -0,0 +1 @@
+export { schemaSummary } from '@aptkit/context';

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/schema-summary.js

@@ -0,0 +1 @@
+export { schemaSummary } from '@aptkit/context';

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/types.d.ts

@@ -0,0 +1,37 @@
+export type { WorkspaceDescriptor } from '@aptkit/context';
+export type Severity = 'critical' | 'warning' | 'info' | 'positive';
+export type Anomaly = {
+    metric: string;
+    scope: string[];
+    change: {
+        value: number;
+        direction: 'up' | 'down';
+        baseline: string;
+    };
+    severity: Severity;
+    evidence: {
+        tool: string;
+        result: unknown;
+    }[];
+    impact?: string;
+    history?: number[];
+    category?: string;
+};
+export type Diagnosis = {
+    conclusion: string;
+    evidence: string[];
+    hypothesesConsidered: {
+        hypothesis: string;
+        supported: boolean;
+        reasoning: string;
+    }[];
+    affectedCustomers?: {
+        count: number;
+        segmentDescription: string;
+    };
+    confidence?: 'high' | 'medium' | 'low';
+    timeSeries?: {
+        day: string;
+        value: number;
+    }[];
+};

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/validate.d.ts

@@ -0,0 +1,10 @@
+import type { Diagnosis } from './types.js';
+export declare function isDiagnosis(value: unknown): value is Diagnosis;
+export declare function tryParseDiagnosis(text: string): Diagnosis | null;
+export declare function validateDiagnosis(diagnosis: unknown): {
+    ok: true;
+    error?: undefined;
+} | {
+    ok: false;
+    error: string;
+};

package/node_modules/@aptkit/agent-diagnostic-investigation/dist/src/validate.js

@@ -0,0 +1,49 @@
+import { parseAgentJson } from '@aptkit/runtime';
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function isHypothesis(value) {
+    return (isRecord(value) &&
+        typeof value.hypothesis === 'string' &&
+        typeof value.supported === 'boolean' &&
+        typeof value.reasoning === 'string');
+}
+function isAffectedCustomers(value) {
+    return isRecord(value) && typeof value.count === 'number' && typeof value.segmentDescription === 'string';
+}
+function isTimeSeriesPoint(value) {
+    return isRecord(value) && typeof value.day === 'string' && typeof value.value === 'number';
+}
+export function isDiagnosis(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.conclusion !== 'string')
+        return false;
+    if (!Array.isArray(value.evidence) || !value.evidence.every((item) => typeof item === 'string'))
+        return false;
+    if (!Array.isArray(value.hypothesesConsidered) || !value.hypothesesConsidered.every(isHypothesis)) {
+        return false;
+    }
+    if (value.affectedCustomers !== undefined && !isAffectedCustomers(value.affectedCustomers))
+        return false;
+    if (value.timeSeries !== undefined && (!Array.isArray(value.timeSeries) || !value.timeSeries.every(isTimeSeriesPoint))) {
+        return false;
+    }
+    if (value.confidence !== undefined && !['high', 'medium', 'low'].includes(String(value.confidence)))
+        return false;
+    return true;
+}
+export function tryParseDiagnosis(text) {
+    try {
+        const parsed = parseAgentJson(text);
+        return isDiagnosis(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function validateDiagnosis(diagnosis) {
+    if (isDiagnosis(diagnosis))
+        return { ok: true };
+    return { ok: false, error: 'diagnosis must match the expected structured output shape' };
+}