@chatu-ai/builder-sdk 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,360 @@
+/**
+ * Builder 事件 schema —— 单一事实源（003.技术方案/03 §2 的代码化）
+ * 服务端 C# 侧使用由此导出的 JSON Schema 做对偶校验。
+ * seq 作用域：单个 xid（任务）内单调递增（评审记录 R1）。
+ */
+import { z } from 'zod';
+export declare const SandboxState: z.ZodEnum<["requested", "creating", "warming", "ready", "busy", "snapshotting", "hibernated", "resuming", "recycled", "failed"]>;
+export type SandboxState = z.infer<typeof SandboxState>;
+/** 流前确认事件（服务端自产，固定 seq=0，不参与去重排序——R17） */
+export declare const AckEvent: z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"ack">;
+    sandbox: z.ZodObject<{
+        sandboxId: z.ZodString;
+        state: z.ZodEnum<["requested", "creating", "warming", "ready", "busy", "snapshotting", "hibernated", "resuming", "recycled", "failed"]>;
+        previewUrl: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    }, {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "ack";
+    sandbox: {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    };
+}, {
+    xid: string;
+    seq: number;
+    kind: "ack";
+    sandbox: {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    };
+}>;
+export declare const MessageEvent: z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"message">;
+    role: z.ZodEnum<["assistant", "system"]>;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "message";
+    role: "assistant" | "system";
+    text: string;
+}, {
+    xid: string;
+    seq: number;
+    kind: "message";
+    role: "assistant" | "system";
+    text: string;
+}>;
+export declare const TaskCardEvent: z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"taskCard">;
+    id: z.ZodString;
+    label: z.ZodString;
+    state: z.ZodEnum<["running", "done", "failed"]>;
+    detail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "taskCard";
+    state: "failed" | "running" | "done";
+    id: string;
+    label: string;
+    detail?: string | undefined;
+}, {
+    xid: string;
+    seq: number;
+    kind: "taskCard";
+    state: "failed" | "running" | "done";
+    id: string;
+    label: string;
+    detail?: string | undefined;
+}>;
+export declare const FileDiffEvent: z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"fileDiff">;
+    path: z.ZodString;
+    action: z.ZodEnum<["create", "modify", "delete"]>;
+    diff: z.ZodOptional<z.ZodString>;
+    bytes: z.ZodNumber;
+    truncated: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    xid: string;
+    seq: number;
+    kind: "fileDiff";
+    action: "create" | "modify" | "delete";
+    bytes: number;
+    truncated: boolean;
+    diff?: string | undefined;
+}, {
+    path: string;
+    xid: string;
+    seq: number;
+    kind: "fileDiff";
+    action: "create" | "modify" | "delete";
+    bytes: number;
+    diff?: string | undefined;
+    truncated?: boolean | undefined;
+}>;
+export declare const PreviewEvent: z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"preview">;
+    state: z.ZodEnum<["starting", "ready", "crashed"]>;
+    url: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "preview";
+    state: "ready" | "starting" | "crashed";
+    url?: string | undefined;
+    error?: string | null | undefined;
+}, {
+    xid: string;
+    seq: number;
+    kind: "preview";
+    state: "ready" | "starting" | "crashed";
+    url?: string | undefined;
+    error?: string | null | undefined;
+}>;
+export declare const VersionEvent: z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"version">;
+    sha: z.ZodString;
+    message: z.ZodString;
+    filesChanged: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    xid: string;
+    seq: number;
+    kind: "version";
+    sha: string;
+    filesChanged: number;
+}, {
+    message: string;
+    xid: string;
+    seq: number;
+    kind: "version";
+    sha: string;
+    filesChanged: number;
+}>;
+export declare const DoneEvent: z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"done">;
+    state: z.ZodEnum<["completed", "failed", "canceled"]>;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "done";
+    state: "failed" | "completed" | "canceled";
+    error?: string | undefined;
+}, {
+    xid: string;
+    seq: number;
+    kind: "done";
+    state: "failed" | "completed" | "canceled";
+    error?: string | undefined;
+}>;
+export declare const BuilderEvent: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"ack">;
+    sandbox: z.ZodObject<{
+        sandboxId: z.ZodString;
+        state: z.ZodEnum<["requested", "creating", "warming", "ready", "busy", "snapshotting", "hibernated", "resuming", "recycled", "failed"]>;
+        previewUrl: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    }, {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "ack";
+    sandbox: {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    };
+}, {
+    xid: string;
+    seq: number;
+    kind: "ack";
+    sandbox: {
+        sandboxId: string;
+        state: "requested" | "creating" | "warming" | "ready" | "busy" | "snapshotting" | "hibernated" | "resuming" | "recycled" | "failed";
+        previewUrl?: string | undefined;
+    };
+}>, z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"message">;
+    role: z.ZodEnum<["assistant", "system"]>;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "message";
+    role: "assistant" | "system";
+    text: string;
+}, {
+    xid: string;
+    seq: number;
+    kind: "message";
+    role: "assistant" | "system";
+    text: string;
+}>, z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"taskCard">;
+    id: z.ZodString;
+    label: z.ZodString;
+    state: z.ZodEnum<["running", "done", "failed"]>;
+    detail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "taskCard";
+    state: "failed" | "running" | "done";
+    id: string;
+    label: string;
+    detail?: string | undefined;
+}, {
+    xid: string;
+    seq: number;
+    kind: "taskCard";
+    state: "failed" | "running" | "done";
+    id: string;
+    label: string;
+    detail?: string | undefined;
+}>, z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"fileDiff">;
+    path: z.ZodString;
+    action: z.ZodEnum<["create", "modify", "delete"]>;
+    diff: z.ZodOptional<z.ZodString>;
+    bytes: z.ZodNumber;
+    truncated: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    xid: string;
+    seq: number;
+    kind: "fileDiff";
+    action: "create" | "modify" | "delete";
+    bytes: number;
+    truncated: boolean;
+    diff?: string | undefined;
+}, {
+    path: string;
+    xid: string;
+    seq: number;
+    kind: "fileDiff";
+    action: "create" | "modify" | "delete";
+    bytes: number;
+    diff?: string | undefined;
+    truncated?: boolean | undefined;
+}>, z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"preview">;
+    state: z.ZodEnum<["starting", "ready", "crashed"]>;
+    url: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "preview";
+    state: "ready" | "starting" | "crashed";
+    url?: string | undefined;
+    error?: string | null | undefined;
+}, {
+    xid: string;
+    seq: number;
+    kind: "preview";
+    state: "ready" | "starting" | "crashed";
+    url?: string | undefined;
+    error?: string | null | undefined;
+}>, z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"version">;
+    sha: z.ZodString;
+    message: z.ZodString;
+    filesChanged: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    xid: string;
+    seq: number;
+    kind: "version";
+    sha: string;
+    filesChanged: number;
+}, {
+    message: string;
+    xid: string;
+    seq: number;
+    kind: "version";
+    sha: string;
+    filesChanged: number;
+}>, z.ZodObject<{
+    xid: z.ZodString;
+    seq: z.ZodNumber;
+} & {
+    kind: z.ZodLiteral<"done">;
+    state: z.ZodEnum<["completed", "failed", "canceled"]>;
+    error: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    xid: string;
+    seq: number;
+    kind: "done";
+    state: "failed" | "completed" | "canceled";
+    error?: string | undefined;
+}, {
+    xid: string;
+    seq: number;
+    kind: "done";
+    state: "failed" | "completed" | "canceled";
+    error?: string | undefined;
+}>]>;
+export type BuilderEvent = z.infer<typeof BuilderEvent>;

package/dist/events.js

@@ -0,0 +1,63 @@
+/**
+ * Builder 事件 schema —— 单一事实源（003.技术方案/03 §2 的代码化）
+ * 服务端 C# 侧使用由此导出的 JSON Schema 做对偶校验。
+ * seq 作用域：单个 xid（任务）内单调递增（评审记录 R1）。
+ */
+import { z } from 'zod';
+export const SandboxState = z.enum([
+    'requested', 'creating', 'warming', 'ready', 'busy',
+    'snapshotting', 'hibernated', 'resuming', 'recycled', 'failed',
+]);
+const base = z.object({
+    xid: z.string(),
+    seq: z.number().int().nonnegative(),
+});
+/** 流前确认事件（服务端自产，固定 seq=0，不参与去重排序——R17） */
+export const AckEvent = base.extend({
+    kind: z.literal('ack'),
+    sandbox: z.object({
+        sandboxId: z.string(),
+        state: SandboxState,
+        previewUrl: z.string().url().optional(),
+    }),
+});
+export const MessageEvent = base.extend({
+    kind: z.literal('message'),
+    role: z.enum(['assistant', 'system']),
+    text: z.string(),
+});
+export const TaskCardEvent = base.extend({
+    kind: z.literal('taskCard'),
+    id: z.string(),
+    label: z.string(),
+    state: z.enum(['running', 'done', 'failed']),
+    detail: z.string().optional(),
+});
+export const FileDiffEvent = base.extend({
+    kind: z.literal('fileDiff'),
+    path: z.string(),
+    action: z.enum(['create', 'modify', 'delete']),
+    diff: z.string().optional(),
+    bytes: z.number().int().nonnegative(),
+    truncated: z.boolean().default(false),
+});
+export const PreviewEvent = base.extend({
+    kind: z.literal('preview'),
+    state: z.enum(['starting', 'ready', 'crashed']),
+    url: z.string().url().optional(),
+    error: z.string().nullable().optional(),
+});
+export const VersionEvent = base.extend({
+    kind: z.literal('version'),
+    sha: z.string(),
+    message: z.string(),
+    filesChanged: z.number().int().nonnegative(),
+});
+export const DoneEvent = base.extend({
+    kind: z.literal('done'),
+    state: z.enum(['completed', 'failed', 'canceled']),
+    error: z.string().optional(),
+});
+export const BuilderEvent = z.discriminatedUnion('kind', [
+    AckEvent, MessageEvent, TaskCardEvent, FileDiffEvent, PreviewEvent, VersionEvent, DoneEvent,
+]);

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './events';
+export * from './auth';
+export * from './client';
+export * from './parse';
+export * from './resume';
+export * from './agent3';
+export * from './agent3Transport';
+export * from './sse';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './events';
+export * from './auth';
+export * from './client';
+export * from './parse';
+export * from './resume';
+export * from './agent3';
+export * from './agent3Transport';
+export * from './sse';

package/dist/parse.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A2A 原始事件 → BuilderEvent 解析（03 §2 冻结 schema 的映射实现）。
+ * 未知/不完整事件返回 null（前向兼容：忽略而非报错——N4 版本偏斜策略）。
+ */
+import { BuilderEvent } from './events';
+export declare function parseBuilderEvent(raw: unknown): BuilderEvent | null;

package/dist/parse.js

@@ -0,0 +1,51 @@
+/**
+ * A2A 原始事件 → BuilderEvent 解析（03 §2 冻结 schema 的映射实现）。
+ * 未知/不完整事件返回 null（前向兼容：忽略而非报错——N4 版本偏斜策略）。
+ */
+import { BuilderEvent } from './events';
+export function parseBuilderEvent(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const r = raw;
+    const md = r.metadata ?? {};
+    const xid = r.taskId ?? r.task?.id;
+    if (!xid)
+        return null;
+    const seq = typeof md.seq === 'number' ? md.seq : 0;
+    let candidate = null;
+    if (md.sandbox) {
+        candidate = { kind: 'ack', xid, seq: 0, sandbox: md.sandbox };
+    }
+    else if (md.taskCard) {
+        candidate = { kind: 'taskCard', xid, seq, ...md.taskCard };
+    }
+    else if (md.preview) {
+        candidate = { kind: 'preview', xid, seq, ...md.preview };
+    }
+    else if (md.version) {
+        candidate = { kind: 'version', xid, seq, ...md.version };
+    }
+    else if (md.file && r.artifact) {
+        candidate = {
+            kind: 'fileDiff', xid, seq,
+            path: r.artifact.name ?? '',
+            action: md.file.action,
+            diff: r.artifact.parts?.find(p => p.kind === 'text')?.text,
+            bytes: md.file.bytes ?? 0,
+            truncated: md.file.truncated ?? false,
+        };
+    }
+    else if (md.text) {
+        candidate = { kind: 'message', xid, seq, role: md.role ?? 'assistant', text: md.text };
+    }
+    else {
+        const state = r.status?.state ?? r.task?.status?.state;
+        if (state === 'completed' || state === 'failed' || state === 'canceled') {
+            candidate = { kind: 'done', xid, seq, state, error: md.error };
+        }
+    }
+    if (candidate === null)
+        return null;
+    const parsed = BuilderEvent.safeParse(candidate);
+    return parsed.success ? parsed.data : null;
+}

package/dist/parse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/parse.test.js

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { parseBuilderEvent } from './parse';
+describe('parseBuilderEvent (03 §2 shapes)', () => {
+    it('parses create ack (seq forced to 0)', () => {
+        const e = parseBuilderEvent({
+            task: { id: 'xid-1', status: { state: 'submitted' } },
+            metadata: { seq: 1, sandbox: { sandboxId: 'sbx_a', state: 'resuming', previewUrl: 'https://sbx-a.n.y.com' } },
+        });
+        expect(e).toMatchObject({ kind: 'ack', xid: 'xid-1', seq: 0, sandbox: { sandboxId: 'sbx_a' } });
+    });
+    it('parses taskCard status update', () => {
+        const e = parseBuilderEvent({
+            taskId: 'xid-1', status: { state: 'working' },
+            metadata: { seq: 42, taskCard: { id: 'tc_3', label: '安装依赖', state: 'running', detail: 'pnpm add recharts' } },
+        });
+        expect(e).toMatchObject({ kind: 'taskCard', seq: 42, label: '安装依赖' });
+    });
+    it('parses fileDiff artifact', () => {
+        const e = parseBuilderEvent({
+            taskId: 'xid-1',
+            artifact: { artifactId: 'file:app/page.tsx', name: 'app/page.tsx', parts: [{ kind: 'text', text: '--- diff' }] },
+            metadata: { seq: 43, file: { action: 'modify', bytes: 2048, truncated: false } },
+        });
+        expect(e).toMatchObject({ kind: 'fileDiff', path: 'app/page.tsx', action: 'modify', diff: '--- diff' });
+    });
+    it('parses version artifact and done', () => {
+        expect(parseBuilderEvent({
+            taskId: 'xid-1', artifact: { artifactId: 'version:abc' },
+            metadata: { seq: 99, version: { sha: 'abc123', message: 'add landing page', filesChanged: 7 } },
+        })).toMatchObject({ kind: 'version', sha: 'abc123' });
+        expect(parseBuilderEvent({
+            taskId: 'xid-1', status: { state: 'completed' }, metadata: { seq: 100 },
+        })).toMatchObject({ kind: 'done', state: 'completed' });
+    });
+    it('returns null for unknown/malformed events (forward compat)', () => {
+        expect(parseBuilderEvent({ metadata: { seq: 1 } })).toBeNull(); // 无 xid
+        expect(parseBuilderEvent({ taskId: 'x', metadata: { seq: 1 } })).toBeNull(); // 无可识别载荷
+        expect(parseBuilderEvent('not-an-object')).toBeNull();
+        expect(parseBuilderEvent({ taskId: 'x', metadata: { seq: 1, taskCard: { bad: true } } })).toBeNull(); // schema 不符
+    });
+});
+import { createBuilderClient, CookieAuth } from './index';
+describe('client req envelope unwrap', () => {
+    const mkClient = (body, ct = 'application/json') => createBuilderClient({
+        restBase: 'https://api.test/web/Builder',
+        auth: new CookieAuth(),
+        transport: { stream: async function* () { }, resubscribe: async function* () { }, cancel: async () => { } },
+        fetchImpl: (async () => new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': ct } })),
+    });
+    it('unwraps {code:0,data} envelope', async () => {
+        const c = mkClient({ code: 0, data: { token: 't', previewUrl: 'https://x/?t=t' } });
+        expect(await c.sandbox.previewToken('c1')).toEqual({ token: 't', previewUrl: 'https://x/?t=t' });
+    });
+    it('passes through raw shapes (ContentResult endpoints)', async () => {
+        const c = mkClient({ versions: [{ sha: 'a', message: 'm', filesChanged: 1 }] });
+        expect((await c.versions.list('c1'))[0].sha).toBe('a');
+    });
+    it('throws on non-zero code', async () => {
+        const c = mkClient({ code: 400, data: null, message: '会话不存在' });
+        await expect(c.sandbox.status('c1')).rejects.toThrow('会话不存在');
+    });
+});

package/dist/resume.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 弹性事件流：seq 去重（xid 作用域）+ 断线自动 resubscribe（指数退避）。
+ * 保证下游拿到的流有序无重；ack(seq=0) 不参与去重。
+ */
+import type { BuilderEvent } from './events';
+export interface ResumeSource {
+    /** 初始流 */
+    open(): AsyncIterable<BuilderEvent | null>;
+    /** 断线后按 lastSeq 重订阅 */
+    reopen(lastSeq: number): AsyncIterable<BuilderEvent | null>;
+}
+export interface ResilienceOptions {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function resilientStream(source: ResumeSource, opts?: ResilienceOptions): AsyncIterable<BuilderEvent>;

package/dist/resume.js

@@ -0,0 +1,33 @@
+export async function* resilientStream(source, opts = {}) {
+    const maxRetries = opts.maxRetries ?? 3;
+    const baseDelay = opts.baseDelayMs ?? 500;
+    const sleep = opts.sleep ?? (ms => new Promise(r => setTimeout(r, ms)));
+    let lastSeq = 0;
+    let retries = 0;
+    let iterable = source.open();
+    for (;;) {
+        try {
+            for await (const ev of iterable) {
+                if (ev === null)
+                    continue;
+                if (ev.kind !== 'ack') {
+                    if (ev.seq <= lastSeq)
+                        continue; // 去重/乱序丢弃
+                    lastSeq = ev.seq;
+                }
+                retries = 0; // 有数据即重置退避
+                yield ev;
+                if (ev.kind === 'done')
+                    return;
+            }
+            return; // 流正常结束
+        }
+        catch (err) {
+            if (retries >= maxRetries)
+                throw err;
+            await sleep(baseDelay * 2 ** retries);
+            retries++;
+            iterable = source.reopen(lastSeq);
+        }
+    }
+}

package/dist/resume.test.d.ts

@@ -0,0 +1 @@
+export {};