@arcforge/core 2.0.218 → 2.0.244

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.
@@ -0,0 +1,114 @@
1
+ import { err } from "@arcforge/err"
2
+ import type { CognetUse, EngineRequirement, EngineRequirements, ServiceGrant } from "@arcforge/types"
3
+ import { STANDARD } from "./standard"
4
+
5
+ /** A grant, read: off, auto, one of the agent's own providers, or a route its inference sources supply — and its limit. */
6
+ export type Granted =
7
+ | { kind: "off" }
8
+ | { kind: "auto"; limit?: Limit }
9
+ | { kind: "own"; path: string; limit?: Limit }
10
+ | { kind: "route"; pin: string; limit?: Limit }
11
+
12
+ type Limit = Exclude<ServiceGrant, string>["limit"]
13
+
14
+ /**
15
+ * What the agent granted each use — read once, the same way wherever a use is
16
+ * resolved: in this process, or on the supervisor's side of a confined one.
17
+ * Absent is `auto`. A grant for a use the cognet does not declare is a
18
+ * mistake, not something to ignore.
19
+ */
20
+ export function granted(uses: Readonly<Record<string, CognetUse>>, grants: Readonly<Record<string, ServiceGrant>> | undefined): Record<string, Granted> {
21
+ for (const name of Object.keys(grants ?? {})) {
22
+ if (!uses[name]) throw err("SERVICE_INVALID", { detail: `services.${name}: the cognet declares no use "${name}" — it uses ${Object.keys(uses).join(", ") || "nothing"}`, context: { use: name } })
23
+ }
24
+ return Object.fromEntries(Object.keys(uses).map(name => [name, read(name, grants?.[name])]))
25
+ }
26
+
27
+ /** One grant, its shape checked: axon.config.ts is evaluated as written, so nothing has checked it before here. */
28
+ function read(name: string, grant: unknown): Granted {
29
+ if (grant === undefined || grant === "auto") return { kind: "auto" }
30
+ if (grant === "off") return { kind: "off" }
31
+ if (typeof grant === "string") return named(grant, undefined)
32
+ if (typeof grant !== "object" || grant === null) throw invalid(name, `a provider, "auto", "off", or { provider?, limit? } — not ${JSON.stringify(grant)}`)
33
+ const { provider, limit } = grant as { provider?: unknown; limit?: unknown }
34
+ if (provider !== undefined && typeof provider !== "string") throw invalid(name, "a provider named as text")
35
+ if (limit !== undefined) {
36
+ const { calls, usd, per } = limit as { calls?: unknown; usd?: unknown; per?: unknown }
37
+ if (typeof limit !== "object" || limit === null || !["second", "minute", "hour", "day"].includes(per as string)) throw invalid(name, `a limit { calls?, usd?, per: "second" | "minute" | "hour" | "day" }`)
38
+ if ((calls !== undefined && !(Number.isInteger(calls) && (calls as number) > 0)) || (usd !== undefined && !(typeof usd === "number" && usd > 0))) throw invalid(name, "a limit of a whole number of calls, or an amount of money, above 0")
39
+ }
40
+ return object(grant as Exclude<ServiceGrant, string>)
41
+ }
42
+
43
+ function invalid(name: string, must: string) {
44
+ return err("SERVICE_INVALID", { detail: `services.${name} must be ${must}`, context: { use: name } })
45
+ }
46
+
47
+ function object(grant: Exclude<ServiceGrant, string>): Granted {
48
+ const limit = grant.limit
49
+ if (grant.provider === undefined || grant.provider === "auto") return { kind: "auto", ...(limit ? { limit: limit } : {}) }
50
+ return named(grant.provider, limit)
51
+ }
52
+
53
+ function named(provider: string, limit: Limit): Granted {
54
+ return provider.startsWith("./")
55
+ ? { kind: "own", path: provider, ...(limit ? { limit: limit } : {}) }
56
+ : { kind: "route", pin: provider, ...(limit ? { limit: limit } : {}) }
57
+ }
58
+
59
+ /**
60
+ * The engine roles the machine's own engines are asked to fill — one per use
61
+ * of a standard interface that a route may serve — and the routes granted by
62
+ * name. A use granted off, or to one of the agent's own providers, asks the
63
+ * engines for nothing.
64
+ */
65
+ export function engineRoles(uses: Readonly<Record<string, CognetUse>>, grants: Readonly<Record<string, Granted>>): { requirements: EngineRequirements; pins: Record<string, string> } {
66
+ const requirements: EngineRequirements = {}
67
+ const pins: Record<string, string> = {}
68
+ for (const [name, use] of Object.entries(uses)) {
69
+ const grant = grants[name]!
70
+ const adapter = STANDARD[use.named]
71
+ if (!adapter && use.model !== undefined) throw err("SERVICE_INVALID", { detail: `${name} names a model, but ${use.named} is not served by any engine — only a provider the agent writes can serve it`, context: { use: name } })
72
+ if (grant.kind === "off" || grant.kind === "own") continue
73
+ if (!adapter) {
74
+ if (grant.kind === "route") throw err("SERVICE_INVALID", { detail: `services.${name}: granted "${grant.pin}", but ${use.named} is not served by any engine — only a provider the agent writes can serve it`, context: { use: name } })
75
+ continue
76
+ }
77
+ requirements[name] = { ...adapter.requirement(use), ...shared(use) }
78
+ if (grant.kind === "route") pins[name] = grant.pin
79
+ }
80
+ return { requirements: requirements, pins: pins }
81
+ }
82
+
83
+ /**
84
+ * What a use decides of its requirement whatever its interface. A `slots`
85
+ * minimum in `requires` asks for that many at once as surely as `parallel`
86
+ * does — it is then also held against what binds.
87
+ */
88
+ function shared(use: CognetUse): Partial<EngineRequirement> {
89
+ const slots = use.requires?.slots
90
+ const least = typeof slots === "number" ? slots : typeof slots === "object" && slots !== null && "min" in slots ? slots.min ?? 1 : 1
91
+ return {
92
+ ...(use.optional ? { optional: true } : {}),
93
+ ...(use.primary ? { primary: true } : {}),
94
+ ...(use.model !== undefined ? { model: typeof use.model === "string" ? [use.model] : use.model } : {}),
95
+ ...((use.parallel ?? 1) > 1 || least > 1 ? { parallel: true } : {}),
96
+ }
97
+ }
98
+
99
+ /**
100
+ * What can be known about the grants before anything runs — at prepare: each
101
+ * names a use the cognet declares, a provider of the agent's own that exists,
102
+ * and no route for an interface no engine serves. Throws on the first that
103
+ * does not. Whether a route can actually be reached is the boot's to find.
104
+ */
105
+ export function checked(uses: Readonly<Record<string, CognetUse>>, grants: Readonly<Record<string, ServiceGrant>> | undefined, providers: ReadonlyArray<{ name: string; implements: string }>): void {
106
+ const read = granted(uses, grants)
107
+ engineRoles(uses, read)
108
+ for (const [name, grant] of Object.entries(read)) {
109
+ if (grant.kind !== "own") continue
110
+ const provider = providers.find(one => one.name === grant.path)
111
+ if (!provider) throw err("SERVICE_INVALID", { detail: `services.${name}: no provider ${grant.path} — write providers/${grant.path.slice("./providers/".length)}.provider.ts`, context: { use: name } })
112
+ if (provider.implements !== uses[name]!.named) throw err("SERVICE_INVALID", { detail: `services.${name}: ${grant.path} implements ${provider.implements}, but ${name} uses ${uses[name]!.named}`, context: { use: name } })
113
+ }
114
+ }
@@ -0,0 +1,203 @@
1
+ import type {
2
+ AxonDriver,
3
+ AxonEngineDriver,
4
+ AxonEngineMessage,
5
+ AxonEngineResponse,
6
+ AxonTransformDriver,
7
+ EngineRequirement,
8
+ ResolvedEngineFacts,
9
+ ServiceProvider,
10
+ ServiceUse,
11
+ } from "@arcforge/types"
12
+ import { err } from "@arcforge/err"
13
+
14
+ /** What a standard interface's adapter knows: how a use of it resolves, and how a bound driver serves it. */
15
+ type Adapter = {
16
+ /**
17
+ * What a model must be to answer this interface for this use. Only what
18
+ * the interface decides; what every use decides alike — optional,
19
+ * primary, its models, how many at once — is added by `engineRoles`.
20
+ */
21
+ requirement(use: ServiceUse): EngineRequirement
22
+ /**
23
+ * The driver bound to that requirement, as a provider of the interface.
24
+ * `name` is the route that serves it; `facts` what resolution learned of
25
+ * it — the same facts a confined agent is sent, so one adapter serves both.
26
+ */
27
+ provider(driver: AxonDriver, name: string, facts: ResolvedEngineFacts): ServiceProvider
28
+ }
29
+
30
+ /**
31
+ * The standard interfaces the machine's own engines serve — each a table row,
32
+ * never a branch. A row maps an interface onto the engine requirement that
33
+ * finds a model able to answer it, and wraps the model's driver as a
34
+ * provider: the interface's values in, the driver's own shapes across, the
35
+ * interface's values back.
36
+ *
37
+ * An interface not here is served only by a provider the agent writes.
38
+ */
39
+ export const STANDARD: Readonly<Record<string, Adapter>> = {
40
+ "chat@1": {
41
+ requirement: use => ({
42
+ type: "generate",
43
+ in: wants(use, "pictures", true) ? ["text", "image"] : ["text"],
44
+ out: ["text"],
45
+ ...(min(use, "context") !== undefined ? { context: min(use, "context") } : {}),
46
+ }),
47
+ provider: (driver, name, facts) => {
48
+ const generate = kind(driver, "generate", name) as AxonEngineDriver
49
+ return {
50
+ name: name,
51
+ describe: () => ({
52
+ ...(facts.context !== undefined ? { context: facts.context } : {}),
53
+ pictures: facts.modalities.in.includes("image"),
54
+ slots: facts.slots,
55
+ }),
56
+ async call(method, args, signal) {
57
+ if (method !== "request") throw unknown(name, "chat@1", method)
58
+ let text = ""
59
+ for await (const event of generate.stream(request(args, name, signal))) {
60
+ if (event.type === "text:delta") text += event.content
61
+ if (event.type === "done") return reply(event.response, text)
62
+ }
63
+ throw err("SERVICE_FAILED", { detail: `${name} ended its reply without saying it was done` })
64
+ },
65
+ async *stream(method, args, signal) {
66
+ if (method !== "stream") throw unknown(name, "chat@1", method)
67
+ for await (const event of generate.stream(request(args, name, signal))) {
68
+ if (event.type === "text:delta") yield { text: event.content }
69
+ if (event.type === "done") {
70
+ const { stop, usage } = reply(event.response, "")
71
+ yield { text: "", stop: stop, ...(usage ? { usage: usage } : {}) }
72
+ return
73
+ }
74
+ }
75
+ throw err("SERVICE_FAILED", { detail: `${name} ended its reply without saying it was done` })
76
+ },
77
+ open: () => Promise.reject(unknown(name, "chat@1", "open")),
78
+ release: () => Promise.resolve(),
79
+ }
80
+ },
81
+ },
82
+
83
+ "depth-relative@1": {
84
+ requirement: () => ({ type: "transform", in: ["image"], out: ["depth"] }),
85
+ provider: (driver, name) => {
86
+ const transform = kind(driver, "transform", name) as AxonTransformDriver
87
+ return {
88
+ name: name,
89
+ describe: () => ({}),
90
+ async call(method, args, signal) {
91
+ if (method !== "estimate") throw unknown(name, "depth-relative@1", method)
92
+ const answer = await transform.transform(image(args.picture), signal ? { signal: signal } : {}) as { depth: Tensor }
93
+ const [height, width] = answer.depth.dims as [number, number]
94
+ return { width: width, height: height, nearness: floats(answer.depth) }
95
+ },
96
+ stream: () => { throw unknown(name, "depth-relative@1", "stream") },
97
+ open: () => Promise.reject(unknown(name, "depth-relative@1", "open")),
98
+ release: () => Promise.resolve(),
99
+ }
100
+ },
101
+ },
102
+
103
+ "segment@1": {
104
+ requirement: () => ({ type: "transform", in: ["image"], out: ["masks"] }),
105
+ provider: (driver, name) => {
106
+ const transform = kind(driver, "transform", name) as AxonTransformDriver
107
+ /** Encoded pictures, by the id handed out for each. The model encodes per prompt; the picture is what is kept. */
108
+ const kept = new Map<string, unknown>()
109
+ return {
110
+ name: name,
111
+ describe: () => ({}),
112
+ async call(method, args, signal) {
113
+ if (method === "encode") {
114
+ const id = Bun.randomUUIDv7()
115
+ kept.set(id, image(args.picture))
116
+ return { handle: "Encoded", id: id }
117
+ }
118
+ if (method !== "mask") throw unknown(name, "segment@1", method)
119
+ const encoded = args.encoded as { id: string }
120
+ const picture = kept.get(encoded.id)
121
+ if (!picture) throw err("SERVICE_HANDLE_ENDED", { detail: `${name} keeps no picture ${encoded.id}` })
122
+ const prompt = args.prompt as { point?: [number, number]; box?: number[] }
123
+ if (!prompt.point) throw err("SERVICE_INVALID", { detail: `${name} finds a region from a point; a box prompt is not something it can answer` })
124
+ const answer = await transform.transform({ kind: "segment", image: picture, points: [{ x: prompt.point[0], y: prompt.point[1] }] }, signal ? { signal: signal } : {}) as { masks: Array<{ mask: Tensor; score: number }> }
125
+ const found = answer.masks[0]
126
+ if (!found) throw err("SERVICE_FAILED", { detail: `${name} answered a prompt with no region` })
127
+ const [height, width] = found.mask.dims as [number, number]
128
+ return { width: width, height: height, mask: bytes(found.mask), score: found.score }
129
+ },
130
+ stream: () => { throw unknown(name, "segment@1", "stream") },
131
+ open: () => Promise.reject(unknown(name, "segment@1", "open")),
132
+ async release(id) {
133
+ kept.delete(id)
134
+ },
135
+ }
136
+ },
137
+ },
138
+ }
139
+
140
+ /** A tensor, as a transform driver answers with it. */
141
+ type Tensor = { dims: number[]; dtype: "float32" | "uint8"; data: string }
142
+
143
+ /** The conversation, as the driver is asked it. Pictures cross as a stimulus reference, which a raw picture is not. */
144
+ function request(args: Readonly<Record<string, unknown>>, name: string, signal?: AbortSignal) {
145
+ const conversation = args.conversation as { system?: string; messages: Array<{ role: string; text: string; pictures?: unknown[] }>; limit?: number }
146
+ const messages: AxonEngineMessage[] = [
147
+ ...(conversation.system !== undefined ? [{ role: "system" as const, content: conversation.system }] : []),
148
+ ...conversation.messages.map(message => {
149
+ if (message.pictures?.length) throw err("SERVICE_INVALID", { detail: `${name}: pictures in a conversation are not wired through this provider yet` })
150
+ if (message.role !== "user" && message.role !== "assistant") throw err("SERVICE_INVALID", { detail: `a message's role is "user" or "assistant", not "${message.role}"` })
151
+ return { role: message.role, content: message.text } as AxonEngineMessage
152
+ }),
153
+ ]
154
+ return { messages: messages, ...(conversation.limit !== undefined ? { maxTokens: conversation.limit } : {}), ...(signal ? { signal: signal } : {}) }
155
+ }
156
+
157
+ function reply(response: AxonEngineResponse, written: string) {
158
+ if (response.stopReason === "abort") throw new DOMException("the reply was cancelled", "AbortError")
159
+ const tokens = response.meta.tokens
160
+ return {
161
+ text: written || response.text,
162
+ stop: response.stopReason === "length" ? "limit" : "done",
163
+ ...(tokens ? { usage: { input: tokens.in, output: tokens.out } } : {}),
164
+ }
165
+ }
166
+
167
+ /** A picture, as a transform driver takes one: RGB bytes, base64 across a socket. */
168
+ function image(picture: unknown) {
169
+ const { width, height, rgb } = picture as { width: number; height: number; rgb: Uint8Array }
170
+ if (rgb.length !== width * height * 3) throw err("SERVICE_INVALID", { detail: `a ${width}×${height} picture holds ${width * height * 3} bytes, not ${rgb.length}` })
171
+ return { kind: "image", width: width, height: height, channels: 3, data: Buffer.from(rgb.buffer, rgb.byteOffset, rgb.byteLength).toString("base64") }
172
+ }
173
+
174
+ function floats(tensor: Tensor): Float32Array {
175
+ const raw = Buffer.from(tensor.data, "base64")
176
+ return new Float32Array(raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength))
177
+ }
178
+
179
+ function bytes(tensor: Tensor): Uint8Array {
180
+ return new Uint8Array(Buffer.from(tensor.data, "base64"))
181
+ }
182
+
183
+ function kind(driver: AxonDriver, expected: "generate" | "transform", name: string): AxonDriver {
184
+ const actual = driver.kind ?? "generate"
185
+ if (actual !== expected) throw err("SERVICE_FAILED", { detail: `${name} was bound as a ${actual} engine where a ${expected} engine was resolved` })
186
+ return driver
187
+ }
188
+
189
+ function unknown(name: string, named: string, method: string) {
190
+ return err("SERVICE_INVALID", { detail: `${name} serves ${named}, which has no ${method}` })
191
+ }
192
+
193
+ /** The `min` a use requires of a numeric field of describe(), if any. */
194
+ function min(use: ServiceUse, field: string): number | undefined {
195
+ const required = use.requires?.[field]
196
+ if (typeof required === "number") return required
197
+ if (typeof required === "object" && required !== null && "min" in required) return required.min
198
+ return undefined
199
+ }
200
+
201
+ function wants(use: ServiceUse, field: string, value: unknown): boolean {
202
+ return use.requires?.[field] === value
203
+ }
@@ -32,9 +32,9 @@ export type MediateOpts = {
32
32
  check(fn: string, subject: string, args: unknown[], owner: string): Promise<boolean>
33
33
  /** Span emission — the audit trail every surface reads. */
34
34
  emit: {
35
- start(input: { module: string; fn: string; args: unknown[] }): void
36
- complete(input: { module: string; fn: string; result: unknown; durationMs: number }): void
37
- failed(input: { module: string; fn: string; error: unknown; durationMs: number }): void
35
+ start(input: { module: string; fn: string; args: unknown[] }): Promise<string>
36
+ complete(input: { module: string; fn: string; result: unknown; durationMs: number; spanId: string }): Promise<void>
37
+ failed(input: { module: string; fn: string; error: unknown; durationMs: number; spanId: string }): Promise<void>
38
38
  }
39
39
  }
40
40
 
@@ -64,15 +64,16 @@ export function mediate(opts: MediateOpts, value: unknown, path: string, owner:
64
64
  // :start with no matching end would leave a permanently-open
65
65
  // bracket in every flame graph.
66
66
  const started = Date.now()
67
- opts.emit.start({ module: owner, fn: path, args })
67
+ const spanId = await opts.emit.start({ module: owner, fn: path, args })
68
+ let result: unknown
68
69
  try {
69
- const result = await Reflect.apply(value as (...a: unknown[]) => unknown, receiver, args)
70
- opts.emit.complete({ module: owner, fn: path, result, durationMs: Date.now() - started })
71
- return result
70
+ result = await Reflect.apply(value as (...a: unknown[]) => unknown, receiver, args)
72
71
  } catch (cause) {
73
- opts.emit.failed({ module: owner, fn: path, error: cause, durationMs: Date.now() - started })
72
+ await opts.emit.failed({ module: owner, fn: path, error: cause, durationMs: Date.now() - started, spanId: spanId })
74
73
  throw cause
75
74
  }
75
+ await opts.emit.complete({ module: owner, fn: path, result, durationMs: Date.now() - started, spanId: spanId })
76
+ return result
76
77
  }
77
78
  }
78
79