DaemonClient-Schnellstart (TypeScript)

cd your-project/
qwen serve --port 4170
# → qwen serve hört auf http://127.0.0.1:4170 (Modus=http-bridge, Arbeitsverzeichnis=/path/to/your-project)

npm install @qwen-code/sdk

import { DaemonClient, type DaemonEvent } from '@qwen-code/sdk';
 
const client = new DaemonClient({
  baseUrl: 'http://127.0.0.1:4170',
  // PR 27 (v0.16-alpha): Wenn `token` weggelassen wird, greift DaemonClient
  // automatisch auf `process.env.QWEN_SERVER_TOKEN` zurück – dieselbe
  // Umgebungsvariable, auf die auch das `--token`-CLI-Flag des Daemons
  // zurückfällt. Also entweder:
  //   export QWEN_SERVER_TOKEN="$(openssl rand -hex 32)"   # einmalig
  //   export QWEN_SERVER_TOKEN="$(cat ./my-token-file)"    # benutzerverwaltete Datei
  //   const client = new DaemonClient({ baseUrl: '...' });
  // ODER explizit übergeben, wenn Sie einen anderen Umgebungsvariablennamen haben:
  //   token: process.env.MY_TOKEN,
});
 
// 1. Bestätigen, dass wir den Daemon erreichen können, Benutzeroberfläche auf seinen
//    Funktionen basieren und das gebundene Arbeitsverzeichnis des Daemons auslesen (#3803 §02).
const caps = await client.capabilities();
console.log('Daemon-Funktionen:', caps.features);
console.log('Daemon-Arbeitsverzeichnis:', caps.workspaceCwd); // kanonischer gebundener Pfad
 
// 2. Eine Sitzung erzeugen oder wiederherstellen. Zwei gleichwertige Varianten:
//    (a) `workspaceCwd: caps.workspaceCwd` übergeben, um explizit zu sein, oder
//    (b) `workspaceCwd` ganz weglassen – das SDK sendet dann kein `cwd`-Feld,
//        und die Daemon-Route fällt auf ihr gebundenes Arbeitsverzeichnis zurück.
//        Variante (b) ist prägnant, setzt aber voraus, dass Sie darauf vertrauen,
//        dass `caps.workspaceCwd` das ist, was Sie beabsichtigt haben.
//    Ein nicht leeres `workspaceCwd`, das nicht zum gebundenen Pfad des Daemons
//    kanonisiert, führt zu `400 workspace_mismatch` (siehe „Arbeitsverzeichnis-Konflikt“ unten).
const session = await client.createOrAttachSession({
  workspaceCwd: caps.workspaceCwd,
});
console.log(`Sitzung=${session.sessionId} wiederhergestellt=${session.attached}`);
 
// 3. Den Ereignisstrom abonnieren. `lastEventId: 0` übergeben, damit der Daemon
//    alle Ereignisse seit Sitzungsbeginn wiederholt – ohne dies gibt es ein
//    TOCTOU-Fenster zwischen dem Abruf des Iterators mit `subscribeEvents()`
//    und dem tatsächlichen Öffnen der zugrunde liegenden SSE-Verbindung
//    (ein HTTP-Roundtrip), in dem ein schnell startender Agent Ereignisse
//    aussenden kann, die zwar in den sitzungsspezifischen Ringpuffer gehen,
//    aber nicht an einen frischen Abonnenten ohne Cursor gestreamt werden.
//    `lastEventId: 0` deckt dieses Fenster mit dem Wiedergabepuffer ab
//    (und später auch jede Wiederverbindung – siehe unten).
const abort = new AbortController();
const subscription = (async () => {
  for await (const event of client.subscribeEvents(session.sessionId, {
    signal: abort.signal,
    lastEventId: 0,
  })) {
    handleEvent(event);
  }
})();
 
// 4. Eine Aufforderung senden und warten, bis die Antwort vollständig ist.
//    (Hinweis zur Reihenfolge: Selbst wenn `prompt()` vor dem Abschluss
//    des SSE-Handshakes aufgerufen wird, stellt `lastEventId: 0` aus Schritt 3
//    sicher, dass jedes Ereignis im Iterator landet.)
const result = await client.prompt(session.sessionId, {
  prompt: [{ type: 'text', text: 'Fasse src/main.ts in einem Satz zusammen.' }],
});
console.log('Stoppgrund:', result.stopReason);
 
// 5. Das Abonnement auflösen, damit das Skript beendet werden kann.
abort.abort();
await subscription;
 
function handleEvent(event: DaemonEvent): void {
  switch (event.type) {
    case 'session_update': {
      const data = event.data as {
        sessionUpdate: string;
        content?: { text?: string };
      };
      if (data.sessionUpdate === 'agent_message_chunk' && data.content?.text) {
        process.stdout.write(data.content.text);
      }
      break;
    }
    case 'permission_request':
      // Siehe „Abstimmen über Berechtigungen“ unten für die Semantik des Erstantworters.
      console.log('\n[Berechtigung erforderlich]', event.data);
      break;
    case 'permission_resolved':
      console.log('\n[Berechtigung erteilt/verweigert]', event.data);
      break;
    case 'session_died':
      console.error('\n[Agent abgestürzt]', event.data);
      break;
    default:
      console.log(`\n[${event.type}]`, event.data);
  }
}

const file = await client.readWorkspaceFile('src/main.ts');
 
const updated = await client.editWorkspaceFile({
  path: 'src/main.ts',
  oldText: 'timeout: 30000',
  newText: 'timeout: 60000',
  expectedHash: file.hash!,
});
 
console.log(updated.hash);

let cursor: number | undefined;
 
for await (const event of client.subscribeEvents(session.sessionId, {
  signal: abort.signal,
  lastEventId: cursor, // Fortsetzen ab dieser ID; undefined = nur Live-Ereignisse
})) {
  if (typeof event.id === 'number') cursor = event.id;
  handleEvent(event);
}

case 'permission_request': {
  const req = event.data as {
    requestId: string;
    options: Array<{ optionId: string; name: string; kind: string }>;
  };
  // Wählen Sie eine beliebige Option – `proceed_once`, `allow`, etc.
  const choice = req.options.find((o) => o.kind === 'allow_once') ?? req.options[0];
  const accepted = await client.respondToPermission(req.requestId, {
    outcome: { outcome: 'selected', optionId: choice.optionId },
  });
  if (!accepted) {
    console.log('Ein anderer Client hat zuerst abgestimmt; nichts zu tun.');
  }
  break;
}

// Der Daemon wurde als `qwen serve --workspace /work/repo` gestartet, also
// ist `caps.workspaceCwd === '/work/repo'` für beide Clients.
 
// Client A (z. B. ein IDE-Plugin)
const a = await clientA.createOrAttachSession({ workspaceCwd: '/work/repo' });
console.log(a.attached); // false – A hat den Agenten erzeugt
 
// Client B (z. B. eine Weboberfläche auf derselben Maschine)
const b = await clientB.createOrAttachSession({ workspaceCwd: '/work/repo' });
console.log(b.attached); // true – B ist A's Sitzung beigetreten
console.log(a.sessionId === b.sessionId); // true

import { DaemonHttpError } from '@qwen-code/sdk';
 
try {
  await client.createOrAttachSession({ workspaceCwd: '/some/other/project' });
} catch (err) {
  if (err instanceof DaemonHttpError && err.status === 400) {
    const body = err.body as {
      code?: string;
      boundWorkspace?: string;
      requestedWorkspace?: string;
    };
    if (body.code === 'workspace_mismatch') {
      console.error(
        `Dieser Daemon ist an ${body.boundWorkspace} gebunden, ` +
          `nicht an ${body.requestedWorkspace}. Starten Sie einen separaten Daemon ` +
          `für diesen Workspace oder leiten Sie zum richtigen weiter.`,
      );
    }
  }
}

const client = new DaemonClient({
  baseUrl: 'https://your-host:4170',
  token: process.env.QWEN_SERVER_TOKEN,
});

// Gleicher Effekt wie token: process.env.QWEN_SERVER_TOKEN, aber ohne den Boilerplate-Code.
const client = new DaemonClient({ baseUrl: 'https://your-host:4170' });

import { DaemonHttpError } from '@qwen-code/sdk';
 
try {
  await client.health();
} catch (err) {
  if (err instanceof DaemonHttpError) {
    console.error(`Daemon-Fehler ${err.status}:`, err.body);
  } else {
    throw err;
  }
}

await client.cancel(session.sessionId);
// Im Event-Stream sehen Sie, dass das Prompt mit stopReason: "cancelled" aufgelöst wird.