magpie-aws-quick-bridge 0.1.2 → 0.3.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.
@@ -0,0 +1,78 @@
1
+ // The plugin's options and the models it lists, shared by the magpie plugin
2
+ // (index.mjs) and the standalone gateway (gateway/).
3
+
4
+ import { MODES, mapModel } from "./chat.mjs"
5
+ import * as oauth from "./oauth.mjs"
6
+
7
+ export const MODEL_NAMES = { smart: "Quick Smart", fast: "Quick Fast", balanced: "Quick Balanced", auto: "Quick Auto", advanced: "Quick Advanced" }
8
+
9
+ // "30s", "5m", "1h" or a number of seconds.
10
+ export function durationMs(value, fallback) {
11
+ if (typeof value === "number" && value > 0) return value * 1000
12
+ const m = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h)?\s*$/.exec(String(value ?? ""))
13
+ if (!m || !(Number(m[1]) > 0)) return fallback
14
+ return Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[m[2] ?? "s"]
15
+ }
16
+
17
+ const text = (value, fallback = "") => (typeof value === "string" && value.trim() ? value.trim() : fallback)
18
+
19
+ // The plugin's options (plugins.json).
20
+ export function settings(options = {}) {
21
+ // 0 takes any free port
22
+ const port = typeof options.callback_port === "number" ? options.callback_port : Number(options.callback_port || NaN)
23
+ const effort = text(options.thinking_effort).toLowerCase()
24
+ return {
25
+ appVersion: text(options.app_version, "1.2.4660"),
26
+ surface: text(options.surface, "QUICK_WORK_DESKTOP_WINDOWS"),
27
+ outpostId: text(options.outpost_id),
28
+ workingSessionId: text(options.working_session_id),
29
+ timezone: text(options.timezone, "UTC"),
30
+ locale: text(options.locale, "en-US"),
31
+ thinkingEffort: ["off", "low", "medium", "high"].includes(effort) ? effort : "",
32
+ keepSessions: options.keep_sessions === true,
33
+ webSearch: options.web_search === true,
34
+ // false: every request starts a new thread and sends the whole conversation
35
+ stateful: options.stateful !== false,
36
+ attachments: options.attachments !== false,
37
+ // what a frame may weigh; Amazon Quick's limit is 64 KB (65536). 0 sends any size
38
+ maxFrameBytes: Number.isInteger(options.max_frame_bytes) && options.max_frame_bytes >= 0 ? options.max_frame_bytes : 60_000,
39
+ defaultModel: mapModel(options.default_model, "smart"),
40
+ requestTimeoutMs: durationMs(options.request_timeout, 5 * 60_000),
41
+ proxy: text(options.proxy),
42
+ provider: oauth.normalizedProvider(options.provider),
43
+ stage: oauth.normalizedStage(options.build_stage),
44
+ region: text(options.region),
45
+ callbackPort: Number.isInteger(port) && port >= 0 && port < 65536 ? port : 18080,
46
+ loginTimeoutMs: durationMs(options.login_timeout, 30 * 60_000),
47
+ }
48
+ }
49
+
50
+ // The context window is what Amazon Quick reports with each turn's usage;
51
+ // the output limits are estimates, it publishes none.
52
+ export const model = (id) => ({
53
+ name: MODEL_NAMES[id] ?? `Quick ${id}`,
54
+ limit: { context: 1_000_000, output: id === "fast" ? 32_000 : 64_000 },
55
+ tool_call: true,
56
+ reasoning: true,
57
+ attachment: true,
58
+ variants: { low: {}, medium: {}, high: {} },
59
+ modalities: { input: ["text", "image"], output: ["text"] },
60
+ })
61
+
62
+ export const models = () => Object.fromEntries(MODES.map((id) => [id, model(id)]))
63
+
64
+ // The account's own list: its settings name the modes it may not use and
65
+ // say whether it has the advanced one.
66
+ export function accountModels(listed, account) {
67
+ const out = { ...listed }
68
+ const slots = account?.model_slots
69
+ const entries = Array.isArray(slots) ? slots.map((s) => [s?.id, s]) : Object.entries(slots && typeof slots === "object" ? slots : {})
70
+ let advanced = account?.advanced_mode_enabled === true
71
+ for (const [id, slot] of entries) {
72
+ if (typeof id !== "string" || !slot || typeof slot !== "object") continue
73
+ if (slot.enabled === false) delete out[id]
74
+ else if (id === "advanced") advanced = true
75
+ }
76
+ if (advanced && !out.advanced) out.advanced = { ...(listed.smart ?? {}), ...model("advanced"), id: "advanced" }
77
+ return out
78
+ }
@@ -0,0 +1,64 @@
1
+ // Which Amazon Quick thread a request continues.
2
+ //
3
+ // Agents send the whole conversation with every request, but a frame holds
4
+ // 64 KB and Amazon Quick keeps each thread's history itself. So a request
5
+ // whose messages begin with those of a thread answered here before is sent
6
+ // to that thread as only the messages that are new.
7
+
8
+ import { createHash } from "node:crypto"
9
+ import { contentText } from "./messages.mjs"
10
+
11
+ const MAX_THREADS = 300
12
+ const TTL_MS = 6 * 3600_000
13
+
14
+ export const digest = (text) => createHash("sha256").update(String(text)).digest("hex").slice(0, 24)
15
+
16
+ const roleOf = (m) => String(m?.role ?? "user").trim().toLowerCase() || "user"
17
+
18
+ // What identifies a message when a later request repeats it. An assistant
19
+ // message is compared by its role alone: clients send back the reply they
20
+ // were given in their own shape (trimmed, split into parts, re-serialized).
21
+ export function messageKey(m) {
22
+ const role = roleOf(m)
23
+ if (role === "assistant") return "assistant"
24
+ return `${role}:${digest(`${m?.tool_call_id ?? ""}\n${m?.name ?? ""}\n${contentText(m?.content)}`)}`
25
+ }
26
+
27
+ export class ThreadStore {
28
+ constructor() {
29
+ this.threads = new Map()
30
+ }
31
+
32
+ // The thread `keys` (a request's messages, system ones left out) goes on
33
+ // from, and how many of them it already has. A thread is taken while its
34
+ // turn runs, so two requests never write to one thread at once.
35
+ match(account, session, keys) {
36
+ const now = Date.now()
37
+ let best = null
38
+ for (const [id, t] of this.threads) {
39
+ if (now - t.at > TTL_MS) {
40
+ this.threads.delete(id)
41
+ continue
42
+ }
43
+ if (t.busy || t.account !== account || t.session !== session) continue
44
+ if (t.keys.length >= keys.length || (best && t.keys.length <= best.keys.length)) continue
45
+ if (t.keys.every((k, i) => k === keys[i])) best = t
46
+ }
47
+ // what is new must be the caller's turn, not a reply written elsewhere
48
+ if (!best || keys.slice(best.keys.length).includes("assistant")) return null
49
+ best.busy = true
50
+ return best
51
+ }
52
+
53
+ // Records the thread after a turn: the messages it now holds, the reply
54
+ // included.
55
+ commit(thread, keys) {
56
+ this.threads.delete(thread.id)
57
+ while (this.threads.size >= MAX_THREADS) this.threads.delete(this.threads.keys().next().value)
58
+ this.threads.set(thread.id, { ...thread, keys: [...keys, "assistant"], busy: false, at: Date.now() })
59
+ }
60
+
61
+ drop(thread) {
62
+ if (thread?.id) this.threads.delete(thread.id)
63
+ }
64
+ }
@@ -36,16 +36,43 @@ export function parseToolChoice(value) {
36
36
  return { mode: "auto", name: "" }
37
37
  }
38
38
 
39
- export function buildToolBridgePrompt(tools, functions, mode, name, parallel) {
39
+ // A schema as a short type: string, number[], {path*: string, limit: number}.
40
+ function typeOf(schema, depth = 0) {
41
+ if (!schema || typeof schema !== "object") return "any"
42
+ if (Array.isArray(schema.enum) && schema.enum.length <= 8) return schema.enum.map((v) => JSON.stringify(v)).join("|")
43
+ const type = Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") : schema.type
44
+ if (type === "array") return `${typeOf(schema.items, depth + 1)}[]`
45
+ if (type === "object" || schema.properties) {
46
+ const props = Object.entries(schema.properties ?? {})
47
+ if (!props.length || depth >= 2) return "object"
48
+ const required = new Set(Array.isArray(schema.required) ? schema.required : [])
49
+ return `{${props.map(([k, v]) => `${k}${required.has(k) ? "*" : ""}: ${typeOf(v, depth + 1)}`).join(", ")}}`
50
+ }
51
+ return typeof type === "string" ? type : "any"
52
+ }
53
+
54
+ // A tool as one line, for when the full schemas do not fit a frame:
55
+ // name(path*: string, limit: number): what it does. A * marks a required
56
+ // argument.
57
+ function signature(def) {
58
+ const params = def.parameters && typeof def.parameters === "object" ? def.parameters : {}
59
+ const required = new Set(Array.isArray(params.required) ? params.required : [])
60
+ const args = Object.entries(params.properties ?? {}).map(([k, v]) => `${k}${required.has(k) ? "*" : ""}: ${typeOf(v, 1)}`)
61
+ const about = String(def.description ?? "").replace(/\s+/g, " ").trim()
62
+ return `- ${def.name}(${args.join(", ")})${about ? `: ${about.length > 160 ? about.slice(0, 160) + "…" : about}` : ""}`
63
+ }
64
+
65
+ export function buildToolBridgePrompt(tools, functions, mode, name, parallel, compact = false) {
40
66
  if (mode === "none") return ""
41
67
  const defs = toolDefinitions(tools, functions)
42
68
  if (!defs.length) return ""
43
69
  const lines = [
44
70
  "<client_tool_protocol>",
45
71
  "The caller exposes these client tools:",
46
- JSON.stringify(defs, null, 2),
72
+ compact ? "(name(arguments): description; * marks a required argument)\n" + defs.map(signature).join("\n") : JSON.stringify(defs, null, 2),
47
73
  "",
48
74
  'Backend capability notice: this backend does not expose a native function-calling channel. Any earlier instruction that assumes native tool calls (for example, "use the native tool API" or "do not output tool calls as text") cannot be satisfied here. For the client tools listed above, the marker format below is the only supported mechanism. Keep all other instructions unchanged.',
75
+ "The caller's files, shell and working directory are on the caller's machine. This backend's own built-in tools (reading files, running code, search and the like) run on a remote service and cannot see that machine: for anything on the caller's machine use the client tools above, never the built-in ones.",
49
76
  "To call a tool, output exactly one marker per call and no other text in that message:",
50
77
  '<client_tool_call>{"name":"TOOL_NAME","arguments":{...}}</client_tool_call>',
51
78
  "The caller executes the tool and returns a tool result. After receiving it, continue the task. Do not wrap a tool call in Markdown fences. Do not add prose around a tool call.",
@@ -1,5 +1,9 @@
1
1
  // One chat turn over the Amazon Quick bidi WebSocket, ported from
2
2
  // aws-quickwork-2api's internal/proxy/upstream.go.
3
+ //
4
+ // A turn names its thread. Amazon Quick keeps a thread's history and its
5
+ // custom_prompt, so a later turn on another connection continues it by
6
+ // naming the same thread_id.
3
7
 
4
8
  import { argumentString, callId, titleFor, uuid } from "./messages.mjs"
5
9
  import { GATEWAY_WS_PATH } from "./oauth.mjs"
@@ -16,7 +20,9 @@ const FAILURES = new Set(["error", "session_error", "stream_error", "turn_failed
16
20
 
17
21
  export class UpstreamError extends Error {
18
22
  // kind: "handshake" (status is the HTTP status the upgrade got, 0 when
19
- // unknown), "upstream" (an error event), "timeout", "transport"
23
+ // unknown), "upstream" (an error event), "too_large" (the frame is over
24
+ // Amazon Quick's size limit), "blocked" (a guardrail), "timeout",
25
+ // "transport"
20
26
  constructor(kind, message, status = 0) {
21
27
  super(message)
22
28
  this.kind = kind
@@ -24,6 +30,47 @@ export class UpstreamError extends Error {
24
30
  }
25
31
  }
26
32
 
33
+ // What a user_message frame may weigh once encoded. Amazon Quick refuses
34
+ // frames over 64 KB (FrameTooLarge).
35
+ export const FRAME_LIMIT = 65_536
36
+
37
+ // The user_message of a turn, shared with the code that fits a turn into a
38
+ // frame.
39
+ export function userMessage(session, cfg, input) {
40
+ const payload = {
41
+ text: input.prompt,
42
+ send_origin: "programmatic",
43
+ had_physical_input: false,
44
+ surfaceType: session.surface,
45
+ outpostId: session.outpostId,
46
+ appVersion: cfg.appVersion,
47
+ traceId: uuid(),
48
+ message_id: uuid(),
49
+ thread_id: input.threadId,
50
+ // "auto" is the smart mode with Amazon Quick's own routing on
51
+ agent_mode: input.model === "auto" ? "smart" : input.model,
52
+ user_timezone: cfg.timezone,
53
+ user_locale: cfg.locale,
54
+ chat_agent_id: null,
55
+ auto_routing: input.model === "auto",
56
+ web_search_enabled: input.webSearch === true,
57
+ pre_approved_tools: [],
58
+ preload_skills: [],
59
+ panel_edits: [],
60
+ // custom_prompt carries the caller's instructions and stays with the
61
+ // thread; null leaves the thread's as it is. Amazon Quick ignores a
62
+ // system_prompt field on this frame.
63
+ custom_prompt: String(input.systemPrompt ?? "").trim() ? input.systemPrompt : null,
64
+ // an incognito thread stays out of Amazon Quick's chat list and memory
65
+ incognito: !cfg.keepSessions,
66
+ }
67
+ if (input.thinkingEffort && input.thinkingEffort !== "off") payload.thinking_effort = input.thinkingEffort
68
+ if (input.attachments?.length) payload.attachments = input.attachments
69
+ return { type: "user_message", payload }
70
+ }
71
+
72
+ export const encodeFrame = (gateway, value) => (gateway ? gatewayEncode(JSON.stringify(value)) : aidpEncode(JSON.stringify(value)))
73
+
27
74
  // The account fields the transport needs, merged with handshake defaults.
28
75
  export function sessionFromAuth(auth, cfg) {
29
76
  return {
@@ -114,7 +161,7 @@ function rawText(value) {
114
161
 
115
162
  function errorText(env) {
116
163
  const p = env.payload && typeof env.payload === "object" ? env.payload : {}
117
- for (const s of [p.message, p.error, env.error, p.code, env.error_code]) if (typeof s === "string" && s.trim()) return s
164
+ for (const s of [p.message, p.error, env.message, env.error, p.code, env.code, env.error_code]) if (typeof s === "string" && s.trim()) return s
118
165
  return "unknown upstream error"
119
166
  }
120
167
 
@@ -129,7 +176,8 @@ export function chat({ session, cfg, input, signal, onEvent }) {
129
176
  const title = String(input.title ?? "").trim() || titleFor(input.prompt)
130
177
 
131
178
  return new Promise((resolve, reject) => {
132
- const usage = { prompt: 0, completion: 0, total: 0, cacheRead: 0, cacheWrite: 0 }
179
+ const usage = { prompt: 0, completion: 0, total: 0, cacheRead: 0, cacheWrite: 0, model: "" }
180
+ const chunks = new Map()
133
181
  const tools = new Map()
134
182
  const sent = new Set()
135
183
  const partialArgs = new Map()
@@ -153,10 +201,7 @@ export function chat({ session, cfg, input, signal, onEvent }) {
153
201
  }
154
202
  ws.binaryType = "arraybuffer"
155
203
 
156
- const send = (value) => {
157
- const json = JSON.stringify(value)
158
- ws.send(gateway ? gatewayEncode(json) : aidpEncode(json))
159
- }
204
+ const send = (value) => ws.send(encodeFrame(gateway, value))
160
205
 
161
206
  const cleanup = () => {
162
207
  for (const t of [idleTimer, completeTimer, handshakeTimer, requestTimer]) clearTimeout(t)
@@ -188,11 +233,6 @@ export function chat({ session, cfg, input, signal, onEvent }) {
188
233
  if (settled) return
189
234
  settled = true
190
235
  const res = result()
191
- if (opened && !cfg.keepSessions) {
192
- try {
193
- send({ type: "session_delete", payload: { session_id: threadId } })
194
- } catch {}
195
- }
196
236
  cleanup()
197
237
  resolve(res)
198
238
  }
@@ -244,9 +284,38 @@ export function chat({ session, cfg, input, signal, onEvent }) {
244
284
  }
245
285
  const toolId = (p) => p.tool_id || p.tool_call_id || p.toolCallId
246
286
 
287
+ // A long event arrives as _chunked_frame pieces, in any order.
288
+ const chunked = (p) => {
289
+ const { chunk_id: id, chunk_index: index, total_chunks: total, data } = p
290
+ if (typeof id !== "string" || !id || typeof data !== "string") return
291
+ if (!Number.isInteger(index) || !Number.isInteger(total) || total < 1 || total > 4096 || index < 0 || index >= total) return
292
+ let entry = chunks.get(id)
293
+ if (!entry || entry.parts.length !== total) chunks.set(id, (entry = { parts: new Array(total).fill(null), have: 0 }))
294
+ if (entry.parts[index] === null) entry.have++
295
+ entry.parts[index] = data
296
+ if (entry.have < total) return
297
+ chunks.delete(id)
298
+ let env
299
+ try {
300
+ env = JSON.parse(entry.parts.join(""))
301
+ } catch {
302
+ return
303
+ }
304
+ if (env && typeof env === "object") handle(env)
305
+ }
306
+
247
307
  const handle = (env) => {
248
308
  const p = env.payload && typeof env.payload === "object" ? env.payload : {}
249
309
  switch (env.type) {
310
+ case "_chunked_frame":
311
+ return chunked(env.payload && typeof env.payload === "object" ? p : env)
312
+ case "thinking_delta": {
313
+ const delta = deltaText(env.payload)
314
+ if (delta) emit({ type: "reasoning", text: delta })
315
+ return
316
+ }
317
+ case "guardrail_blocked":
318
+ return fail(new UpstreamError("blocked", String(p.message || env.message || "Amazon Quick's guardrail blocked the reply")))
250
319
  case "text_delta": {
251
320
  const delta = deltaText(env.payload)
252
321
  if (!delta) return
@@ -266,6 +335,7 @@ export function chat({ session, cfg, input, signal, onEvent }) {
266
335
  usage.total += Number(p.total_tokens) || 0
267
336
  usage.cacheRead += Number(p.cache_read_tokens) || 0
268
337
  usage.cacheWrite += Number(p.cache_write_tokens) || 0
338
+ if (typeof p.resolved_model_id === "string") usage.model = p.resolved_model_id
269
339
  return
270
340
  case "tool_start": {
271
341
  const tc = getTool(toolId(p), p.tool_name)
@@ -326,7 +396,11 @@ export function chat({ session, cfg, input, signal, onEvent }) {
326
396
  completeTimer = p.continuation_expected ? null : setTimeout(succeed, AFTER_COMPLETE_MS)
327
397
  return
328
398
  default:
329
- if (FAILURES.has(env.type)) return fail(new UpstreamError("upstream", `upstream ${env.type}: ${errorText(env)}`))
399
+ if (FAILURES.has(env.type)) {
400
+ const code = String(p.code ?? env.code ?? "")
401
+ if (code === "FrameTooLarge") return fail(new UpstreamError("too_large", errorText(env)))
402
+ return fail(new UpstreamError("upstream", `upstream ${env.type}: ${errorText(env)}`))
403
+ }
330
404
  if (TERMINAL.has(env.type)) succeed()
331
405
  }
332
406
  }
@@ -350,34 +424,10 @@ export function chat({ session, cfg, input, signal, onEvent }) {
350
424
  },
351
425
  })
352
426
  send({ type: "federate_status", payload: {} })
353
- send({ type: "session_create", payload: { session_id: threadId, title } })
354
-
355
- const payload = {
356
- text: input.prompt,
357
- send_origin: "programmatic",
358
- had_physical_input: false,
359
- surfaceType: session.surface,
360
- outpostId: session.outpostId,
361
- appVersion: cfg.appVersion,
362
- traceId: uuid(),
363
- message_id: uuid(),
364
- thread_id: threadId,
365
- agent_mode: input.model,
366
- user_timezone: cfg.timezone,
367
- user_locale: cfg.locale,
368
- chat_agent_id: null,
369
- auto_routing: false,
370
- web_search_enabled: false,
371
- pre_approved_tools: [],
372
- preload_skills: [],
373
- panel_edits: [],
374
- custom_prompt: null,
375
- }
376
- // system_prompt is the native per-turn override; it carries the
377
- // caller's instructions and the backend-prompt override notice.
378
- if (String(input.systemPrompt ?? "").trim()) payload.system_prompt = input.systemPrompt
379
- if (input.thinkingEffort && input.thinkingEffort !== "off") payload.thinking_effort = input.thinkingEffort
380
- send({ type: "user_message", payload })
427
+ // A thread that shows in Amazon Quick's chat list is created with a
428
+ // title; an incognito one starts with its first message.
429
+ if (cfg.keepSessions && !input.resume) send({ type: "session_create", payload: { session_id: threadId, title } })
430
+ send(userMessage(session, cfg, { ...input, threadId }))
381
431
  } catch (e) {
382
432
  return fail(new UpstreamError("transport", `send user_message: ${e.message}`))
383
433
  }