@deepagents/devtool 0.0.0-stage → 7.0.1

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# `@deepagents/devtool`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Development-only Zukhruf DevTool UI. `devtool()` returns a mountable Hono app
+containing only the bundled browser assets and their SPA fallback; consumers do
+not import React or CSS, and the DevTool owns no listener, port, runtime
+object, credentials, or proxy.
+
+```sh
+npm install --save-dev @deepagents/devtool
+```
+
+The host owns one Hono server and chooses each plugin's mount. This example
+chooses `/zukhruf/v1` for the authenticated HTTP plugin and `/devtool` for the
+UI:
+
+```ts
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+
+import { devtool } from '@deepagents/devtool';
+import { fileTelemetry, tracesHttp } from '@deepagents/devtool/traces';
+import { AgentRuntime, defineAgent } from '@deepagents/experimental/zukhruf';
+import { type HttpEnv, http } from '@deepagents/experimental/zukhruf/http';
+
+const traceTelemetry = fileTelemetry({ path: './telemetry.jsonl' });
+const runtime = new AgentRuntime(
+  defineAgent({
+    ...declaration,
+    plugins: [...declaration.plugins, traceTelemetry],
+  }),
+);
+await using host = await runtime.initialize(runtimeOptions);
+await using worker = await host.work();
+
+const app = new Hono<HttpEnv>();
+app.use('/zukhruf/v1/*', (context, next) => {
+  context.set('userId', 'demo');
+  return next();
+});
+app.route('/zukhruf/v1', http(host, tracesHttp(traceTelemetry)));
+app.route('/devtool', devtool({ protocolPath: '/zukhruf/v1' }));
+
+await using server = serve({
+  fetch: app.fetch,
+  hostname: '127.0.0.1',
+  port: 4317,
+});
+console.info('http://127.0.0.1:4317/devtool');
+```
+
+`http(host)` uses Hono's effective mount to produce discovery links. For the
+example mount, `GET /zukhruf/v1/info` returns:
+
+```json
+{
+  "capabilities": {
+    "history": { "href": "/zukhruf/v1/history" },
+    "chat": { "href": "/zukhruf/v1/session" },
+    "events": { "href": "/zukhruf/v1/events" },
+    "traces": { "href": "/zukhruf/v1/traces" }
+  }
+}
+```
+
+`history`, `chat`, and `events` are always advertised by `http(host)`. **New Chat**,
+conversation loading, streaming, and cancellation use the session protocol on
+the current origin, so the host's own authentication middleware guards every
+runtime request. The owner event stream keeps conversation status and child
+progress current without browser polling. Runtime health comes from
+`GET /zukhruf/v1/health`.
+
+`traces` appears only when the runtime installs the `fileTelemetry()` plugin
+from `@deepagents/devtool/traces` and the host passes
+`tracesHttp(traceTelemetry)` from the same subpath to `http()`.
+The plugin instance contributes the AI SDK OpenTelemetry integration and a
+transport-neutral trace reader; the definition-bound HTTP projection adds the
+runtime's authenticated trace routes and discovery entry. Together they
+correlate the conversation, stream, and agent identifiers on each turn, project
+the Halo-compatible JSONL in place inside the runtime process, and serve
+`GET /zukhruf/v1/traces/:chatId` and `GET /zukhruf/v1/traces/:chatId/:traceId`
+behind the Zukhruf authentication boundary. Ownership comes from the
+authenticated `userId`; the file URI is never exposed and the browser never
+sends a user ID. Without the plugin, `/info` omits `traces` and the UI hides
+every **Traces** link. Recording controls are honored and disabled payloads are
+labelled as not recorded.
+
+`schedules` appears only when the runtime installs `schedules()` and the host
+passes `schedulesHttp(scheduled)` from
+`@deepagents/experimental/zukhruf/schedules/http` to `http()`. The authenticated
+projection provides task creation and editing, pause/resume, archive/purge, Run
+now, per-task runs, cancellation, explicit review, and the owner-wide
+pending-review inbox. Omitting the projection removes the discovery capability
+and hides **Scheduled** navigation.
+
+The UI follows both host-selected Hono mounts. `devtool({ protocolPath })`
+injects its effective UI mount as the document base and the same-origin absolute
+protocol path as the discovery target. `protocolPath` defaults to
+`/zukhruf/v1`. Assets, React Router, deep links, refresh, and Back therefore work
+beneath any UI path while runtime requests follow the configured protocol mount.
+For this example, `/devtool` and `/devtool/` load the shell, assets load beneath
+`/devtool/assets/`, and `/devtool` redirects to `/devtool/history`.

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Static DevTool UI. Mount with `app.route(path, devtool({ protocolPath }))` on
+ * the same origin that mounts `http(runtime)` at `protocolPath`.
+ */
+export declare function devtool({ protocolPath, }?: {
+    protocolPath?: string;
+}): import("hono/hono-base").HonoBase<{}, {
+    "/assets/*": {
+        $get: {
+            input: {};
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+} & {
+    "*": {
+        $get: {
+            input: {};
+            output: {};
+            outputFormat: string;
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+}, "/", "*">;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,wBAAgB,OAAO,CAAC,EACtB,YAA4B,GAC7B,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO;;;;;;;;;;;;;;;;;;aAgChC"}

package/dist/index.js

@@ -0,0 +1,44 @@
+// packages/devtool/host/src/index.ts
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import { html } from "hono/html";
+import { basePath } from "hono/route";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+var ui = fileURLToPath(new URL("./ui/", import.meta.url));
+var shell = await readFile(
+  new URL("./ui/index.html", import.meta.url),
+  "utf8"
+);
+function devtool({
+  protocolPath = "/zukhruf/v1"
+} = {}) {
+  const parsed = new URL(protocolPath, "http://localhost");
+  if (parsed.origin !== "http://localhost" || parsed.pathname !== protocolPath) {
+    throw new TypeError(
+      "devtool: protocolPath must be a same-origin absolute path"
+    );
+  }
+  const infoPath = `${protocolPath.replace(/\/+$/, "")}/info`;
+  return new Hono().use(
+    "/assets/*",
+    serveStatic({
+      root: ui,
+      rewriteRequestPath: (path, context) => path.slice(basePath(context).replace(/\/$/, "").length)
+    })
+  ).get("/assets/*", (context) => context.notFound()).get("*", async (context) => {
+    const mount = basePath(context).replace(/\/$/, "");
+    const base = await html`<base href="${mount}/" />`;
+    const configuration = await html`<meta
+        name="deepagents-zukhruf-info"
+        content="${infoPath}"
+      />`;
+    return context.html(
+      shell.replace("<head>", `<head>${base}${configuration}`)
+    );
+  });
+}
+export {
+  devtool
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["import { serveStatic } from '@hono/node-server/serve-static';\nimport { Hono } from 'hono';\nimport { html } from 'hono/html';\nimport { basePath } from 'hono/route';\nimport { readFile } from 'node:fs/promises';\nimport { fileURLToPath } from 'node:url';\n\nconst ui = fileURLToPath(new URL('./ui/', import.meta.url));\nconst shell = await readFile(\n  new URL('./ui/index.html', import.meta.url),\n  'utf8',\n);\n\n/**\n * Static DevTool UI. Mount with `app.route(path, devtool({ protocolPath }))` on\n * the same origin that mounts `http(runtime)` at `protocolPath`.\n */\nexport function devtool({\n  protocolPath = '/zukhruf/v1',\n}: { protocolPath?: string } = {}) {\n  const parsed = new URL(protocolPath, 'http://localhost');\n  if (\n    parsed.origin !== 'http://localhost' ||\n    parsed.pathname !== protocolPath\n  ) {\n    throw new TypeError(\n      'devtool: protocolPath must be a same-origin absolute path',\n    );\n  }\n  const infoPath = `${protocolPath.replace(/\\/+$/, '')}/info`;\n  return new Hono()\n    .use(\n      '/assets/*',\n      serveStatic({\n        root: ui,\n        rewriteRequestPath: (path, context) =>\n          path.slice(basePath(context).replace(/\\/$/, '').length),\n      }),\n    )\n    .get('/assets/*', (context) => context.notFound())\n    .get('*', async (context) => {\n      const mount = basePath(context).replace(/\\/$/, '');\n      const base = await html`<base href=\"${mount}/\" />`;\n      const configuration = await html`<meta\n        name=\"deepagents-zukhruf-info\"\n        content=\"${infoPath}\"\n      />`;\n      return context.html(\n        shell.replace('<head>', `<head>${base}${configuration}`),\n      );\n    });\n}\n"],
+  "mappings": ";AAAA,SAAS,mBAAmB;AAC5B,SAAS,YAAY;AACrB,SAAS,YAAY;AACrB,SAAS,gBAAgB;AACzB,SAAS,gBAAgB;AACzB,SAAS,qBAAqB;AAE9B,IAAM,KAAK,cAAc,IAAI,IAAI,SAAS,YAAY,GAAG,CAAC;AAC1D,IAAM,QAAQ,MAAM;AAAA,EAClB,IAAI,IAAI,mBAAmB,YAAY,GAAG;AAAA,EAC1C;AACF;AAMO,SAAS,QAAQ;AAAA,EACtB,eAAe;AACjB,IAA+B,CAAC,GAAG;AACjC,QAAM,SAAS,IAAI,IAAI,cAAc,kBAAkB;AACvD,MACE,OAAO,WAAW,sBAClB,OAAO,aAAa,cACpB;AACA,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,QAAM,WAAW,GAAG,aAAa,QAAQ,QAAQ,EAAE,CAAC;AACpD,SAAO,IAAI,KAAK,EACb;AAAA,IACC;AAAA,IACA,YAAY;AAAA,MACV,MAAM;AAAA,MACN,oBAAoB,CAAC,MAAM,YACzB,KAAK,MAAM,SAAS,OAAO,EAAE,QAAQ,OAAO,EAAE,EAAE,MAAM;AAAA,IAC1D,CAAC;AAAA,EACH,EACC,IAAI,aAAa,CAAC,YAAY,QAAQ,SAAS,CAAC,EAChD,IAAI,KAAK,OAAO,YAAY;AAC3B,UAAM,QAAQ,SAAS,OAAO,EAAE,QAAQ,OAAO,EAAE;AACjD,UAAM,OAAO,MAAM,mBAAmB,KAAK;AAC3C,UAAM,gBAAgB,MAAM;AAAA;AAAA,mBAEf,QAAQ;AAAA;AAErB,WAAO,QAAQ;AAAA,MACb,MAAM,QAAQ,UAAU,SAAS,IAAI,GAAG,aAAa,EAAE;AAAA,IACzD;AAAA,EACF,CAAC;AACL;",
+  "names": []
+}

package/dist/traces/file-trace-adapter.d.ts

@@ -0,0 +1,53 @@
+import type { ConversationId } from '@deepagents/experimental/zukhruf';
+export type RecordingState = 'recorded' | 'not-recorded';
+export interface AgentTraceSummary {
+    id: string;
+    chatId: string;
+    userId: string;
+    streamId: string;
+    agentName: string;
+    agentPath: string;
+    workflowName: string;
+    startedAt: string | null;
+    endedAt: string | null;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    stepCount: number;
+    finishReason: string | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    recording: {
+        inputs: RecordingState;
+        outputs: RecordingState;
+    };
+}
+export interface AgentTraceSpan {
+    id: string;
+    traceId: string;
+    parentId: string | null;
+    startedAt: string;
+    endedAt: string | null;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    type: string;
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    usage?: unknown;
+    error?: unknown;
+    data: Record<string, unknown>;
+}
+export type AgentTrace = AgentTraceSummary & {
+    spans: AgentTraceSpan[];
+};
+export interface AgentTraceReader {
+    list(conversation: ConversationId): Promise<AgentTraceSummary[]>;
+    get(conversation: ConversationId, traceId: string): Promise<AgentTrace | undefined>;
+}
+export declare class FileTraceAdapter implements AgentTraceReader {
+    #private;
+    constructor(path: URL);
+    list({ chatId, userId }: ConversationId): Promise<AgentTraceSummary[]>;
+    get({ chatId, userId }: ConversationId, traceId: string): Promise<AgentTrace | undefined>;
+}
+//# sourceMappingURL=file-trace-adapter.d.ts.map

package/dist/traces/file-trace-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-trace-adapter.d.ts","sourceRoot":"","sources":["../../src/traces/file-trace-adapter.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAUvE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,cAAc,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,SAAS,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,CAAC;CAChE;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG;IAAE,KAAK,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,YAAY,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACjE,GAAG,CACD,YAAY,EAAE,cAAc,EAC5B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;CACpC;AAeD,qBAAa,gBAAiB,YAAW,gBAAgB;;gBAG3C,IAAI,EAAE,GAAG;IAIf,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAStE,GAAG,CACP,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,cAAc,EAClC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;CAgBnC"}

package/dist/traces/http.d.ts

@@ -0,0 +1,4 @@
+import type { AgentPluginDefinition } from '@deepagents/experimental/zukhruf';
+import type { FileTelemetryInstance } from './index.ts';
+export declare function tracesHttp(definition: AgentPluginDefinition<FileTelemetryInstance>): import("@deepagents/experimental/zukhruf/http").HttpProjection;
+//# sourceMappingURL=http.d.ts.map

package/dist/traces/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/traces/http.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,kCAAkC,CAAC;AAW1C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKxD,wBAAgB,UAAU,CACxB,UAAU,EAAE,qBAAqB,CAAC,qBAAqB,CAAC,kEAMzD"}

package/dist/traces/index.d.ts

@@ -0,0 +1,11 @@
+import type { FileTelemetryOptions } from '@deepagents/context/telemetry/file';
+import type { AgentPluginDefinition } from '@deepagents/experimental/zukhruf';
+import type { AgentTraceReader } from './file-trace-adapter.ts';
+export * from './file-trace-adapter.ts';
+export { tracesHttp } from './http.ts';
+export interface FileTelemetryInstance {
+    readonly traces: AgentTraceReader;
+}
+/** AI SDK OpenTelemetry spans persisted in Halo's flat JSONL format. */
+export declare function fileTelemetry(options: FileTelemetryOptions): AgentPluginDefinition<FileTelemetryInstance>;
+//# sourceMappingURL=index.d.ts.map

package/dist/traces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/traces/index.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAcvC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,GAC5B,qBAAqB,CAAC,qBAAqB,CAAC,CA2B9C"}