Sitzungslebenszyklus-Hooks

Mit Sitzungslebenszyklus-Hooks können Sie auf Start- und Endereignisse der Sitzung reagieren. Verwenden Sie sie für:

• Initialisieren des Kontexts, wenn Sitzungen beginnen
• Bereinigen von Ressourcen beim Beenden von Sitzungen
• Sitzungsmetriken und Analysen nachverfolgen
• Dynamisches Konfigurieren des Sitzungsverhaltens

Sitzungsstart-Hook

Der onSessionStart Hook wird aufgerufen, wenn eine Sitzung beginnt – ob neu oder fortgesetzt.

Hook-Signatur

import type { SessionStartHookInput, HookInvocation, SessionStartHookOutput } from "@github/copilot-sdk";
type SessionStartHandler = (
  input: SessionStartHookInput,
  invocation: HookInvocation
) => Promise<
  SessionStartHookOutput | null | undefined
>;

Die Hook-Signaturen in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Eingabe

Feld	Typ	Beschreibung
timestamp	Zahl	Unix-Zeitstempel, zu dem der Hook ausgelöst wurde
cwd	Schnur	Aktuelles Arbeitsverzeichnis
source

          `"startup"`
          \|
          `"resume"`
          \|
          `"new"`
         | Wie die Sitzung gestartet wurde |

| initialPrompt | Zeichenfolge | undefiniert | Die anfängliche Eingabeaufforderung, falls angegeben |

Output

Feld	Typ	Beschreibung
additionalContext	Schnur	Kontext zum Hinzufügen am Sitzungsstart
modifiedConfig	Objekt	Sitzungskonfiguration außer Kraft setzen

Beispiele

Projektkontext zu Beginn hinzufügen

const session = await client.createSession({
  hooks: {
    onSessionStart: async (
      input, invocation
    ) => {
      console.log(
        `Session ${invocation.sessionId} `
        + `started (${input.source})`
      );

      const projectInfo =
        await detectProjectType(input.cwd);

      return {
        additionalContext:
          `This is a ${projectInfo.type} project.\n`
          + `Main language: `
          + `${projectInfo.language}\n`
          + `Package manager: `
          + `${projectInfo.packageManager}`,
      };
    },
  },
});

Beispiele in Python finden Sie im github/copilot-sdk Repository.

Verwaltung der Sitzungswiederaufnahme

const session = await client.createSession({
  hooks: {
    onSessionStart: async (
      input, invocation
    ) => {
      if (input.source === "resume") {
        const previousState =
          await loadSessionState(
            invocation.sessionId
          );

        return {
          additionalContext:
            `Session resumed. Previous context:\n`
            + `- Last topic: `
            + `${previousState.lastTopic}\n`
            + `- Open files: `
            + previousState.openFiles.join(", "),
        };
      }
      return null;
    },
  },
});

Laden von Benutzereinstellungen

const session = await client.createSession({
  hooks: {
    onSessionStart: async () => {
      const preferences =
        await loadUserPreferences();

      const contextParts = [];

      if (preferences.language) {
        contextParts.push(
          `Preferred language: `
          + `${preferences.language}`
        );
      }
      if (preferences.codeStyle) {
        contextParts.push(
          `Code style: ${preferences.codeStyle}`
        );
      }
      if (preferences.verbosity === "concise") {
        contextParts.push(
          "Keep responses brief and "
          + "to the point."
        );
      }

      return {
        additionalContext:
          contextParts.join("\n"),
      };
    },
  },
});

Sitzungsende-Hook

Der onSessionEnd Hook wird aufgerufen, wenn eine Sitzung endet.

Hook-Signatur

import {
  HookInvocation,
  SessionEndHookInput,
  SessionEndHookOutput,
} from "@github/copilot-sdk";

type SessionEndHandler = (
  input: SessionEndHookInput,
  invocation: HookInvocation
) => Promise<
  SessionEndHookOutput | null | undefined
>;

Die Hook-Signaturen in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Eingabe

Feld	Typ	Beschreibung
timestamp	Zahl	Unix-Zeitstempel, zu dem der Hook ausgelöst wurde
cwd	Schnur	Aktuelles Arbeitsverzeichnis
reason	Schnur	Warum die Sitzung beendet wurde (siehe folgende Tabelle)
finalMessage	Zeichenfolge | undefiniert	Die letzte Nachricht aus der Sitzung
error	Zeichenfolge | undefiniert	Fehlermeldung, wenn die Sitzung aufgrund eines Fehlers beendet wurde

Endgründe

Grund	Beschreibung
"complete"	Die Sitzung wurde normal abgeschlossen.
"error"	Sitzung aufgrund eines Fehlers beendet
"abort"	Die Sitzung wurde durch den Benutzer oder durch Code abgebrochen.
"timeout"	Sitzung abgelaufen
"user_exit"	Der Benutzer hat die Sitzung explizit beendet.

Output

Feld	Typ	Beschreibung
suppressOutput	boolean	Endgültige Sitzungsausgabe unterdrücken
cleanupActions	string[]	Liste der auszuführenden Bereinigungsaktionen
sessionSummary	Schnur	Zusammenfassung der Sitzung für Protokollierung/Analyse

Beispiele

Nachverfolgen von Sitzungsmetriken

const sessionStartTimes =
  new Map<string, number>();

const session = await client.createSession({
  hooks: {
    onSessionStart: async (
      input, invocation
    ) => {
      sessionStartTimes.set(
        invocation.sessionId, input.timestamp
      );
      return null;
    },
    onSessionEnd: async (
      input, invocation
    ) => {
      const startTime = sessionStartTimes.get(
        invocation.sessionId
      );
      const duration = startTime
        ? input.timestamp - startTime
        : 0;

      await recordMetrics({
        sessionId: invocation.sessionId,
        duration,
        endReason: input.reason,
      });

      sessionStartTimes.delete(
        invocation.sessionId
      );
      return null;
    },
  },
});

Beispiele in Python finden Sie im github/copilot-sdk Repository.

Bereinigen von Ressourcen

const sessionResources =
  new Map<string, { tempFiles: string[] }>();

const session = await client.createSession({
  hooks: {
    onSessionStart: async (
      input, invocation
    ) => {
      sessionResources.set(
        invocation.sessionId,
        { tempFiles: [] }
      );
      return null;
    },
    onSessionEnd: async (
      input, invocation
    ) => {
      const resources =
        sessionResources.get(
          invocation.sessionId
        );

      if (resources) {
        for (const file
          of resources.tempFiles) {
          await fs.unlink(file).catch(() => {});
        }
        sessionResources.delete(
          invocation.sessionId
        );
      }

      console.log(
        `Session ${invocation.sessionId} `
        + `ended: ${input.reason}`
      );
      return null;
    },
  },
});

Sitzungsstatus zum Fortsetzen speichern

const session = await client.createSession({
  hooks: {
    onSessionEnd: async (input, invocation) => {
      if (input.reason !== "error") {
        // Save state for potential resume
        await saveSessionState(invocation.sessionId, {
          endTime: input.timestamp,
          cwd: input.cwd,
          reason: input.reason,
        });
      }
      return null;
    },
  },
});

Protokollsitzungszusammenfassung

const sessionData: Record<
  string,
  { prompts: number; tools: number;
    startTime: number }
> = {};

const session = await client.createSession({
  hooks: {
    onSessionStart: async (
      input, invocation
    ) => {
      sessionData[invocation.sessionId] = {
        prompts: 0,
        tools: 0,
        startTime: input.timestamp,
      };
      return null;
    },
    onUserPromptSubmitted: async (
      _, invocation
    ) => {
      sessionData[
        invocation.sessionId
      ].prompts++;
      return null;
    },
    onPreToolUse: async (_, invocation) => {
      sessionData[
        invocation.sessionId
      ].tools++;
      return { permissionDecision: "allow" };
    },
    onSessionEnd: async (
      input, invocation
    ) => {
      const data =
        sessionData[invocation.sessionId];
      const durationSec =
        (input.timestamp - data.startTime)
        / 1000;
      console.log(
        `Session Summary:\n`
        + `  ID: ${invocation.sessionId}\n`
        + `  Duration: ${durationSec}s\n`
        + `  Prompts: ${data.prompts}\n`
        + `  Tool calls: ${data.tools}\n`
        + `  End reason: ${input.reason}`
      );

      delete sessionData[
        invocation.sessionId
      ];
      return null;
    },
  },
});

Bewährte Methoden

•         **Stellen Sie sicher, dass `onSessionStart` schnell bleibt.** Benutzer warten darauf, dass die Sitzung bereit ist.
  

•         **Behandeln Sie alle Beendigungsgründe.** Gehen Sie nicht davon aus, dass Sitzungen sauber enden; behandeln Sie Fehler und Abbrüche.
  

•         **Ressourcen bereinigen.** Verwenden Sie `onSessionEnd`, um alle während der Sitzung zugewiesenen Ressourcen freizugeben.
  

•         **Speichern Sie den minimalen Zustand.** Wenn Sitzungsdaten nachverfolgt werden, halten Sie diese leichtgewichtig.
  

•         **Machen Sie die Bereinigung idempotent.** 
          `onSessionEnd` wird möglicherweise nicht aufgerufen, wenn der Prozess abstürzt.
  

Weiterführende Lektüre

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/quickstart)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/error-handling)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/user-prompt-submitted)