orchajs 0.23.12 → 0.25.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 (78) hide show
  1. package/README.md +122 -11
  2. package/dist/amarsia/analytics.js +12 -0
  3. package/dist/amarsia/inference.d.ts +6 -0
  4. package/dist/amarsia/inference.js +337 -0
  5. package/dist/browser.js +5 -0
  6. package/dist/cli-agents-template.d.ts +1 -1
  7. package/dist/cli-agents-template.js +70 -8
  8. package/dist/compiler/build-project.js +78 -15
  9. package/dist/compiler/compile.js +131 -10
  10. package/dist/compiler/node-esm-banner.d.ts +2 -0
  11. package/dist/compiler/node-esm-banner.js +5 -0
  12. package/dist/orcha.js +11 -0
  13. package/dist/project-loader.js +6 -3
  14. package/dist/providers/dependencies.d.ts +1 -0
  15. package/dist/providers/dependencies.js +30 -4
  16. package/dist/providers/types.d.ts +4 -0
  17. package/dist/react-native.js +5 -0
  18. package/dist/runtime/agent.d.ts +2 -0
  19. package/dist/runtime/agent.js +262 -21
  20. package/dist/runtime/compiler-hook.d.ts +4 -0
  21. package/dist/runtime/compiler-hook.js +9 -0
  22. package/dist/runtime/create-orcha.d.ts +19 -0
  23. package/dist/runtime/create-orcha.js +110 -7
  24. package/dist/runtime/mcp/client.d.ts +31 -0
  25. package/dist/runtime/mcp/client.js +106 -0
  26. package/dist/runtime/mcp/http-client.d.ts +6 -0
  27. package/dist/runtime/mcp/http-client.js +87 -0
  28. package/dist/runtime/mcp/node-client.d.ts +3 -0
  29. package/dist/runtime/mcp/node-client.js +60 -0
  30. package/dist/runtime/optional-features.d.ts +19 -0
  31. package/dist/runtime/optional-features.js +22 -0
  32. package/dist/runtime/platform-browser.js +16 -3
  33. package/dist/runtime/platform-node.js +16 -2
  34. package/dist/runtime/platform-react-native.js +16 -3
  35. package/dist/runtime-entry.d.ts +1 -1
  36. package/dist/storage/browser-indexeddb.d.ts +3 -0
  37. package/dist/storage/browser-indexeddb.js +72 -8
  38. package/dist/storage/cloud-outbox.d.ts +30 -0
  39. package/dist/storage/cloud-outbox.js +628 -0
  40. package/dist/storage/cloud.d.ts +1 -0
  41. package/dist/storage/cloud.js +1 -0
  42. package/dist/storage/node-jsonl.d.ts +3 -0
  43. package/dist/storage/node-jsonl.js +273 -4
  44. package/dist/storage/node-sqlite.d.ts +3 -0
  45. package/dist/storage/node-sqlite.js +66 -17
  46. package/dist/storage/react-native-jsonl.d.ts +3 -0
  47. package/dist/storage/react-native-jsonl.js +223 -0
  48. package/dist/testing.js +1 -0
  49. package/dist/types.d.ts +54 -3
  50. package/dist-cjs/amarsia/analytics.js +12 -0
  51. package/dist-cjs/amarsia/inference.js +335 -0
  52. package/dist-cjs/browser.js +5 -0
  53. package/dist-cjs/cli-agents-template.js +70 -8
  54. package/dist-cjs/compiler/build-project.js +92 -4
  55. package/dist-cjs/compiler/compile.js +148 -11
  56. package/dist-cjs/compiler/node-esm-banner.js +32 -0
  57. package/dist-cjs/orcha.js +11 -0
  58. package/dist-cjs/project-loader.js +8 -2
  59. package/dist-cjs/providers/dependencies.js +37 -5
  60. package/dist-cjs/react-native.js +5 -0
  61. package/dist-cjs/runtime/agent.js +327 -37
  62. package/dist-cjs/runtime/compiler-hook.js +11 -0
  63. package/dist-cjs/runtime/create-orcha.js +118 -7
  64. package/dist-cjs/runtime/mcp/client.js +157 -0
  65. package/dist-cjs/runtime/mcp/http-client.js +134 -0
  66. package/dist-cjs/runtime/mcp/node-client.js +95 -0
  67. package/dist-cjs/runtime/optional-features.js +58 -0
  68. package/dist-cjs/runtime/platform-browser.js +16 -3
  69. package/dist-cjs/runtime/platform-node.js +16 -2
  70. package/dist-cjs/runtime/platform-react-native.js +18 -3
  71. package/dist-cjs/storage/browser-indexeddb.js +73 -8
  72. package/dist-cjs/storage/cloud-outbox.js +646 -0
  73. package/dist-cjs/storage/cloud.js +29 -0
  74. package/dist-cjs/storage/node-jsonl.js +246 -3
  75. package/dist-cjs/storage/node-sqlite.js +70 -19
  76. package/dist-cjs/storage/react-native-jsonl.js +207 -0
  77. package/dist-cjs/testing.js +5 -1
  78. package/package.json +13 -3
@@ -16,13 +16,14 @@ export function compileRegistry(registrations, registryRoot, actionRuntime = "na
16
16
  }
17
17
  const normalized = normalizeAgentRegistration(key, registration);
18
18
  const subagents = {};
19
- for (const [subagentKey, registeredPath] of Object.entries(normalized.subagents)) {
19
+ for (const [subagentKey, registration] of Object.entries(normalized.subagents)) {
20
20
  if (!subagentKey.trim()) {
21
21
  throw new Error(`Agent "${key}" has an empty subagent name.`);
22
22
  }
23
- subagents[subagentKey] = compileAgent(subagentKey, registeredPath, registryRoot, actionRuntime, target);
23
+ const subagent = normalizeSubagentRegistration(key, subagentKey, registration);
24
+ subagents[subagentKey] = compileAgent(subagentKey, subagent.path, subagent.mcp, registryRoot, actionRuntime, target);
24
25
  }
25
- const parent = compileAgent(key, normalized.path, registryRoot, actionRuntime, target);
26
+ const parent = compileAgent(key, normalized.path, normalized.mcp, registryRoot, actionRuntime, target);
26
27
  agents[key] = Object.freeze({
27
28
  ...parent,
28
29
  subagentPolicy: Object.keys(subagents).length > 0
@@ -48,7 +49,7 @@ function normalizeAgentRegistration(key, registration) {
48
49
  if (!registration.trim()) {
49
50
  throw new Error(`Agent "${key}" must register a folder path.`);
50
51
  }
51
- return { path: registration, subagents: {} };
52
+ return { path: registration, mcp: {}, subagents: {} };
52
53
  }
53
54
  if (!registration || typeof registration !== "object") {
54
55
  throw new Error(`Agent "${key}" must register a folder path.`);
@@ -60,19 +61,51 @@ function normalizeAgentRegistration(key, registration) {
60
61
  (!registration.subagents ||
61
62
  typeof registration.subagents !== "object" ||
62
63
  Array.isArray(registration.subagents))) {
63
- throw new Error(`Agent "${key}" subagents must be an object of folder paths.`);
64
+ throw new Error(`Agent "${key}" subagents must be an object of named registrations.`);
64
65
  }
65
- for (const [subagentKey, registeredPath] of Object.entries(registration.subagents ?? {})) {
66
- if (typeof registeredPath !== "string" || !registeredPath.trim()) {
67
- throw new Error(`Subagent "${key}/${subagentKey}" must register a folder path.`);
66
+ validateMcpRegistration(`Agent "${key}"`, registration.mcp);
67
+ return {
68
+ path: registration.path,
69
+ mcp: registration.mcp ?? {},
70
+ subagents: registration.subagents ?? {},
71
+ };
72
+ }
73
+ function normalizeSubagentRegistration(parentKey, key, registration) {
74
+ if (typeof registration === "string") {
75
+ if (!registration.trim()) {
76
+ throw new Error(`Subagent "${parentKey}/${key}" must register a folder path.`);
68
77
  }
78
+ return { path: registration, mcp: {} };
79
+ }
80
+ if (!registration ||
81
+ typeof registration !== "object" ||
82
+ typeof registration.path !== "string" ||
83
+ !registration.path.trim()) {
84
+ throw new Error(`Subagent "${parentKey}/${key}" must register a folder path.`);
69
85
  }
86
+ validateMcpRegistration(`Subagent "${parentKey}/${key}"`, registration.mcp);
70
87
  return {
71
88
  path: registration.path,
72
- subagents: registration.subagents ?? {},
89
+ mcp: registration.mcp ?? {},
73
90
  };
74
91
  }
75
- function compileAgent(key, registeredPath, registryRoot, actionRuntime, target) {
92
+ function validateMcpRegistration(owner, registration) {
93
+ if (registration !== undefined &&
94
+ (!registration ||
95
+ typeof registration !== "object" ||
96
+ Array.isArray(registration))) {
97
+ throw new Error(`${owner} mcp must be an object of named folder paths.`);
98
+ }
99
+ for (const [key, path] of Object.entries(registration ?? {})) {
100
+ if (!/^[a-zA-Z0-9_-]{1,32}$/.test(key)) {
101
+ throw new Error(`${owner} has invalid MCP name "${key}".`);
102
+ }
103
+ if (typeof path !== "string" || !path.trim()) {
104
+ throw new Error(`${owner} MCP "${key}" must register a folder path.`);
105
+ }
106
+ }
107
+ }
108
+ function compileAgent(key, registeredPath, mcpRegistration, registryRoot, actionRuntime, target) {
76
109
  const name = key;
77
110
  const sourceDirectory = resolve(registryRoot, registeredPath);
78
111
  const configPath = resolve(sourceDirectory, "index.json");
@@ -151,12 +184,100 @@ function compileAgent(key, registeredPath, registryRoot, actionRuntime, target)
151
184
  actions: compileActions(name, sourceDirectory, actionRuntime, target),
152
185
  skills: compileSkills(name, sourceDirectory),
153
186
  evaluations: compileEvaluations(name, sourceDirectory),
187
+ mcpServers: compileMcpServers(name, mcpRegistration, registryRoot, target),
154
188
  subagentPolicy: configuration.subagents
155
189
  ? Object.freeze({ ...configuration.subagents })
156
190
  : undefined,
157
191
  subagents: Object.freeze({}),
158
192
  });
159
193
  }
194
+ function compileMcpServers(agentName, registration, registryRoot, target) {
195
+ const servers = {};
196
+ for (const [key, registeredPath] of Object.entries(registration)) {
197
+ const directory = resolve(registryRoot, registeredPath);
198
+ const configurationPath = resolve(directory, "index.json");
199
+ let configuration;
200
+ try {
201
+ configuration = JSON.parse(readFileSync(configurationPath, "utf8"));
202
+ }
203
+ catch (error) {
204
+ throw new Error(`MCP server "${agentName}/${key}" is missing a valid index.json at ${configurationPath}.`, { cause: error });
205
+ }
206
+ validateMcpServerConfiguration(agentName, key, configuration, target);
207
+ servers[key] = Object.freeze({
208
+ ...configuration,
209
+ key,
210
+ directoryName: registeredPath,
211
+ });
212
+ }
213
+ return Object.freeze(servers);
214
+ }
215
+ function validateMcpServerConfiguration(agentName, key, configuration, target) {
216
+ const label = `MCP server "${agentName}/${key}"`;
217
+ if (!configuration ||
218
+ typeof configuration !== "object" ||
219
+ !["streamable-http", "stdio"].includes(configuration.transport)) {
220
+ throw new Error(`${label} transport must be "streamable-http" or "stdio".`);
221
+ }
222
+ if (configuration.transport === "streamable-http") {
223
+ let url;
224
+ try {
225
+ url = new URL(configuration.url);
226
+ }
227
+ catch {
228
+ throw new Error(`${label} requires a valid URL.`);
229
+ }
230
+ if (!["https:", "http:"].includes(url.protocol)) {
231
+ throw new Error(`${label} URL must use HTTP or HTTPS.`);
232
+ }
233
+ if (url.protocol === "http:" &&
234
+ !["localhost", "127.0.0.1", "::1"].includes(url.hostname)) {
235
+ throw new Error(`${label} must use HTTPS unless it connects to localhost.`);
236
+ }
237
+ if (configuration.headers !== undefined &&
238
+ (!configuration.headers ||
239
+ typeof configuration.headers !== "object" ||
240
+ Array.isArray(configuration.headers) ||
241
+ Object.values(configuration.headers).some((value) => typeof value !== "string"))) {
242
+ throw new Error(`${label} headers must contain string values.`);
243
+ }
244
+ if (configuration.credentials !== undefined &&
245
+ !["omit", "same-origin", "include"].includes(configuration.credentials)) {
246
+ throw new Error(`${label} has invalid credentials.`);
247
+ }
248
+ }
249
+ else {
250
+ if (target !== "node") {
251
+ throw new Error(`${label} uses stdio, which is only available for the node target.`);
252
+ }
253
+ if (typeof configuration.command !== "string" ||
254
+ !configuration.command.trim()) {
255
+ throw new Error(`${label} requires a command.`);
256
+ }
257
+ if (configuration.args !== undefined &&
258
+ (!Array.isArray(configuration.args) ||
259
+ configuration.args.some((value) => typeof value !== "string"))) {
260
+ throw new Error(`${label} args must be an array of strings.`);
261
+ }
262
+ if (configuration.env !== undefined &&
263
+ (!configuration.env ||
264
+ typeof configuration.env !== "object" ||
265
+ Array.isArray(configuration.env) ||
266
+ Object.values(configuration.env).some((value) => typeof value !== "string"))) {
267
+ throw new Error(`${label} env must contain string values.`);
268
+ }
269
+ }
270
+ validateNumber(label, "timeoutMs", configuration.timeoutMs, {
271
+ integer: true,
272
+ minimum: 1,
273
+ maximum: 300_000,
274
+ });
275
+ validateNumber(label, "maxOutputBytes", configuration.maxOutputBytes, {
276
+ integer: true,
277
+ minimum: 1,
278
+ maximum: 10_000_000,
279
+ });
280
+ }
160
281
  function compileActions(agentName, sourceDirectory, actionRuntime, target) {
161
282
  const actionsDirectory = resolve(sourceDirectory, "actions");
162
283
  if (!existsSync(actionsDirectory)) {
@@ -0,0 +1,2 @@
1
+ /** Lets esbuild's Node ESM output resolve dynamic `require()` of built-ins. */
2
+ export declare const nodeEsmRequireBanner: string;
@@ -0,0 +1,5 @@
1
+ /** Lets esbuild's Node ESM output resolve dynamic `require()` of built-ins. */
2
+ export const nodeEsmRequireBanner = [
3
+ 'import { createRequire as __orchaCreateRequire } from "node:module";',
4
+ "const require = __orchaCreateRequire(import.meta.url);",
5
+ ].join("\n");
package/dist/orcha.js CHANGED
@@ -1,16 +1,27 @@
1
1
  import { existsSync, readFileSync } from "node:fs";
2
2
  import { resolve } from "node:path";
3
+ import { createAmarsiaInferenceGenerator } from "./amarsia/inference.js";
3
4
  import { generateProviderResponse } from "./providers/index.js";
4
5
  import { setNativeRuntimeLoader, setSandboxRuntimeLoader, } from "./runtime/actions/execute.js";
5
6
  import { executeNativeAction } from "./runtime/actions/native.js";
6
7
  import { getRegistryCompiler } from "./runtime/compiler-hook.js";
7
8
  import { createOrcha } from "./runtime/create-orcha.js";
9
+ import { setMcpClientFactory } from "./runtime/mcp/client.js";
10
+ import { setCloudSessionStoreFactory, setInferenceGeneratorFactory, } from "./runtime/optional-features.js";
8
11
  import { nodeRuntimePlatform } from "./runtime/platform-node.js";
12
+ import { CloudSessionStore } from "./storage/cloud.js";
9
13
  setNativeRuntimeLoader(async () => ({ executeNativeAction }));
10
14
  setSandboxRuntimeLoader(async () => {
11
15
  const modulePath = "./runtime/actions/sandbox.js";
12
16
  return import(modulePath);
13
17
  });
18
+ setMcpClientFactory(async (server, credentials) => {
19
+ const modulePath = "./runtime/mcp/node-client.js";
20
+ const { createNodeMcpClient } = await import(modulePath);
21
+ return createNodeMcpClient(server, credentials);
22
+ });
23
+ setInferenceGeneratorFactory(createAmarsiaInferenceGenerator);
24
+ setCloudSessionStoreFactory((options) => new CloudSessionStore(options));
14
25
  export const orcha = createOrcha((configuration) => {
15
26
  const projectRoot = resolve(configuration.root ??
16
27
  process.env.ORCHA_PROJECT_ROOT ??
@@ -6,7 +6,7 @@ import { build as bundleEntry } from "esbuild";
6
6
  import { compileRegistry } from "./compiler/compile.js";
7
7
  import { loadProjectEnvironment } from "./env.js";
8
8
  import { orcha } from "./orcha.js";
9
- import { ensureCompiledProviderDependencies } from "./providers/dependencies.js";
9
+ import { ensureCompiledMcpDependencies, ensureCompiledProviderDependencies, } from "./providers/dependencies.js";
10
10
  import { setRegistryCompiler } from "./runtime/compiler-hook.js";
11
11
  export async function loadProject(projectRoot) {
12
12
  setRegistryCompiler((configuration, compilerProjectRoot) => compileRegistry(configuration.agents, resolve(compilerProjectRoot, "orcha"), configuration.actions?.runtime ?? "native", "node"));
@@ -45,9 +45,12 @@ export async function loadProject(projectRoot) {
45
45
  }
46
46
  if (!orcha.isInitialized() ||
47
47
  orcha.getCompiledBundle() === previousBundle) {
48
- throw new Error('"orcha/index.ts" must call orcha.init({ providers, agents }).');
48
+ throw new Error('"orcha/index.ts" must call orcha.init({ agents, ... }).');
49
49
  }
50
- await ensureCompiledProviderDependencies(orcha.getCompiledBundle(), projectRoot);
50
+ if (!orcha.isInferenceEnabled()) {
51
+ await ensureCompiledProviderDependencies(orcha.getCompiledBundle(), projectRoot);
52
+ }
53
+ await ensureCompiledMcpDependencies(orcha.getCompiledBundle(), projectRoot);
51
54
  }
52
55
  finally {
53
56
  await rm(bundlePath, { force: true });
@@ -1,3 +1,4 @@
1
1
  import type { CompiledBundle } from "../types.js";
2
2
  export declare function ensureCompiledProviderDependencies(bundle: CompiledBundle, projectRoot: string): Promise<void>;
3
3
  export declare function ensureProviderDependencies(providerNames: readonly string[], projectRoot: string): Promise<void>;
4
+ export declare function ensureCompiledMcpDependencies(bundle: CompiledBundle, projectRoot: string): Promise<void>;
@@ -16,6 +16,16 @@ const providerDependencies = {
16
16
  installSpec: "@google/genai@2.22.0",
17
17
  },
18
18
  };
19
+ const mcpDependencies = [
20
+ {
21
+ packageName: "@modelcontextprotocol/sdk",
22
+ installSpec: "@modelcontextprotocol/sdk@1.32.1",
23
+ },
24
+ {
25
+ packageName: "zod",
26
+ installSpec: "zod@3.25.76",
27
+ },
28
+ ];
19
29
  const installations = new Map();
20
30
  export function ensureCompiledProviderDependencies(bundle, projectRoot) {
21
31
  const providers = allCompiledAgents(bundle.agents).flatMap((agent) => [
@@ -40,6 +50,22 @@ export async function ensureProviderDependencies(providerNames, projectRoot) {
40
50
  if (dependencies.length === 0) {
41
51
  return;
42
52
  }
53
+ return ensureDependencies(dependencies, projectRoot, "provider");
54
+ }
55
+ export async function ensureCompiledMcpDependencies(bundle, projectRoot) {
56
+ const hasMcp = allCompiledAgents(bundle.agents).some((agent) => Object.keys(agent.mcpServers ?? {}).length > 0);
57
+ if (!hasMcp) {
58
+ return;
59
+ }
60
+ const declaredPackages = await readDeclaredPackages(projectRoot);
61
+ const missing = mcpDependencies.filter((dependency) => !declaredPackages.has(dependency.packageName) ||
62
+ !isInstalled(dependency.packageName, projectRoot));
63
+ if (missing.length === 0) {
64
+ return;
65
+ }
66
+ return ensureDependencies(missing, projectRoot, "MCP");
67
+ }
68
+ async function ensureDependencies(dependencies, projectRoot, kind) {
43
69
  const key = `${projectRoot}:${dependencies
44
70
  .map((dependency) => dependency.packageName)
45
71
  .sort()
@@ -48,7 +74,7 @@ export async function ensureProviderDependencies(providerNames, projectRoot) {
48
74
  if (existing) {
49
75
  return existing;
50
76
  }
51
- const installation = installProviderDependencies(dependencies, projectRoot).finally(() => installations.delete(key));
77
+ const installation = installDependencies(dependencies, projectRoot, kind).finally(() => installations.delete(key));
52
78
  installations.set(key, installation);
53
79
  return installation;
54
80
  }
@@ -87,13 +113,13 @@ function isInstalled(packageName, projectRoot) {
87
113
  return false;
88
114
  }
89
115
  }
90
- async function installProviderDependencies(dependencies, projectRoot) {
116
+ async function installDependencies(dependencies, projectRoot, kind) {
91
117
  const packageManager = detectPackageManager(projectRoot);
92
118
  const packageNames = dependencies.map((dependency) => dependency.packageName);
93
119
  const command = installCommand(packageManager, dependencies.map((dependency) => dependency.installSpec), false);
94
- console.log(`[orcha] Installing required provider ${packageNames.length === 1 ? "dependency" : "dependencies"} with ${packageManager}: ${packageNames.join(", ")}`);
120
+ console.log(`[orcha] Installing required ${kind} ${packageNames.length === 1 ? "dependency" : "dependencies"} with ${packageManager}: ${packageNames.join(", ")}`);
95
121
  const exitCode = await runPackageManager(command.command, command.arguments, { cwd: projectRoot });
96
122
  if (exitCode !== 0) {
97
- throw new Error(`Failed to install required provider ${packageNames.length === 1 ? "dependency" : "dependencies"}: ${packageNames.join(", ")}`);
123
+ throw new Error(`Failed to install required ${kind} ${packageNames.length === 1 ? "dependency" : "dependencies"}: ${packageNames.join(", ")}`);
98
124
  }
99
125
  }
@@ -54,6 +54,10 @@ export interface ProviderRequest {
54
54
  tools: ProviderToolDefinition[];
55
55
  publishOutput?: (output: string) => void;
56
56
  signal?: AbortSignal;
57
+ trace?: {
58
+ agentExternalId: string;
59
+ sessionId: string;
60
+ };
57
61
  }
58
62
  export type ProviderStopReason = "end_turn" | "tool_call" | "max_tokens" | "content_filter" | "unknown";
59
63
  export interface ProviderResponse {
@@ -1,11 +1,16 @@
1
+ import { createAmarsiaInferenceGenerator } from "./amarsia/inference.js";
1
2
  import { generateBrowserProviderResponse } from "./providers/browser.js";
2
3
  import { setNativeRuntimeLoader } from "./runtime/actions/execute.js";
3
4
  import { createOrcha } from "./runtime/create-orcha.js";
5
+ import { setCloudSessionStoreFactory, setInferenceGeneratorFactory, } from "./runtime/optional-features.js";
4
6
  import { reactNativeRuntimePlatform } from "./runtime/platform-react-native.js";
7
+ import { CloudSessionStore } from "./storage/cloud.js";
5
8
  setNativeRuntimeLoader(async () => {
6
9
  const modulePath = "./runtime/actions/browser-native.js";
7
10
  return import(modulePath);
8
11
  });
12
+ setInferenceGeneratorFactory(createAmarsiaInferenceGenerator);
13
+ setCloudSessionStoreFactory((options) => new CloudSessionStore(options));
9
14
  export const orcha = createOrcha(() => {
10
15
  throw new Error("The React Native runtime requires a precompiled Orcha bundle. Configure the Orcha Metro integration.");
11
16
  }, generateBrowserProviderResponse, reactNativeRuntimePlatform);
@@ -21,6 +21,8 @@ export declare class RuntimeAgent implements AgentRuntime {
21
21
  });
22
22
  get agent(): string;
23
23
  get clientTools(): CompiledActionManifest[];
24
+ /** @internal Releases persistent MCP transports during reinitialization. */
25
+ _close(): Promise<void>;
24
26
  /** @internal Used by the local playground for live trace delivery. */
25
27
  _subscribeSessionEvents(sessionId: string, listener: (events: SessionEvent[]) => void): () => void;
26
28
  /** @internal Used by the local playground for live session indexes. */