agentfootprint 1.9.0 → 1.10.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.
Files changed (13) hide show
  1. package/dist/esm/exportTrace.js +72 -0
  2. package/dist/esm/exportTrace.js.map +1 -0
  3. package/dist/esm/index.js +2 -0
  4. package/dist/esm/index.js.map +1 -1
  5. package/dist/exportTrace.js +76 -0
  6. package/dist/exportTrace.js.map +1 -0
  7. package/dist/index.js +5 -2
  8. package/dist/index.js.map +1 -1
  9. package/dist/types/exportTrace.d.ts +85 -0
  10. package/dist/types/exportTrace.d.ts.map +1 -0
  11. package/dist/types/index.d.ts +2 -0
  12. package/dist/types/index.d.ts.map +1 -1
  13. package/package.json +3 -3
package/dist/esm/exportTrace.js ADDED
@@ -0,0 +1,72 @@
1
+ /**
2
+ * exportTrace — capture an agent run's full state into a portable JSON
3
+ * blob for sharing externally (paste into a viewer, ship to support, log
4
+ * for debugging, store in a database).
5
+ *
6
+ * Defaults to **redacted** output: snapshots come from
7
+ * `getSnapshot({ redact: true })` (footprintjs 4.14+), so values for keys
8
+ * listed in `RedactionPolicy.keys` / matching `patterns` arrive as
9
+ * `'REDACTED'` instead of raw. The commit log is already redacted at
10
+ * write-time. Combined with `emitPatterns` (also redacted at origin), the
11
+ * exported trace is safe to share when the caller has configured a policy.
12
+ *
13
+ * **Without a redaction policy, this helper still emits a trace — but
14
+ * `sharedState` will contain raw values.** Configure `setRedactionPolicy`
15
+ * before calling this for any externally shared trace.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { Agent, exportTrace, anthropic } from 'agentfootprint';
20
+ *
21
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4') })
22
+ * .system('You are a customer support agent.')
23
+ * .build();
24
+ *
25
+ * await agent.run('My credit card 4242-4242-4242-4242 was declined');
26
+ *
27
+ * // Configure policy on the underlying executor for full safety
28
+ * // (concept-level recorder API for this is a follow-up).
29
+ * const trace = exportTrace(agent);
30
+ * console.log(JSON.stringify(trace, null, 2));
31
+ * // → paste into the playground viewer, send to support, etc.
32
+ * ```
33
+ */
34
+ /**
35
+ * Capture a full execution trace from any runner exposing the standard
36
+ * introspection surface (`getSnapshot`, `getNarrative*`, `getSpec`).
37
+ * All of those methods are optional — missing methods skip the field.
38
+ *
39
+ * Always returns a JSON-stringify-safe object.
40
+ */
41
+ export function exportTrace(runner, options) {
42
+ const redact = options?.redact !== false; // default true
43
+ const r = runner;
44
+ // `getSnapshot` may be the older 0-arg form — still safe to call with
45
+ // an arg (JS ignores extras), but keep our intent explicit so older
46
+ // overloads with strict signatures don't trip the type checker.
47
+ let snapshot;
48
+ try {
49
+ snapshot = r.getSnapshot?.({ redact });
50
+ }
51
+ catch {
52
+ // Fall back to the 0-arg form if the runner's signature rejects the
53
+ // options object (older custom runners). Result will be raw — caller
54
+ // is responsible for the safety implication when this happens.
55
+ try {
56
+ snapshot = r.getSnapshot?.();
57
+ }
58
+ catch {
59
+ snapshot = undefined;
60
+ }
61
+ }
62
+ return {
63
+ schemaVersion: 1,
64
+ exportedAt: new Date().toISOString(),
65
+ redacted: redact,
66
+ snapshot,
67
+ narrativeEntries: r.getNarrativeEntries?.(),
68
+ narrative: r.getNarrative?.(),
69
+ spec: r.getSpec?.(),
70
+ };
71
+ }
72
+ //# sourceMappingURL=exportTrace.js.map
package/dist/esm/exportTrace.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"exportTrace.js","sourceRoot":"","sources":["../../src/exportTrace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA4DH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAkB,EAAE,OAA4B;IAC1E,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,eAAe;IACzD,MAAM,CAAC,GAAG,MAA0B,CAAC;IAErC,sEAAsE;IACtE,oEAAoE;IACpE,gEAAgE;IAChE,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,CAAC;YACH,QAAQ,GAAI,CAAC,CAAC,WAA2C,EAAE,EAAE,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,SAAS,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,MAAM;QAChB,QAAQ;QACR,gBAAgB,EAAE,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC3C,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE,EAAE;QAC7B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE;KACpB,CAAC;AACJ,CAAC"}
package/dist/esm/index.js CHANGED
@@ -13,6 +13,8 @@
13
13
  */
14
14
  // ── Concepts (Builders + Runners) ───────────────────────────
15
15
  export { Agent, AgentRunner, LLMCall, LLMCallRunner, RAG, RAGRunner, FlowChart, FlowChartRunner, Swarm, SwarmRunner, Parallel, ParallelRunner, Conditional, ConditionalRunner, } from './concepts';
16
+ // ── Trace export (paste-into-viewer / share-with-support workflow) ─
17
+ export { exportTrace } from './exportTrace';
16
18
  // ── Tools ───────────────────────────────────────────────────
17
19
  export { defineTool, askHuman, ToolRegistry } from './tools';
18
20
  // ── Providers (core — you can't build an agent without these) ─
package/dist/esm/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAQpB,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAuBlF,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAQpB,sEAAsE;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAuBlF,+DAA+D;AAC/D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA0BnC,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGnF,+DAA+D;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
package/dist/exportTrace.js ADDED
@@ -0,0 +1,76 @@
1
+ "use strict";
2
+ /**
3
+ * exportTrace — capture an agent run's full state into a portable JSON
4
+ * blob for sharing externally (paste into a viewer, ship to support, log
5
+ * for debugging, store in a database).
6
+ *
7
+ * Defaults to **redacted** output: snapshots come from
8
+ * `getSnapshot({ redact: true })` (footprintjs 4.14+), so values for keys
9
+ * listed in `RedactionPolicy.keys` / matching `patterns` arrive as
10
+ * `'REDACTED'` instead of raw. The commit log is already redacted at
11
+ * write-time. Combined with `emitPatterns` (also redacted at origin), the
12
+ * exported trace is safe to share when the caller has configured a policy.
13
+ *
14
+ * **Without a redaction policy, this helper still emits a trace — but
15
+ * `sharedState` will contain raw values.** Configure `setRedactionPolicy`
16
+ * before calling this for any externally shared trace.
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * import { Agent, exportTrace, anthropic } from 'agentfootprint';
21
+ *
22
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4') })
23
+ * .system('You are a customer support agent.')
24
+ * .build();
25
+ *
26
+ * await agent.run('My credit card 4242-4242-4242-4242 was declined');
27
+ *
28
+ * // Configure policy on the underlying executor for full safety
29
+ * // (concept-level recorder API for this is a follow-up).
30
+ * const trace = exportTrace(agent);
31
+ * console.log(JSON.stringify(trace, null, 2));
32
+ * // → paste into the playground viewer, send to support, etc.
33
+ * ```
34
+ */
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.exportTrace = void 0;
37
+ /**
38
+ * Capture a full execution trace from any runner exposing the standard
39
+ * introspection surface (`getSnapshot`, `getNarrative*`, `getSpec`).
40
+ * All of those methods are optional — missing methods skip the field.
41
+ *
42
+ * Always returns a JSON-stringify-safe object.
43
+ */
44
+ function exportTrace(runner, options) {
45
+ const redact = options?.redact !== false; // default true
46
+ const r = runner;
47
+ // `getSnapshot` may be the older 0-arg form — still safe to call with
48
+ // an arg (JS ignores extras), but keep our intent explicit so older
49
+ // overloads with strict signatures don't trip the type checker.
50
+ let snapshot;
51
+ try {
52
+ snapshot = r.getSnapshot?.({ redact });
53
+ }
54
+ catch {
55
+ // Fall back to the 0-arg form if the runner's signature rejects the
56
+ // options object (older custom runners). Result will be raw — caller
57
+ // is responsible for the safety implication when this happens.
58
+ try {
59
+ snapshot = r.getSnapshot?.();
60
+ }
61
+ catch {
62
+ snapshot = undefined;
63
+ }
64
+ }
65
+ return {
66
+ schemaVersion: 1,
67
+ exportedAt: new Date().toISOString(),
68
+ redacted: redact,
69
+ snapshot,
70
+ narrativeEntries: r.getNarrativeEntries?.(),
71
+ narrative: r.getNarrative?.(),
72
+ spec: r.getSpec?.(),
73
+ };
74
+ }
75
+ exports.exportTrace = exportTrace;
76
+ //# sourceMappingURL=exportTrace.js.map
package/dist/exportTrace.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"exportTrace.js","sourceRoot":"","sources":["../src/exportTrace.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AA4DH;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,MAAkB,EAAE,OAA4B;IAC1E,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,eAAe;IACzD,MAAM,CAAC,GAAG,MAA0B,CAAC;IAErC,sEAAsE;IACtE,oEAAoE;IACpE,gEAAgE;IAChE,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,CAAC;YACH,QAAQ,GAAI,CAAC,CAAC,WAA2C,EAAE,EAAE,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,SAAS,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,QAAQ,EAAE,MAAM;QAChB,QAAQ;QACR,gBAAgB,EAAE,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC3C,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE,EAAE;QAC7B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE;KACpB,CAAC;AACJ,CAAC;AA9BD,kCA8BC"}
package/dist/index.js CHANGED
@@ -13,8 +13,8 @@
13
13
  * agentfootprint/stream → Real-time lifecycle events
14
14
  */
15
15
  Object.defineProperty(exports, "__esModule", { value: true });
16
- exports.ToolUsageRecorder = exports.TokenRecorder = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.postgresStore = exports.dynamoStore = exports.redisStore = exports.InMemoryStore = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
17
- exports.CostRecorder = exports.TurnRecorder = void 0;
16
+ exports.TokenRecorder = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.postgresStore = exports.dynamoStore = exports.redisStore = exports.InMemoryStore = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.exportTrace = exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
17
+ exports.CostRecorder = exports.TurnRecorder = exports.ToolUsageRecorder = void 0;
18
18
  // ── Concepts (Builders + Runners) ───────────────────────────
19
19
  var concepts_1 = require("./concepts");
20
20
  Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return concepts_1.Agent; } });
@@ -31,6 +31,9 @@ Object.defineProperty(exports, "Parallel", { enumerable: true, get: function ()
31
31
  Object.defineProperty(exports, "ParallelRunner", { enumerable: true, get: function () { return concepts_1.ParallelRunner; } });
32
32
  Object.defineProperty(exports, "Conditional", { enumerable: true, get: function () { return concepts_1.Conditional; } });
33
33
  Object.defineProperty(exports, "ConditionalRunner", { enumerable: true, get: function () { return concepts_1.ConditionalRunner; } });
34
+ // ── Trace export (paste-into-viewer / share-with-support workflow) ─
35
+ var exportTrace_1 = require("./exportTrace");
36
+ Object.defineProperty(exports, "exportTrace", { enumerable: true, get: function () { return exportTrace_1.exportTrace; } });
34
37
  // ── Tools ───────────────────────────────────────────────────
35
38
  var tools_1 = require("./tools");
36
39
  Object.defineProperty(exports, "defineTool", { enumerable: true, get: function () { return tools_1.defineTool; } });
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;AAEH,+DAA+D;AAC/D,uCAeoB;AAdlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AASnB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AACtD,uDAA2D;AAAlD,yGAAA,aAAa,OAAA;AACtB,mDAAkF;AAAzE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAuB/C,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;AAEH,+DAA+D;AAC/D,uCAeoB;AAdlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AASnB,sEAAsE;AACtE,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AAGpB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AACtD,uDAA2D;AAAlD,yGAAA,aAAa,OAAA;AACtB,mDAAkF;AAAzE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAuB/C,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}
package/dist/types/exportTrace.d.ts ADDED
@@ -0,0 +1,85 @@
1
+ /**
2
+ * exportTrace — capture an agent run's full state into a portable JSON
3
+ * blob for sharing externally (paste into a viewer, ship to support, log
4
+ * for debugging, store in a database).
5
+ *
6
+ * Defaults to **redacted** output: snapshots come from
7
+ * `getSnapshot({ redact: true })` (footprintjs 4.14+), so values for keys
8
+ * listed in `RedactionPolicy.keys` / matching `patterns` arrive as
9
+ * `'REDACTED'` instead of raw. The commit log is already redacted at
10
+ * write-time. Combined with `emitPatterns` (also redacted at origin), the
11
+ * exported trace is safe to share when the caller has configured a policy.
12
+ *
13
+ * **Without a redaction policy, this helper still emits a trace — but
14
+ * `sharedState` will contain raw values.** Configure `setRedactionPolicy`
15
+ * before calling this for any externally shared trace.
16
+ *
17
+ * @example
18
+ * ```ts
19
+ * import { Agent, exportTrace, anthropic } from 'agentfootprint';
20
+ *
21
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4') })
22
+ * .system('You are a customer support agent.')
23
+ * .build();
24
+ *
25
+ * await agent.run('My credit card 4242-4242-4242-4242 was declined');
26
+ *
27
+ * // Configure policy on the underlying executor for full safety
28
+ * // (concept-level recorder API for this is a follow-up).
29
+ * const trace = exportTrace(agent);
30
+ * console.log(JSON.stringify(trace, null, 2));
31
+ * // → paste into the playground viewer, send to support, etc.
32
+ * ```
33
+ */
34
+ import type { RunnerLike } from './types';
35
+ /**
36
+ * Schema-versioned, JSON-safe representation of a single agent run.
37
+ *
38
+ * Pin the consumer side to `schemaVersion: 1`. Any breaking change to the
39
+ * shape ships as a new schema version with a clear migration note.
40
+ */
41
+ export interface AgentfootprintTrace {
42
+ /** Schema version. Always `1` in this release. */
43
+ readonly schemaVersion: 1;
44
+ /** ISO 8601 timestamp the trace was exported. */
45
+ readonly exportedAt: string;
46
+ /** True when `sharedState` came from the redacted mirror. */
47
+ readonly redacted: boolean;
48
+ /**
49
+ * Full execution snapshot — `sharedState`, `executionTree`, `commitLog`,
50
+ * `subflowResults`, and any recorder snapshots. The exact shape matches
51
+ * `footprintjs.RuntimeSnapshot`. May be omitted if the runner did not
52
+ * expose `getSnapshot()`.
53
+ */
54
+ readonly snapshot?: unknown;
55
+ /**
56
+ * Structured per-step narrative entries. Use this to render a timeline
57
+ * UI; each entry has a `type`, `text`, `depth`, and `runtimeStageId`.
58
+ */
59
+ readonly narrativeEntries?: unknown[];
60
+ /** Flat string-list narrative — convenience view for logs / chat UIs. */
61
+ readonly narrative?: string[];
62
+ /**
63
+ * Flowchart spec — node + edge metadata for rendering the topology of
64
+ * what ran. Stable across runs of the same agent shape.
65
+ */
66
+ readonly spec?: unknown;
67
+ }
68
+ export interface ExportTraceOptions {
69
+ /**
70
+ * When `true` (the default), request `getSnapshot({ redact: true })` from
71
+ * the runner so `sharedState` is scrubbed via the redacted-mirror feature.
72
+ * Set to `false` only for in-process debugging where the raw view is
73
+ * needed and the trace will not leave the local machine.
74
+ */
75
+ readonly redact?: boolean;
76
+ }
77
+ /**
78
+ * Capture a full execution trace from any runner exposing the standard
79
+ * introspection surface (`getSnapshot`, `getNarrative*`, `getSpec`).
80
+ * All of those methods are optional — missing methods skip the field.
81
+ *
82
+ * Always returns a JSON-stringify-safe object.
83
+ */
84
+ export declare function exportTrace(runner: RunnerLike, options?: ExportTraceOptions): AgentfootprintTrace;
85
+ //# sourceMappingURL=exportTrace.d.ts.map
package/dist/types/exportTrace.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"exportTrace.d.ts","sourceRoot":"","sources":["../../src/exportTrace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC;IACtC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAcD,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,mBAAmB,CA8BjG"}
package/dist/types/index.d.ts CHANGED
@@ -13,6 +13,8 @@
13
13
  */
14
14
  export { Agent, AgentRunner, LLMCall, LLMCallRunner, RAG, RAGRunner, FlowChart, FlowChartRunner, Swarm, SwarmRunner, Parallel, ParallelRunner, Conditional, ConditionalRunner, } from './concepts';
15
15
  export type { CustomRouteBranch, CustomRouteConfig, ConditionalOptions, ConditionalPredicate, } from './concepts';
16
+ export { exportTrace } from './exportTrace';
17
+ export type { AgentfootprintTrace, ExportTraceOptions } from './exportTrace';
16
18
  export { defineTool, askHuman, ToolRegistry } from './tools';
17
19
  export { mock, MockAdapter, mockRetriever, MockRetriever, createProvider } from './adapters';
18
20
  export { anthropic, openai, ollama, bedrock } from './models';
package/dist/types/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,aAAa,GACd,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,YAAY,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EACX,WAAW,EACX,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACnF,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAGxF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,KAAK,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,GAAG,EACH,SAAS,EACT,SAAS,EACT,eAAe,EACf,KAAK,EACL,WAAW,EACX,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAG7E,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,aAAa,GACd,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC/E,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9D,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGnC,YAAY,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EACX,WAAW,EACX,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACnF,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAGxF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentfootprint",
3
- "version": "1.9.0",
3
+ "version": "1.10.0",
4
4
  "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
5
5
  "license": "MIT",
6
6
  "author": "Sanjay Krishna Anbalagan",
@@ -154,7 +154,7 @@
154
154
  },
155
155
  "sideEffects": false,
156
156
  "peerDependencies": {
157
- "footprintjs": ">=4.13.0",
157
+ "footprintjs": ">=4.14.0",
158
158
  "@anthropic-ai/sdk": ">=0.30.0",
159
159
  "@aws-sdk/client-bedrock-runtime": ">=3.0.0",
160
160
  "openai": ">=4.0.0"
@@ -176,7 +176,7 @@
176
176
  "@typescript-eslint/parser": "^5.61.0",
177
177
  "eslint": "^8.44.0",
178
178
  "eslint-config-prettier": "^6.15.0",
179
- "footprintjs": "^4.13.0",
179
+ "footprintjs": "^4.14.0",
180
180
  "prettier": "^2.8.1",
181
181
  "typescript": "~5.4.5",
182
182
  "vitest": "^4.0.18",