@coalex-ai/sdk 1.13.0 → 1.14.0-beta.58
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/README.md +18 -0
- package/dist/context.d.ts +11 -0
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +72 -37
- package/dist/context.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -98,6 +98,24 @@ const result = await coalexContext(
|
|
|
98
98
|
);
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
+
Agents that fetch their prompt once at startup (outside any request trace) can attribute each
|
|
102
|
+
request to a prompt version by passing `promptVersion` / `promptType` per invocation — the
|
|
103
|
+
TypeScript mirror of the Python SDK's `coalex_context(prompt_version=...)`. Every span in the
|
|
104
|
+
context (and any span that starts outside it, via the same fallback `getPrompt()` uses) is then
|
|
105
|
+
stamped with `coalex.prompt_version` / `coalex.prompt_type`.
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
const prompt = await getPrompt({ agent: "my-agent", name: "system" }); // once, at startup
|
|
109
|
+
|
|
110
|
+
// per request:
|
|
111
|
+
await coalexContext(
|
|
112
|
+
{ agentId: "my-agent", requestId: "req-123", promptVersion: prompt.version, promptType: prompt.promptType },
|
|
113
|
+
async () => {
|
|
114
|
+
// traced code — spans carry coalex.prompt_version
|
|
115
|
+
},
|
|
116
|
+
);
|
|
117
|
+
```
|
|
118
|
+
|
|
101
119
|
### `evaluate(options)`
|
|
102
120
|
|
|
103
121
|
Submit an AI output for evaluation. Returns the governance decision.
|
package/dist/context.d.ts
CHANGED
|
@@ -5,6 +5,8 @@ export declare function getLastPrompt(): {
|
|
|
5
5
|
version: number;
|
|
6
6
|
type: string;
|
|
7
7
|
} | null;
|
|
8
|
+
/** Reset the prompt fallback. Used by coalexContext() to restore the prior value on exit. */
|
|
9
|
+
export declare function clearLastPrompt(): void;
|
|
8
10
|
/**
|
|
9
11
|
* Return the agentId of the active coalexContext(), or undefined outside one.
|
|
10
12
|
* Lets evaluate() propagate the agentId for mid-run escalations that fire before
|
|
@@ -16,6 +18,15 @@ export interface CoalexContextOptions {
|
|
|
16
18
|
agentId: string;
|
|
17
19
|
requestId?: string;
|
|
18
20
|
version?: string;
|
|
21
|
+
/**
|
|
22
|
+
* Prompt Vault version driving this invocation. Lets an agent that fetches its prompt once at
|
|
23
|
+
* startup (outside any request trace) attribute each request to a prompt version — getPrompt()
|
|
24
|
+
* only stamps the trace it runs in, so the cache-at-startup pattern passes the version here per
|
|
25
|
+
* request (COA-1339 / COA-368). The TypeScript mirror of Python `coalex_context(prompt_version=)`.
|
|
26
|
+
*/
|
|
27
|
+
promptVersion?: number;
|
|
28
|
+
/** Prompt type (e.g. "system"). Paired with {@link promptVersion}. */
|
|
29
|
+
promptType?: string;
|
|
19
30
|
}
|
|
20
31
|
export declare function coalexContext<T>(options: CoalexContextOptions, fn: () => Promise<T> | T): Promise<T>;
|
|
21
32
|
export declare function coalexContextSync<T>(options: CoalexContextOptions, fn: () => T): T;
|
package/dist/context.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAeA,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEjE;AAED,yEAAyE;AACzE,wBAAgB,aAAa,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAeA,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEjE;AAED,yEAAyE;AACzE,wBAAgB,aAAa,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAExE;AAED,6FAA6F;AAC7F,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAmCD,wBAAsB,aAAa,CAAC,CAAC,EACnC,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,OAAO,EAAE,oBAAoB,EAC7B,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAwBH"}
|
package/dist/context.js
CHANGED
|
@@ -18,6 +18,10 @@ export function setLastPrompt(version, type) {
|
|
|
18
18
|
export function getLastPrompt() {
|
|
19
19
|
return _lastPrompt;
|
|
20
20
|
}
|
|
21
|
+
/** Reset the prompt fallback. Used by coalexContext() to restore the prior value on exit. */
|
|
22
|
+
export function clearLastPrompt() {
|
|
23
|
+
_lastPrompt = null;
|
|
24
|
+
}
|
|
21
25
|
/**
|
|
22
26
|
* Return the agentId of the active coalexContext(), or undefined outside one.
|
|
23
27
|
* Lets evaluate() propagate the agentId for mid-run escalations that fire before
|
|
@@ -27,8 +31,7 @@ export function getLastPrompt() {
|
|
|
27
31
|
export function currentAgentId() {
|
|
28
32
|
return agentIdStore.getStore();
|
|
29
33
|
}
|
|
30
|
-
|
|
31
|
-
const tracer = trace.getTracer("coalex");
|
|
34
|
+
function buildInvocationAttributes(options) {
|
|
32
35
|
const attrs = { "coalex.agent_id": options.agentId };
|
|
33
36
|
if (options.requestId !== undefined) {
|
|
34
37
|
attrs["coalex.request_id"] = options.requestId;
|
|
@@ -36,45 +39,77 @@ export async function coalexContext(options, fn) {
|
|
|
36
39
|
if (options.version !== undefined) {
|
|
37
40
|
attrs["coalex.agent_version"] = options.version;
|
|
38
41
|
}
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
42
|
+
if (options.promptVersion !== undefined) {
|
|
43
|
+
attrs["coalex.prompt_version"] = options.promptVersion;
|
|
44
|
+
}
|
|
45
|
+
if (options.promptType !== undefined) {
|
|
46
|
+
attrs["coalex.prompt_type"] = options.promptType;
|
|
47
|
+
}
|
|
48
|
+
return attrs;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* When a prompt version is supplied, update the process-global fallback the propagator reads, so
|
|
52
|
+
* spans that escape the invocation-span parent chain (e.g. auto-instrumentor root spans with their
|
|
53
|
+
* own trace) are still attributed — the mirror of the Python contextvar. Returns a restore fn so a
|
|
54
|
+
* request's version doesn't leak into a later invocation that passes none. Process-global: under
|
|
55
|
+
* concurrent invocations with *different* versions the last write wins (same caveat as getPrompt()).
|
|
56
|
+
*/
|
|
57
|
+
function applyPromptFallback(options) {
|
|
58
|
+
if (options.promptVersion === undefined) {
|
|
59
|
+
return () => { };
|
|
60
|
+
}
|
|
61
|
+
const prev = getLastPrompt();
|
|
62
|
+
setLastPrompt(options.promptVersion, options.promptType ?? prev?.type ?? "system");
|
|
63
|
+
return () => (prev ? setLastPrompt(prev.version, prev.type) : clearLastPrompt());
|
|
64
|
+
}
|
|
65
|
+
export async function coalexContext(options, fn) {
|
|
66
|
+
const tracer = trace.getTracer("coalex");
|
|
67
|
+
const attrs = buildInvocationAttributes(options);
|
|
68
|
+
const restorePrompt = applyPromptFallback(options);
|
|
69
|
+
try {
|
|
70
|
+
return await agentIdStore.run(options.agentId, () => tracer.startActiveSpan("coalex.invocation", { attributes: attrs }, async (span) => {
|
|
71
|
+
try {
|
|
72
|
+
const result = await fn();
|
|
73
|
+
span.setStatus({ code: SpanStatusCode.OK });
|
|
74
|
+
return result;
|
|
75
|
+
}
|
|
76
|
+
catch (e) {
|
|
77
|
+
span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
|
|
78
|
+
span.recordException(e instanceof Error ? e : new Error(String(e)));
|
|
79
|
+
throw e;
|
|
80
|
+
}
|
|
81
|
+
finally {
|
|
82
|
+
span.end();
|
|
83
|
+
}
|
|
84
|
+
}));
|
|
85
|
+
}
|
|
86
|
+
finally {
|
|
87
|
+
restorePrompt();
|
|
88
|
+
}
|
|
54
89
|
}
|
|
55
90
|
export function coalexContextSync(options, fn) {
|
|
56
91
|
const tracer = trace.getTracer("coalex");
|
|
57
|
-
const attrs =
|
|
58
|
-
|
|
59
|
-
|
|
92
|
+
const attrs = buildInvocationAttributes(options);
|
|
93
|
+
const restorePrompt = applyPromptFallback(options);
|
|
94
|
+
try {
|
|
95
|
+
return agentIdStore.run(options.agentId, () => tracer.startActiveSpan("coalex.invocation", { attributes: attrs }, (span) => {
|
|
96
|
+
try {
|
|
97
|
+
const result = fn();
|
|
98
|
+
span.setStatus({ code: SpanStatusCode.OK });
|
|
99
|
+
return result;
|
|
100
|
+
}
|
|
101
|
+
catch (e) {
|
|
102
|
+
span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
|
|
103
|
+
span.recordException(e instanceof Error ? e : new Error(String(e)));
|
|
104
|
+
throw e;
|
|
105
|
+
}
|
|
106
|
+
finally {
|
|
107
|
+
span.end();
|
|
108
|
+
}
|
|
109
|
+
}));
|
|
60
110
|
}
|
|
61
|
-
|
|
62
|
-
|
|
111
|
+
finally {
|
|
112
|
+
restorePrompt();
|
|
63
113
|
}
|
|
64
|
-
return agentIdStore.run(options.agentId, () => tracer.startActiveSpan("coalex.invocation", { attributes: attrs }, (span) => {
|
|
65
|
-
try {
|
|
66
|
-
const result = fn();
|
|
67
|
-
span.setStatus({ code: SpanStatusCode.OK });
|
|
68
|
-
return result;
|
|
69
|
-
}
|
|
70
|
-
catch (e) {
|
|
71
|
-
span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
|
|
72
|
-
span.recordException(e instanceof Error ? e : new Error(String(e)));
|
|
73
|
-
throw e;
|
|
74
|
-
}
|
|
75
|
-
finally {
|
|
76
|
-
span.end();
|
|
77
|
-
}
|
|
78
|
-
}));
|
|
79
114
|
}
|
|
80
115
|
//# sourceMappingURL=context.js.map
|
package/dist/context.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,YAAY,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAErD;;;;;;;GAOG;AACH,IAAI,WAAW,GAA6C,IAAI,CAAC;AAEjE,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,IAAY;IACzD,WAAW,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa;IAC3B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,YAAY,CAAC,QAAQ,EAAE,CAAC;AACjC,CAAC;
|
|
1
|
+
{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
|