ax 0.2.2 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +32 -0
- package/LICENSE +21 -0
- package/README.md +403 -0
- package/dist/api/audit.d.ts +47 -0
- package/dist/api/deep-journey.d.ts +90 -0
- package/dist/api/platform.d.ts +139 -0
- package/dist/api/shared.d.ts +14 -0
- package/dist/api/skills.d.ts +25 -0
- package/dist/contract/index.d.ts +22 -0
- package/dist/contract/types.gen.d.ts +3270 -0
- package/dist/contract/version.d.ts +2 -0
- package/dist/index.cjs +600 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +563 -0
- package/dist/main.cjs +597 -0
- package/package.json +70 -23
- package/ReadMe.md +0 -15
- package/ax.coffee +0 -38
- package/ax.js +0 -65
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
export interface RunSummary {
|
|
2
|
+
run_id: string;
|
|
3
|
+
domain?: string;
|
|
4
|
+
intent?: string;
|
|
5
|
+
harness?: string;
|
|
6
|
+
model?: string;
|
|
7
|
+
effective_model?: string;
|
|
8
|
+
outcome: string;
|
|
9
|
+
num_turns?: number;
|
|
10
|
+
duration_ms?: number;
|
|
11
|
+
started_at?: string;
|
|
12
|
+
finished_at?: string;
|
|
13
|
+
last_seq?: number;
|
|
14
|
+
}
|
|
15
|
+
export interface InsightRecommendation {
|
|
16
|
+
title: string;
|
|
17
|
+
detail: string;
|
|
18
|
+
priority?: string;
|
|
19
|
+
}
|
|
20
|
+
export interface JourneyInsight {
|
|
21
|
+
summary?: string;
|
|
22
|
+
outcome?: string;
|
|
23
|
+
visibility_score?: number;
|
|
24
|
+
intent_satisfied?: boolean;
|
|
25
|
+
task_satisfied?: string;
|
|
26
|
+
key_observations?: string[];
|
|
27
|
+
friction_points?: string[];
|
|
28
|
+
recommendations?: InsightRecommendation[];
|
|
29
|
+
intent_category?: string;
|
|
30
|
+
journey_layers?: string[];
|
|
31
|
+
/** Usage of the analyzer that produced the insight — not the run itself. */
|
|
32
|
+
usage?: {
|
|
33
|
+
input_tokens?: number;
|
|
34
|
+
output_tokens?: number;
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* One entry of a `trajectory` snapshot. Richer than the raw `step` events: a
|
|
39
|
+
* tool call arrives merged with its result (status, duration, structured
|
|
40
|
+
* output) plus ora's attribution of where the agent got the target from.
|
|
41
|
+
*/
|
|
42
|
+
export interface JourneyStep {
|
|
43
|
+
id: number;
|
|
44
|
+
turn: number;
|
|
45
|
+
type: string;
|
|
46
|
+
kind?: string;
|
|
47
|
+
text?: string;
|
|
48
|
+
thinking?: string;
|
|
49
|
+
tool?: string;
|
|
50
|
+
action?: string;
|
|
51
|
+
input?: Record<string, unknown>;
|
|
52
|
+
input_display?: string;
|
|
53
|
+
summary?: string;
|
|
54
|
+
label?: string;
|
|
55
|
+
status?: number;
|
|
56
|
+
duration_ms?: number;
|
|
57
|
+
is_error?: boolean;
|
|
58
|
+
output_structured?: {
|
|
59
|
+
body?: string;
|
|
60
|
+
links?: Array<{
|
|
61
|
+
title?: string;
|
|
62
|
+
url?: string;
|
|
63
|
+
}>;
|
|
64
|
+
};
|
|
65
|
+
elapsed_ms?: number;
|
|
66
|
+
attribution?: {
|
|
67
|
+
kind?: string;
|
|
68
|
+
method?: string;
|
|
69
|
+
confidence?: string;
|
|
70
|
+
/** For link-follows: the exact step this URL was discovered on. */
|
|
71
|
+
referrer?: {
|
|
72
|
+
step_id?: number;
|
|
73
|
+
turn?: number;
|
|
74
|
+
artifact_kind?: string;
|
|
75
|
+
url_path?: string;
|
|
76
|
+
};
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
/** A raw `step` event payload (loosely typed; the CLI never renders from these). */
|
|
80
|
+
export interface RawRunStep {
|
|
81
|
+
type: string;
|
|
82
|
+
turn?: number;
|
|
83
|
+
tool?: string;
|
|
84
|
+
[extra: string]: unknown;
|
|
85
|
+
}
|
|
86
|
+
/** Run-level token/cost totals, read from the runs list after completion. */
|
|
87
|
+
export interface RunSpend {
|
|
88
|
+
totalTokens?: number;
|
|
89
|
+
inputTokens?: number;
|
|
90
|
+
outputTokens?: number;
|
|
91
|
+
cacheReadTokens?: number;
|
|
92
|
+
cacheCreationTokens?: number;
|
|
93
|
+
costUsd?: number;
|
|
94
|
+
}
|
|
95
|
+
export interface JourneyHooks {
|
|
96
|
+
/** Fired exactly once when the run exists (the stream's own `run` event is ignored). */
|
|
97
|
+
opened?: (runId: string) => void;
|
|
98
|
+
/**
|
|
99
|
+
* A full-trajectory snapshot arrived. These flow every few seconds while
|
|
100
|
+
* the agent works and are the ONLY live signal — drive all UI from here.
|
|
101
|
+
*/
|
|
102
|
+
snapshot?: (steps: JourneyStep[]) => void;
|
|
103
|
+
/**
|
|
104
|
+
* A raw `step` event arrived. ⚠ The server flushes these in one burst at
|
|
105
|
+
* the very end of the run; rendering from them means a blank screen until
|
|
106
|
+
* the agent finishes.
|
|
107
|
+
*/
|
|
108
|
+
step?: (step: RawRunStep, seq: number) => void;
|
|
109
|
+
finished?: (summary: RunSummary) => void;
|
|
110
|
+
scored?: (insight: JourneyInsight) => void;
|
|
111
|
+
}
|
|
112
|
+
export interface RunRequest {
|
|
113
|
+
intent: string;
|
|
114
|
+
domain?: string;
|
|
115
|
+
harness?: string;
|
|
116
|
+
model?: string;
|
|
117
|
+
/** "harness" = tool-using agent (default); "direct" = single LLM answer. */
|
|
118
|
+
executionKind?: "harness" | "direct";
|
|
119
|
+
baseUrl?: string;
|
|
120
|
+
apiKey?: string;
|
|
121
|
+
idleMs?: number;
|
|
122
|
+
}
|
|
123
|
+
export interface JourneyRun {
|
|
124
|
+
runId: string;
|
|
125
|
+
intent: string;
|
|
126
|
+
domain?: string;
|
|
127
|
+
harness?: string;
|
|
128
|
+
result?: RunSummary;
|
|
129
|
+
insight?: JourneyInsight;
|
|
130
|
+
usage?: RunSpend;
|
|
131
|
+
steps: RawRunStep[];
|
|
132
|
+
/** The last trajectory snapshot seen — the definitive step list. */
|
|
133
|
+
trajectory: JourneyStep[];
|
|
134
|
+
}
|
|
135
|
+
export declare function decodeEventBlock(block: string): {
|
|
136
|
+
event: string;
|
|
137
|
+
data: string;
|
|
138
|
+
} | null;
|
|
139
|
+
export declare function launchJourney(request: RunRequest, hooks?: JourneyHooks): Promise<JourneyRun>;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Idle watchdog for a long-lived stream: aborts the fetch when `poke()` hasn't
|
|
3
|
+
* been called for `ms`. Unlike a fixed deadline, a stream that keeps emitting
|
|
4
|
+
* can run indefinitely — which is what a slow-but-healthy scan or agent needs.
|
|
5
|
+
*/
|
|
6
|
+
export declare function watchdog(ms: number): {
|
|
7
|
+
signal: AbortSignal;
|
|
8
|
+
poke: () => void;
|
|
9
|
+
disarm: () => void;
|
|
10
|
+
tripped: () => boolean;
|
|
11
|
+
};
|
|
12
|
+
/** Best-effort human message from an error response body. */
|
|
13
|
+
export declare function errorBodyText(res: Response): Promise<string>;
|
|
14
|
+
export declare const pause: (ms: number) => Promise<void>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export declare class SkillApiError extends Error {
|
|
2
|
+
}
|
|
3
|
+
export interface SkillEntry {
|
|
4
|
+
name: string;
|
|
5
|
+
type?: string;
|
|
6
|
+
description?: string;
|
|
7
|
+
/** Path or absolute URL to the SKILL.md. */
|
|
8
|
+
url: string;
|
|
9
|
+
/** `sha256:<hex>` over the exact SKILL.md bytes. */
|
|
10
|
+
digest?: string;
|
|
11
|
+
}
|
|
12
|
+
export declare function resolveBase(baseUrl?: string): string;
|
|
13
|
+
export declare function fetchSkillIndex(baseUrl?: string): Promise<SkillEntry[]>;
|
|
14
|
+
export declare function digestOf(bytes: Uint8Array): string;
|
|
15
|
+
export interface FetchedSkill {
|
|
16
|
+
entry: SkillEntry;
|
|
17
|
+
/** The exact SKILL.md bytes, digest-verified against the index. */
|
|
18
|
+
bytes: Uint8Array;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Fetch one skill's SKILL.md and verify it against the index digest. A
|
|
22
|
+
* mismatch is refused outright - never serve bytes the index does not vouch
|
|
23
|
+
* for.
|
|
24
|
+
*/
|
|
25
|
+
export declare function fetchSkill(name: string, baseUrl?: string): Promise<FetchedSkill>;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { components } from "./types.gen";
|
|
2
|
+
import { BUILT_AGAINST } from "./version";
|
|
3
|
+
export type AuditScanResult = components["schemas"]["AuditScanResult"];
|
|
4
|
+
export type AuditScoreResult = components["schemas"]["AuditScoreResult"];
|
|
5
|
+
export type AuditCheck = components["schemas"]["AuditCheck"];
|
|
6
|
+
export type AuditLayer = components["schemas"]["AuditLayer"];
|
|
7
|
+
export type AuditTopFix = AuditScanResult["topFixes"][number];
|
|
8
|
+
export type JourneyRun = components["schemas"]["JourneyRun"];
|
|
9
|
+
export type JourneyCappedRun = components["schemas"]["JourneyCappedRun"];
|
|
10
|
+
export type JourneyRunDetail = components["schemas"]["JourneyRunDetail"];
|
|
11
|
+
export type JourneyRunResult = components["schemas"]["JourneyRunResult"];
|
|
12
|
+
export type JourneyTrajectoryStep = components["schemas"]["JourneyTrajectoryStep"];
|
|
13
|
+
export { BUILT_AGAINST };
|
|
14
|
+
/**
|
|
15
|
+
* True when the server reports a newer contract (major or minor) than the one
|
|
16
|
+
* this build was generated against. Patch drift is spec-prose only - silent.
|
|
17
|
+
*/
|
|
18
|
+
export declare function isNewerContract(payloadVersion: string | undefined): boolean;
|
|
19
|
+
/** One stderr line per process when the server's contract is newer than ours. */
|
|
20
|
+
export declare function warnOnNewerContract(payloadVersion: string | undefined): void;
|
|
21
|
+
/** Test hook: reset the once-per-process warning latch. */
|
|
22
|
+
export declare function resetContractWarning(): void;
|