@vornicx/origin 0.1.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/LICENSE +21 -0
- package/README.md +238 -0
- package/dist/apollo/index.d.ts +87 -0
- package/dist/apollo/index.js +140 -0
- package/dist/apollo/index.js.map +1 -0
- package/dist/chunk-77G3SI57.js +1119 -0
- package/dist/chunk-77G3SI57.js.map +1 -0
- package/dist/index.d.ts +158 -0
- package/dist/index.js +137 -0
- package/dist/index.js.map +1 -0
- package/dist/policy-KjPvxtus.d.ts +605 -0
- package/package.json +96 -0
|
@@ -0,0 +1,605 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/** Context types — the structured understanding of "the work around you". */
|
|
4
|
+
interface FileRef {
|
|
5
|
+
/** Path relative to the scan root, POSIX-style. */
|
|
6
|
+
path: string;
|
|
7
|
+
/** Size in bytes. */
|
|
8
|
+
size: number;
|
|
9
|
+
/** Lowercased extension without the leading dot ("" if none). */
|
|
10
|
+
ext: string;
|
|
11
|
+
/** Human language/format name mapped from the extension, if known. */
|
|
12
|
+
language?: string;
|
|
13
|
+
}
|
|
14
|
+
interface ToolRef {
|
|
15
|
+
name: string;
|
|
16
|
+
description?: string;
|
|
17
|
+
}
|
|
18
|
+
interface Intent {
|
|
19
|
+
goal: string;
|
|
20
|
+
/** Action verbs detected in the goal (e.g. "deploy", "refactor"). */
|
|
21
|
+
verbs: string[];
|
|
22
|
+
/** Salient keywords from the goal. */
|
|
23
|
+
keywords: string[];
|
|
24
|
+
}
|
|
25
|
+
interface ContextBundle {
|
|
26
|
+
root: string;
|
|
27
|
+
files: FileRef[];
|
|
28
|
+
/** Language name → file count. */
|
|
29
|
+
languages: Record<string, number>;
|
|
30
|
+
tools: ToolRef[];
|
|
31
|
+
intent?: Intent;
|
|
32
|
+
/** True if the file scan hit the `maxFiles` cap. */
|
|
33
|
+
truncated: boolean;
|
|
34
|
+
scannedAt: string;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
interface ScanOptions {
|
|
38
|
+
/** Directory to scan. Defaults to `process.cwd()`. */
|
|
39
|
+
root?: string;
|
|
40
|
+
/** Cap on files collected. Defaults to 2000. */
|
|
41
|
+
maxFiles?: number;
|
|
42
|
+
/** Tools available to the agent, surfaced in the bundle. */
|
|
43
|
+
tools?: ToolRef[];
|
|
44
|
+
/** A goal to parse into an `Intent`. */
|
|
45
|
+
goal?: string;
|
|
46
|
+
/** Ignore-file names to honor. Defaults to `.gitignore` + `.originignore`. */
|
|
47
|
+
ignoreFiles?: string[];
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Understands the work around you: scans a workspace into a structured
|
|
51
|
+
* `ContextBundle` of files, languages, available tools, and parsed intent —
|
|
52
|
+
* honoring `.gitignore` / `.originignore`.
|
|
53
|
+
*/
|
|
54
|
+
declare class ContextEngine {
|
|
55
|
+
scan(options?: ScanOptions): Promise<ContextBundle>;
|
|
56
|
+
}
|
|
57
|
+
/** Parse a goal into an `Intent`: detected action verbs and salient keywords. */
|
|
58
|
+
declare function parseIntent(goal: string): Intent;
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Atlas memory types.
|
|
62
|
+
*
|
|
63
|
+
* The record shape mirrors Apollo's memory model (`kind`, `importance` 1–5,
|
|
64
|
+
* `content`, `metadata`) so the same memory can back both Origin and Apollo.
|
|
65
|
+
*/
|
|
66
|
+
type MemoryKind = "note" | "chat" | "mission" | "fact" | "preference";
|
|
67
|
+
interface MemoryRecord {
|
|
68
|
+
id: string;
|
|
69
|
+
content: string;
|
|
70
|
+
kind: MemoryKind;
|
|
71
|
+
/** 1 (incidental) … 5 (critical). */
|
|
72
|
+
importance: number;
|
|
73
|
+
source?: string;
|
|
74
|
+
metadata: Record<string, unknown>;
|
|
75
|
+
/** ISO-8601 timestamp. */
|
|
76
|
+
createdAt: string;
|
|
77
|
+
/** ISO-8601 timestamp. */
|
|
78
|
+
updatedAt: string;
|
|
79
|
+
}
|
|
80
|
+
interface RememberInput {
|
|
81
|
+
content: string;
|
|
82
|
+
kind?: MemoryKind;
|
|
83
|
+
importance?: number;
|
|
84
|
+
source?: string;
|
|
85
|
+
metadata?: Record<string, unknown>;
|
|
86
|
+
}
|
|
87
|
+
interface RecallOptions {
|
|
88
|
+
limit?: number;
|
|
89
|
+
kind?: MemoryKind;
|
|
90
|
+
minImportance?: number;
|
|
91
|
+
}
|
|
92
|
+
interface RecallHit extends MemoryRecord {
|
|
93
|
+
/** Blended ranking score (relevance × importance × recency). */
|
|
94
|
+
score: number;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Persistence backend for Atlas memory. Implementations need only provide CRUD;
|
|
99
|
+
* ranking is done in `Memory`. A store MAY implement `recall` to push search down
|
|
100
|
+
* to the backend (e.g. SQL full-text), in which case `Memory` delegates to it.
|
|
101
|
+
*/
|
|
102
|
+
interface MemoryStore {
|
|
103
|
+
all(): Promise<MemoryRecord[]>;
|
|
104
|
+
get(id: string): Promise<MemoryRecord | null>;
|
|
105
|
+
put(record: MemoryRecord): Promise<void>;
|
|
106
|
+
delete(id: string): Promise<boolean>;
|
|
107
|
+
clear(): Promise<void>;
|
|
108
|
+
recall?(query: string, options: RecallOptions): Promise<RecallHit[]>;
|
|
109
|
+
}
|
|
110
|
+
/** Ephemeral, in-process store. The default when no persistence is configured. */
|
|
111
|
+
declare class InMemoryStore implements MemoryStore {
|
|
112
|
+
private readonly records;
|
|
113
|
+
all(): Promise<MemoryRecord[]>;
|
|
114
|
+
get(id: string): Promise<MemoryRecord | null>;
|
|
115
|
+
put(record: MemoryRecord): Promise<void>;
|
|
116
|
+
delete(id: string): Promise<boolean>;
|
|
117
|
+
clear(): Promise<void>;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
interface MemoryOptions {
|
|
121
|
+
store?: MemoryStore;
|
|
122
|
+
/** Injectable clock (tests). Defaults to `() => new Date()`. */
|
|
123
|
+
now?: () => Date;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Atlas — Origin's persistent memory. Remembers notes, facts, preferences,
|
|
127
|
+
* decisions and chat across sessions, and recalls them ranked by
|
|
128
|
+
* relevance × importance × recency.
|
|
129
|
+
*/
|
|
130
|
+
declare class Memory {
|
|
131
|
+
private readonly store;
|
|
132
|
+
private readonly now;
|
|
133
|
+
constructor(options?: MemoryOptions);
|
|
134
|
+
remember(input: RememberInput): Promise<MemoryRecord>;
|
|
135
|
+
recall(query: string, options?: RecallOptions): Promise<RecallHit[]>;
|
|
136
|
+
list(options?: {
|
|
137
|
+
kind?: MemoryKind;
|
|
138
|
+
limit?: number;
|
|
139
|
+
}): Promise<MemoryRecord[]>;
|
|
140
|
+
update(id: string, patch: {
|
|
141
|
+
content?: string;
|
|
142
|
+
importance?: number;
|
|
143
|
+
metadata?: Record<string, unknown>;
|
|
144
|
+
}): Promise<MemoryRecord | null>;
|
|
145
|
+
forget(id: string): Promise<boolean>;
|
|
146
|
+
forgetAll(): Promise<void>;
|
|
147
|
+
/** All records, oldest first — for backup/inspection. */
|
|
148
|
+
export(): Promise<MemoryRecord[]>;
|
|
149
|
+
/** Recalled memories rendered as a system-prompt block (Apollo-compatible). */
|
|
150
|
+
formatBlock(query: string, options?: RecallOptions): Promise<string>;
|
|
151
|
+
}
|
|
152
|
+
/** Lowercase word tokens of length > 2, Unicode-aware. */
|
|
153
|
+
declare function tokenize(text: string): string[];
|
|
154
|
+
/** Render memories as a compact, prompt-ready block. */
|
|
155
|
+
declare function formatMemoriesBlock(memories: MemoryRecord[]): string;
|
|
156
|
+
|
|
157
|
+
/** Observability types — a legible, replayable record of what an agent did. */
|
|
158
|
+
type TraceEventKind = "mission_start" | "decision" | "plan" | "tool_call" | "approval" | "apply" | "verify" | "memory" | "error" | "mission_end";
|
|
159
|
+
interface TraceEvent {
|
|
160
|
+
traceId: string;
|
|
161
|
+
/** Monotonic sequence within the trace. */
|
|
162
|
+
seq: number;
|
|
163
|
+
/** ISO-8601 timestamp. */
|
|
164
|
+
at: string;
|
|
165
|
+
kind: TraceEventKind;
|
|
166
|
+
label: string;
|
|
167
|
+
/** Structured detail, after redaction. */
|
|
168
|
+
data?: Record<string, unknown>;
|
|
169
|
+
/** Wall-clock duration, for span events. */
|
|
170
|
+
durationMs?: number;
|
|
171
|
+
}
|
|
172
|
+
interface Trace {
|
|
173
|
+
id: string;
|
|
174
|
+
startedAt?: string;
|
|
175
|
+
endedAt?: string;
|
|
176
|
+
events: TraceEvent[];
|
|
177
|
+
}
|
|
178
|
+
/** Scrubs secrets from event detail before it is recorded. */
|
|
179
|
+
type Redactor = (data: Record<string, unknown>) => Record<string, unknown>;
|
|
180
|
+
/** Persistence backend for traces. */
|
|
181
|
+
interface TraceSink {
|
|
182
|
+
append(event: TraceEvent): Promise<void>;
|
|
183
|
+
load(traceId: string): Promise<TraceEvent[]>;
|
|
184
|
+
list(): Promise<string[]>;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** Default redactor: masks secret-looking keys and known token formats. */
|
|
188
|
+
declare const defaultRedactor: Redactor;
|
|
189
|
+
/** Ephemeral, in-process trace sink. */
|
|
190
|
+
declare class MemorySink implements TraceSink {
|
|
191
|
+
private readonly traces;
|
|
192
|
+
append(event: TraceEvent): Promise<void>;
|
|
193
|
+
load(traceId: string): Promise<TraceEvent[]>;
|
|
194
|
+
list(): Promise<string[]>;
|
|
195
|
+
}
|
|
196
|
+
/** Append-only JSONL trace sink, one file per trace under `dir`. */
|
|
197
|
+
declare class JsonlSink implements TraceSink {
|
|
198
|
+
private readonly dir;
|
|
199
|
+
constructor(dir: string);
|
|
200
|
+
private file;
|
|
201
|
+
append(event: TraceEvent): Promise<void>;
|
|
202
|
+
load(traceId: string): Promise<TraceEvent[]>;
|
|
203
|
+
list(): Promise<string[]>;
|
|
204
|
+
}
|
|
205
|
+
interface TracerOptions {
|
|
206
|
+
traceId: string;
|
|
207
|
+
sink: TraceSink;
|
|
208
|
+
redactor: Redactor;
|
|
209
|
+
now: () => Date;
|
|
210
|
+
}
|
|
211
|
+
/** Records the events of a single trace (one agent run / mission). */
|
|
212
|
+
declare class Tracer {
|
|
213
|
+
readonly traceId: string;
|
|
214
|
+
private readonly sink;
|
|
215
|
+
private readonly redactor;
|
|
216
|
+
private readonly now;
|
|
217
|
+
private seq;
|
|
218
|
+
private readonly events;
|
|
219
|
+
constructor(options: TracerOptions);
|
|
220
|
+
event(kind: TraceEventKind, label: string, data?: Record<string, unknown>, durationMs?: number): Promise<TraceEvent>;
|
|
221
|
+
start(label?: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
222
|
+
end(label?: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
223
|
+
decision(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
224
|
+
plan(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
225
|
+
toolCall(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
226
|
+
approval(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
227
|
+
apply(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
228
|
+
verify(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
229
|
+
memory(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
230
|
+
error(label: string, data?: Record<string, unknown>): Promise<TraceEvent>;
|
|
231
|
+
/** Start a timed span; call `.end()` to record it with a `durationMs`. */
|
|
232
|
+
span(kind: TraceEventKind, label: string, data?: Record<string, unknown>): {
|
|
233
|
+
end: (extra?: Record<string, unknown>) => Promise<TraceEvent>;
|
|
234
|
+
};
|
|
235
|
+
/** In-memory view of this trace so far. */
|
|
236
|
+
snapshot(): Trace;
|
|
237
|
+
}
|
|
238
|
+
interface ObservabilityOptions {
|
|
239
|
+
sink?: TraceSink;
|
|
240
|
+
/** Persist traces as JSONL under this directory (e.g. `<root>/.origin/traces`). */
|
|
241
|
+
dir?: string;
|
|
242
|
+
redactor?: Redactor;
|
|
243
|
+
now?: () => Date;
|
|
244
|
+
}
|
|
245
|
+
/** Top-level entry point: starts traces and replays them. */
|
|
246
|
+
declare class Observability {
|
|
247
|
+
private readonly sink;
|
|
248
|
+
private readonly redactor;
|
|
249
|
+
private readonly now;
|
|
250
|
+
constructor(options?: ObservabilityOptions);
|
|
251
|
+
startTrace(): Tracer;
|
|
252
|
+
replay(traceId: string): Promise<Trace>;
|
|
253
|
+
list(): Promise<string[]>;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/** Policy types — the human-agency control surface. */
|
|
257
|
+
/** Maps to Apollo's execution modes (`hermes_compat` = Apollo's streamlined gating). */
|
|
258
|
+
type ApolloMode = "plan" | "review" | "auto" | "full-auto" | "hermes_compat";
|
|
259
|
+
type ActionKind = "read" | "write" | "network" | "exec" | "tool" | "memory" | "plan";
|
|
260
|
+
type Gate = "allow" | "deny" | "ask";
|
|
261
|
+
interface ProposedAction {
|
|
262
|
+
kind: ActionKind;
|
|
263
|
+
summary: string;
|
|
264
|
+
tool?: string;
|
|
265
|
+
/** Whether the action mutates state / applies a change. */
|
|
266
|
+
mutating?: boolean;
|
|
267
|
+
/** Path or resource targeted (used for outside-root checks). */
|
|
268
|
+
target?: string;
|
|
269
|
+
metadata?: Record<string, unknown>;
|
|
270
|
+
}
|
|
271
|
+
interface PolicyContext {
|
|
272
|
+
/** Workspace root, for confining actions. */
|
|
273
|
+
root?: string;
|
|
274
|
+
}
|
|
275
|
+
interface PolicyBudget {
|
|
276
|
+
maxSteps: number;
|
|
277
|
+
maxToolCalls: number;
|
|
278
|
+
maxUsd?: number;
|
|
279
|
+
}
|
|
280
|
+
interface Policy {
|
|
281
|
+
readonly name: string;
|
|
282
|
+
readonly mode: ApolloMode;
|
|
283
|
+
readonly budget: PolicyBudget;
|
|
284
|
+
gate(action: ProposedAction, ctx?: PolicyContext): Gate;
|
|
285
|
+
}
|
|
286
|
+
interface ApprovalRequest {
|
|
287
|
+
action: ProposedAction;
|
|
288
|
+
policy: string;
|
|
289
|
+
reason: string;
|
|
290
|
+
}
|
|
291
|
+
interface ApprovalDecision {
|
|
292
|
+
approved: boolean;
|
|
293
|
+
note?: string;
|
|
294
|
+
}
|
|
295
|
+
type ApprovalHandler = (req: ApprovalRequest) => Promise<ApprovalDecision> | ApprovalDecision;
|
|
296
|
+
interface AuthorizeResult {
|
|
297
|
+
allowed: boolean;
|
|
298
|
+
gate: Gate;
|
|
299
|
+
via: "policy" | "approver";
|
|
300
|
+
note?: string;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/**
|
|
304
|
+
* BYOK provider layer.
|
|
305
|
+
*
|
|
306
|
+
* A dependency-free `fetch` wrapper over the major LLM providers. It shares Apollo's
|
|
307
|
+
* provider set and `ChatMessage` shape, so keys and prompts are drop-in compatible
|
|
308
|
+
* across Origin and Apollo. Keys are read from the environment — Origin never ships
|
|
309
|
+
* or stores them.
|
|
310
|
+
*/
|
|
311
|
+
type ChatRole = "system" | "user" | "assistant";
|
|
312
|
+
interface ChatMessage {
|
|
313
|
+
role: ChatRole;
|
|
314
|
+
content: string;
|
|
315
|
+
}
|
|
316
|
+
declare const SUPPORTED_PROVIDERS: readonly ["anthropic", "openai", "google", "groq", "mistral", "openrouter"];
|
|
317
|
+
type SupportedProvider = (typeof SUPPORTED_PROVIDERS)[number];
|
|
318
|
+
/** Environment variables consulted for each provider, in priority order. */
|
|
319
|
+
declare const PROVIDER_KEY_ENV: Record<SupportedProvider, readonly string[]>;
|
|
320
|
+
type Env = Record<string, string | undefined>;
|
|
321
|
+
declare function isSupportedProvider(value: string): value is SupportedProvider;
|
|
322
|
+
/** Resolve an API key for a provider from the environment, or `null` if unset. */
|
|
323
|
+
declare function resolveProviderKey(provider: SupportedProvider, env?: Env): string | null;
|
|
324
|
+
/** List providers that have a usable key in the given environment. */
|
|
325
|
+
declare function availableProviders(env?: Env): SupportedProvider[];
|
|
326
|
+
interface ProviderCall {
|
|
327
|
+
provider: SupportedProvider;
|
|
328
|
+
model: string;
|
|
329
|
+
apiKey: string;
|
|
330
|
+
messages: ChatMessage[];
|
|
331
|
+
signal?: AbortSignal;
|
|
332
|
+
/** Inject a `fetch` implementation (tests, proxies). Defaults to the global `fetch`. */
|
|
333
|
+
fetchImpl?: typeof fetch;
|
|
334
|
+
}
|
|
335
|
+
/** Call a provider and return the assistant's text. Throws on a non-OK response. */
|
|
336
|
+
declare function callProviderText(call: ProviderCall): Promise<string>;
|
|
337
|
+
/** Call a provider and return the raw streaming `Response` (SSE). */
|
|
338
|
+
declare function callProviderStream(call: ProviderCall): Promise<Response>;
|
|
339
|
+
/** Build a per-line SSE delta extractor for a provider's streaming format. */
|
|
340
|
+
declare function makeSSEParser(provider: SupportedProvider): (line: string) => string;
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* A success contract — the objective, runnable definition of "done". Mirrors
|
|
344
|
+
* Apollo's contract (commands / http / regex / criteria) so a goal verified by
|
|
345
|
+
* Origin is verified the same way by Apollo.
|
|
346
|
+
*/
|
|
347
|
+
declare const contractSchema: z.ZodObject<{
|
|
348
|
+
commands: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
349
|
+
cmd: z.ZodString;
|
|
350
|
+
expectExit: z.ZodDefault<z.ZodNumber>;
|
|
351
|
+
}, "strip", z.ZodTypeAny, {
|
|
352
|
+
cmd: string;
|
|
353
|
+
expectExit: number;
|
|
354
|
+
}, {
|
|
355
|
+
cmd: string;
|
|
356
|
+
expectExit?: number | undefined;
|
|
357
|
+
}>, "many">>;
|
|
358
|
+
http: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
359
|
+
url: z.ZodString;
|
|
360
|
+
expectStatus: z.ZodDefault<z.ZodNumber>;
|
|
361
|
+
}, "strip", z.ZodTypeAny, {
|
|
362
|
+
url: string;
|
|
363
|
+
expectStatus: number;
|
|
364
|
+
}, {
|
|
365
|
+
url: string;
|
|
366
|
+
expectStatus?: number | undefined;
|
|
367
|
+
}>, "many">>;
|
|
368
|
+
regex: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
369
|
+
cmd: z.ZodString;
|
|
370
|
+
pattern: z.ZodString;
|
|
371
|
+
}, "strip", z.ZodTypeAny, {
|
|
372
|
+
cmd: string;
|
|
373
|
+
pattern: string;
|
|
374
|
+
}, {
|
|
375
|
+
cmd: string;
|
|
376
|
+
pattern: string;
|
|
377
|
+
}>, "many">>;
|
|
378
|
+
criteria: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
|
|
379
|
+
}, "strip", z.ZodTypeAny, {
|
|
380
|
+
regex: {
|
|
381
|
+
cmd: string;
|
|
382
|
+
pattern: string;
|
|
383
|
+
}[];
|
|
384
|
+
commands: {
|
|
385
|
+
cmd: string;
|
|
386
|
+
expectExit: number;
|
|
387
|
+
}[];
|
|
388
|
+
http: {
|
|
389
|
+
url: string;
|
|
390
|
+
expectStatus: number;
|
|
391
|
+
}[];
|
|
392
|
+
criteria: string[];
|
|
393
|
+
}, {
|
|
394
|
+
regex?: {
|
|
395
|
+
cmd: string;
|
|
396
|
+
pattern: string;
|
|
397
|
+
}[] | undefined;
|
|
398
|
+
commands?: {
|
|
399
|
+
cmd: string;
|
|
400
|
+
expectExit?: number | undefined;
|
|
401
|
+
}[] | undefined;
|
|
402
|
+
http?: {
|
|
403
|
+
url: string;
|
|
404
|
+
expectStatus?: number | undefined;
|
|
405
|
+
}[] | undefined;
|
|
406
|
+
criteria?: string[] | undefined;
|
|
407
|
+
}>;
|
|
408
|
+
type Contract = z.infer<typeof contractSchema>;
|
|
409
|
+
interface CheckResult {
|
|
410
|
+
type: "command" | "http" | "regex";
|
|
411
|
+
target: string;
|
|
412
|
+
pass: boolean;
|
|
413
|
+
detail?: string;
|
|
414
|
+
}
|
|
415
|
+
interface Certificate {
|
|
416
|
+
ok: boolean;
|
|
417
|
+
checks: CheckResult[];
|
|
418
|
+
/** Human-judged criteria, carried through but not auto-evaluated. */
|
|
419
|
+
criteria: string[];
|
|
420
|
+
issuedAt: string;
|
|
421
|
+
/** sha256 over checks + criteria + ok — a tamper-evident fingerprint. */
|
|
422
|
+
hash: string;
|
|
423
|
+
}
|
|
424
|
+
interface ExecResult {
|
|
425
|
+
code: number;
|
|
426
|
+
stdout: string;
|
|
427
|
+
stderr: string;
|
|
428
|
+
}
|
|
429
|
+
type ExecFn = (cmd: string, opts: {
|
|
430
|
+
cwd?: string;
|
|
431
|
+
timeoutMs?: number;
|
|
432
|
+
}) => Promise<ExecResult>;
|
|
433
|
+
interface EvaluateOptions {
|
|
434
|
+
cwd?: string;
|
|
435
|
+
timeoutMs?: number;
|
|
436
|
+
fetchImpl?: typeof fetch;
|
|
437
|
+
execImpl?: ExecFn;
|
|
438
|
+
now?: () => Date;
|
|
439
|
+
}
|
|
440
|
+
/** Run a contract's checks and issue a certificate. */
|
|
441
|
+
declare function evaluateContract(input: unknown, options?: EvaluateOptions): Promise<Certificate>;
|
|
442
|
+
/** Extract a fenced ```contract { … }``` block from an LLM plan, if present. */
|
|
443
|
+
declare function parseContractFromPlan(plan: string): Contract | null;
|
|
444
|
+
|
|
445
|
+
interface ToolContext {
|
|
446
|
+
goal: string;
|
|
447
|
+
signal?: AbortSignal;
|
|
448
|
+
}
|
|
449
|
+
/** A capability the agent can invoke. Inputs are validated by the tool itself. */
|
|
450
|
+
interface Tool {
|
|
451
|
+
name: string;
|
|
452
|
+
description?: string;
|
|
453
|
+
/** Whether invoking the tool mutates state (informs policy gating). */
|
|
454
|
+
mutating?: boolean;
|
|
455
|
+
/** Action kind for policy (defaults to "tool"). */
|
|
456
|
+
kind?: ActionKind;
|
|
457
|
+
run(input: unknown, ctx: ToolContext): Promise<unknown> | unknown;
|
|
458
|
+
}
|
|
459
|
+
/** Identity helper for authoring tools with inference and a single import. */
|
|
460
|
+
declare function defineTool(spec: Tool): Tool;
|
|
461
|
+
interface PlanStep {
|
|
462
|
+
id: string;
|
|
463
|
+
description: string;
|
|
464
|
+
tool?: string;
|
|
465
|
+
input?: unknown;
|
|
466
|
+
kind: ActionKind;
|
|
467
|
+
mutating: boolean;
|
|
468
|
+
}
|
|
469
|
+
interface Plan {
|
|
470
|
+
steps: PlanStep[];
|
|
471
|
+
rationale?: string;
|
|
472
|
+
/** Optional success contract to verify when the plan completes. */
|
|
473
|
+
contract?: unknown;
|
|
474
|
+
}
|
|
475
|
+
interface Observation {
|
|
476
|
+
stepId: string;
|
|
477
|
+
ok: boolean;
|
|
478
|
+
output?: unknown;
|
|
479
|
+
error?: string;
|
|
480
|
+
skipped?: boolean;
|
|
481
|
+
}
|
|
482
|
+
interface RuntimeContext {
|
|
483
|
+
goal: string;
|
|
484
|
+
context: ContextBundle;
|
|
485
|
+
/** Recalled memory, formatted as a prompt block. */
|
|
486
|
+
memoryBlock: string;
|
|
487
|
+
tools: Tool[];
|
|
488
|
+
signal?: AbortSignal;
|
|
489
|
+
}
|
|
490
|
+
/**
|
|
491
|
+
* The reasoning/action engine an agent drives. Origin ships a reference runtime;
|
|
492
|
+
* `@vornicx/origin/apollo` provides one backed by the Apollo CLI.
|
|
493
|
+
*/
|
|
494
|
+
interface Runtime {
|
|
495
|
+
readonly name: string;
|
|
496
|
+
plan(ctx: RuntimeContext): Promise<Plan>;
|
|
497
|
+
synthesize(ctx: RuntimeContext, observations: Observation[]): Promise<string>;
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
type Completion = (messages: ChatMessage[]) => Promise<string>;
|
|
501
|
+
interface ReferenceRuntimeOptions {
|
|
502
|
+
/** Provide an LLM completion directly (tests, custom routing). */
|
|
503
|
+
complete?: Completion;
|
|
504
|
+
provider?: SupportedProvider;
|
|
505
|
+
model?: string;
|
|
506
|
+
env?: Record<string, string | undefined>;
|
|
507
|
+
fetchImpl?: typeof fetch;
|
|
508
|
+
}
|
|
509
|
+
/**
|
|
510
|
+
* A minimal but real reasoning runtime: it plans a goal into steps via an LLM,
|
|
511
|
+
* then synthesizes a final answer from the executed steps. With no provider key
|
|
512
|
+
* it degrades to a legible dry run (empty plan + explanatory answer).
|
|
513
|
+
*/
|
|
514
|
+
declare class ReferenceRuntime implements Runtime {
|
|
515
|
+
readonly name = "reference";
|
|
516
|
+
private readonly complete?;
|
|
517
|
+
constructor(options?: ReferenceRuntimeOptions);
|
|
518
|
+
plan(ctx: RuntimeContext): Promise<Plan>;
|
|
519
|
+
synthesize(ctx: RuntimeContext, observations: Observation[]): Promise<string>;
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
interface MissionResult {
|
|
523
|
+
goal: string;
|
|
524
|
+
answer: string;
|
|
525
|
+
steps: PlanStep[];
|
|
526
|
+
observations: Observation[];
|
|
527
|
+
certificate?: Certificate;
|
|
528
|
+
traceId: string;
|
|
529
|
+
policy: string;
|
|
530
|
+
}
|
|
531
|
+
/**
|
|
532
|
+
* Options for {@link ApolloAgent}. Only what you care about — everything else
|
|
533
|
+
* has a sensible default (in-memory Atlas, fresh context, in-memory traces,
|
|
534
|
+
* human-directed policy, the reference runtime).
|
|
535
|
+
*/
|
|
536
|
+
interface ApolloAgentOptions {
|
|
537
|
+
/** The Atlas memory layer. Typically `origin.memory`. Defaults to a fresh in-memory store. */
|
|
538
|
+
memory?: Memory;
|
|
539
|
+
tools?: Tool[];
|
|
540
|
+
/** Defaults to `humanDirected()`. */
|
|
541
|
+
policy?: Policy;
|
|
542
|
+
context?: ContextEngine;
|
|
543
|
+
observability?: Observability;
|
|
544
|
+
/** Approval handler. Defaults to a CLI prompt for review/plan modes, auto-approve for auto modes. */
|
|
545
|
+
approver?: ApprovalHandler;
|
|
546
|
+
/** Reasoning/action runtime. Defaults to the built-in reference runtime. */
|
|
547
|
+
runtime?: Runtime;
|
|
548
|
+
root?: string;
|
|
549
|
+
provider?: SupportedProvider;
|
|
550
|
+
model?: string;
|
|
551
|
+
/** Provide an LLM completion directly (tests, custom routing). */
|
|
552
|
+
complete?: Completion;
|
|
553
|
+
}
|
|
554
|
+
/**
|
|
555
|
+
* Apollo Agent — the composable agent runtime that powers Origin. It reasons
|
|
556
|
+
* over a goal, uses tools, and acts safely under human control:
|
|
557
|
+
*
|
|
558
|
+
* ```ts
|
|
559
|
+
* const agent = new ApolloAgent({
|
|
560
|
+
* memory: origin.memory,
|
|
561
|
+
* tools: [calendar, mail, browser],
|
|
562
|
+
* policy: humanDirected(),
|
|
563
|
+
* });
|
|
564
|
+
* await agent.run("Prepare my launch plan");
|
|
565
|
+
* ```
|
|
566
|
+
*
|
|
567
|
+
* One run is: context → recall → plan → (gate → act → trace) per step →
|
|
568
|
+
* synthesize → verify → remember. Every decision is traced; every change passes
|
|
569
|
+
* the policy gate first.
|
|
570
|
+
*
|
|
571
|
+
* @see https://archic.es
|
|
572
|
+
*/
|
|
573
|
+
declare class ApolloAgent {
|
|
574
|
+
readonly memory: Memory;
|
|
575
|
+
readonly observability: Observability;
|
|
576
|
+
private readonly tools;
|
|
577
|
+
private readonly policy;
|
|
578
|
+
private readonly contextEngine;
|
|
579
|
+
private readonly approver;
|
|
580
|
+
private readonly runtime;
|
|
581
|
+
private readonly root;
|
|
582
|
+
constructor(options?: ApolloAgentOptions);
|
|
583
|
+
run(goal: string): Promise<MissionResult>;
|
|
584
|
+
}
|
|
585
|
+
|
|
586
|
+
interface PolicyOptions {
|
|
587
|
+
budget?: Partial<PolicyBudget>;
|
|
588
|
+
}
|
|
589
|
+
interface AutonomousOptions extends PolicyOptions {
|
|
590
|
+
/** Skip outside-root approval prompts. Use only for trusted, bounded tasks. */
|
|
591
|
+
fullAuto?: boolean;
|
|
592
|
+
}
|
|
593
|
+
/** True if `target`, resolved against `root`, escapes the workspace. */
|
|
594
|
+
declare function outsideRoot(target: string | undefined, root: string | undefined): boolean;
|
|
595
|
+
/**
|
|
596
|
+
* The default. Read-only work proceeds; anything that changes the world
|
|
597
|
+
* (write/exec/network/tool) requires human approval before it leaves the gate.
|
|
598
|
+
*/
|
|
599
|
+
declare function humanDirected(options?: PolicyOptions): Policy;
|
|
600
|
+
/** Plan and propose only — never execute. */
|
|
601
|
+
declare function reviewOnly(options?: PolicyOptions): Policy;
|
|
602
|
+
/** Execute within budget and scope. Outside the root still asks, unless full-auto. */
|
|
603
|
+
declare function autonomous(options?: AutonomousOptions): Policy;
|
|
604
|
+
|
|
605
|
+
export { type Tool as $, type ActionKind as A, type Policy as B, type Certificate as C, type PolicyBudget as D, type EvaluateOptions as E, type FileRef as F, type Gate as G, type PolicyContext as H, InMemoryStore as I, JsonlSink as J, type PolicyOptions as K, type ProposedAction as L, Memory as M, type ProviderCall as N, Observability as O, PROVIDER_KEY_ENV as P, type RecallOptions as Q, type RecallHit as R, type Redactor as S, ReferenceRuntime as T, type ReferenceRuntimeOptions as U, type RememberInput as V, type Runtime as W, type RuntimeContext as X, SUPPORTED_PROVIDERS as Y, type ScanOptions as Z, type SupportedProvider as _, ApolloAgent as a, type ToolContext as a0, type ToolRef as a1, type Trace as a2, type TraceEvent as a3, type TraceEventKind as a4, type TraceSink as a5, Tracer as a6, autonomous as a7, availableProviders as a8, callProviderStream as a9, callProviderText as aa, contractSchema as ab, defaultRedactor as ac, defineTool as ad, evaluateContract as ae, formatMemoriesBlock as af, humanDirected as ag, isSupportedProvider as ah, makeSSEParser as ai, outsideRoot as aj, parseContractFromPlan as ak, parseIntent as al, resolveProviderKey as am, reviewOnly as an, tokenize as ao, type ApolloAgentOptions as b, type ApolloMode as c, type ApprovalDecision as d, type ApprovalHandler as e, type ApprovalRequest as f, type AuthorizeResult as g, type AutonomousOptions as h, type ChatMessage as i, type ChatRole as j, type CheckResult as k, type Completion as l, type ContextBundle as m, ContextEngine as n, type Contract as o, type Intent as p, type MemoryKind as q, type MemoryOptions as r, type MemoryRecord as s, MemorySink as t, type MemoryStore as u, type MissionResult as v, type ObservabilityOptions as w, type Observation as x, type Plan as y, type PlanStep as z };
|
package/package.json
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@vornicx/origin",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Origin — a personal intelligence layer: context, memory (Atlas), observability, and human-directed agents. Interoperates with Apollo.",
|
|
5
|
+
"author": "vornicx",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"type": "module",
|
|
8
|
+
"sideEffects": false,
|
|
9
|
+
"engines": {
|
|
10
|
+
"node": ">=22.0.0"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"dist",
|
|
14
|
+
"README.md",
|
|
15
|
+
"LICENSE"
|
|
16
|
+
],
|
|
17
|
+
"main": "./dist/index.js",
|
|
18
|
+
"module": "./dist/index.js",
|
|
19
|
+
"types": "./dist/index.d.ts",
|
|
20
|
+
"exports": {
|
|
21
|
+
".": {
|
|
22
|
+
"types": "./dist/index.d.ts",
|
|
23
|
+
"import": "./dist/index.js"
|
|
24
|
+
},
|
|
25
|
+
"./apollo": {
|
|
26
|
+
"types": "./dist/apollo/index.d.ts",
|
|
27
|
+
"import": "./dist/apollo/index.js"
|
|
28
|
+
},
|
|
29
|
+
"./package.json": "./package.json"
|
|
30
|
+
},
|
|
31
|
+
"scripts": {
|
|
32
|
+
"build": "tsup",
|
|
33
|
+
"dev": "tsup --watch",
|
|
34
|
+
"typecheck": "tsc --noEmit",
|
|
35
|
+
"test": "vitest run",
|
|
36
|
+
"test:watch": "vitest",
|
|
37
|
+
"lint": "eslint .",
|
|
38
|
+
"format": "prettier --write .",
|
|
39
|
+
"example:launch": "tsx examples/launch-plan.ts",
|
|
40
|
+
"example:apollo": "tsx examples/with-apollo.ts",
|
|
41
|
+
"example:memory": "tsx examples/memory-for-apollo.ts",
|
|
42
|
+
"prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build"
|
|
43
|
+
},
|
|
44
|
+
"keywords": [
|
|
45
|
+
"origin",
|
|
46
|
+
"archic",
|
|
47
|
+
"apollo",
|
|
48
|
+
"ai",
|
|
49
|
+
"agent",
|
|
50
|
+
"memory",
|
|
51
|
+
"context",
|
|
52
|
+
"observability",
|
|
53
|
+
"llm",
|
|
54
|
+
"byok",
|
|
55
|
+
"human-in-the-loop"
|
|
56
|
+
],
|
|
57
|
+
"repository": {
|
|
58
|
+
"type": "git",
|
|
59
|
+
"url": "git+https://github.com/vornicx/origin.git"
|
|
60
|
+
},
|
|
61
|
+
"homepage": "https://archic.es",
|
|
62
|
+
"bugs": {
|
|
63
|
+
"url": "https://github.com/vornicx/origin/issues"
|
|
64
|
+
},
|
|
65
|
+
"publishConfig": {
|
|
66
|
+
"access": "public"
|
|
67
|
+
},
|
|
68
|
+
"dependencies": {
|
|
69
|
+
"zod": "^3.23.8"
|
|
70
|
+
},
|
|
71
|
+
"peerDependencies": {
|
|
72
|
+
"@supabase/supabase-js": ">=2",
|
|
73
|
+
"better-sqlite3": ">=11"
|
|
74
|
+
},
|
|
75
|
+
"peerDependenciesMeta": {
|
|
76
|
+
"@supabase/supabase-js": {
|
|
77
|
+
"optional": true
|
|
78
|
+
},
|
|
79
|
+
"better-sqlite3": {
|
|
80
|
+
"optional": true
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
"devDependencies": {
|
|
84
|
+
"@eslint/js": "^9.15.0",
|
|
85
|
+
"@types/node": "^22.10.0",
|
|
86
|
+
"@vitest/coverage-v8": "^2.1.8",
|
|
87
|
+
"eslint": "^9.15.0",
|
|
88
|
+
"globals": "^15.12.0",
|
|
89
|
+
"prettier": "^3.4.1",
|
|
90
|
+
"tsup": "^8.3.5",
|
|
91
|
+
"tsx": "^4.19.2",
|
|
92
|
+
"typescript": "^5.7.2",
|
|
93
|
+
"typescript-eslint": "^8.16.0",
|
|
94
|
+
"vitest": "^2.1.8"
|
|
95
|
+
}
|
|
96
|
+
}
|