Thanks to visit codestin.com
Credit goes to docs.github.com

Ganchos de ciclo de vida de sessão

Os ganchos de ciclo de vida da sessão permitem que você responda aos eventos de início e término da sessão. Use-os para:

Neste artigo

  • Inicialize o contexto quando as sessões começarem
  • Limpar recursos quando as sessões terminarem
  • Acompanhar as métricas e análises da sessão
  • Configurar o comportamento da sessão dinamicamente

Gancho de início da sessão {#session-start}

O onSessionStart gancho é chamado quando uma sessão é iniciada (nova ou retomada).

Assinatura de Hook

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

type SessionStartHandler = (
  input: SessionStartHookInput,
  invocation: HookInvocation
) => Promise<SessionStartHookOutput | null | undefined>;
Python
from copilot.session import SessionStartHookInput, SessionStartHookOutput
from typing import Callable, Awaitable

SessionStartHandler = Callable[
    [SessionStartHookInput, dict[str, str]],
    Awaitable[SessionStartHookOutput | None]
]

SessionStartHandler = Callable[
    [SessionStartHookInput, dict[str, str]],
    Awaitable[SessionStartHookOutput | None]
]
Go
package main

import copilot "github.com/github/copilot-sdk/go"

type SessionStartHandler func(
    input copilot.SessionStartHookInput,
    invocation copilot.HookInvocation,
) (*copilot.SessionStartHookOutput, error)

func main() {}

type SessionStartHandler func(
    input SessionStartHookInput,
    invocation HookInvocation,
) (*SessionStartHookOutput, error)
.NET
using GitHub.Copilot;

public delegate Task<SessionStartHookOutput?> SessionStartHandler(
    SessionStartHookInput input,
    HookInvocation invocation);

public delegate Task<SessionStartHookOutput?> SessionStartHandler(
    SessionStartHookInput input,
    HookInvocation invocation);
Java
import com.github.copilot.sdk.json.*;

SessionStartHandler sessionStartHandler;

Entrada

CampoTipoDescrição
timestampnumberCarimbo de data/hora Unix de quando o gancho foi desencadeado
cwdcadeiaDiretório de trabalho atual
source
"startup"
|
"resume"
|
"new"
Como a sessão foi iniciada
initialPromptcadeia de caracteres | indefinidaO prompt inicial, se fornecido

Saída

CampoTipoDescrição
additionalContextcadeiaContexto a ser adicionado no início da sessão
modifiedConfigobjetoSobrepor configuração de sessão

Exemplos

Adicionar contexto de projeto no início

TypeScript
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.
Main language: ${projectInfo.language}
Package manager: ${projectInfo.packageManager}
        `.trim(),
      };
    },
  },
});
Python
from copilot.session import PermissionHandler

async def on_session_start(input_data, invocation):
    print(f"Session {invocation['session_id']} started ({input_data['source']})")
    
    project_info = await detect_project_type(input_data["cwd"])
    
    return {
        "additionalContext": f"""
This is a {project_info['type']} project.
Main language: {project_info['language']}
Package manager: {project_info['packageManager']}
        """.strip()
    }

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={"on_session_start": on_session_start})

Lidar com a retomada de sessão

const session = await client.createSession({
  hooks: {
    onSessionStart: async (input, invocation) => {
      if (input.source === "resume") {
        // Load previous session state
        const previousState = await loadSessionState(invocation.sessionId);
        
        return {
          additionalContext: `
Session resumed. Previous context:
- Last topic: ${previousState.lastTopic}
- Open files: ${previousState.openFiles.join(", ")}
          `.trim(),
        };
      }
      return null;
    },
  },
});

Carregar preferências do usuário

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"),
      };
    },
  },
});

Gancho de fim de sessão {#session-end}

O onSessionEnd gancho é invocado quando uma sessão termina.

Assinatura de Hook

TypeScript
type SessionEndHandler = (
  input: SessionEndHookInput,
  invocation: HookInvocation
) => Promise<SessionEndHookOutput | null | undefined>;
Python
from copilot.session import SessionEndHookInput
from typing import Callable, Awaitable

SessionEndHandler = Callable[
    [SessionEndHookInput, dict[str, str]],
    Awaitable[None]
]

SessionEndHandler = Callable[
    [SessionEndHookInput, dict[str, str]],
    Awaitable[SessionEndHookOutput | None]
]
Go
package main

import copilot "github.com/github/copilot-sdk/go"

type SessionEndHandler func(
    input copilot.SessionEndHookInput,
    invocation copilot.HookInvocation,
) error

func main() {}

type SessionEndHandler func(
    input SessionEndHookInput,
    invocation HookInvocation,
) (*SessionEndHookOutput, error)
.NET
public delegate Task<SessionEndHookOutput?> SessionEndHandler(
    SessionEndHookInput input,
    HookInvocation invocation);
Java
import com.github.copilot.sdk.json.*;

SessionEndHandler sessionEndHandler;

Entrada

CampoTipoDescrição
timestampnumberCarimbo de data/hora Unix de quando o gancho foi desencadeado
cwdcadeiaDiretório de trabalho atual
reasoncadeiaPor que a sessão terminou (veja abaixo)
finalMessagecadeia de caracteres | indefinidaA última mensagem da sessão
errorcadeia de caracteres | indefinidaMensagem de erro se a sessão terminou devido a um erro

Motivos finais

ReasonDescrição
"complete"Sessão concluída normalmente
"error"Sessão encerrada devido a um erro
"abort"A sessão foi abortada pelo usuário ou pelo código.
"timeout"Sessão expirada
"user_exit"O usuário encerrou explicitamente a sessão

Saída

CampoTipoDescrição
suppressOutputbooleanSuprimir a saída final da sessão
cleanupActionsstring[]Lista de ações de limpeza a serem executadas
sessionSummarycadeiaResumo da sessão para registro/análise de dados

Exemplos

Acompanhar métricas de sessão

TypeScript
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;
    },
  },
});
Python
from copilot.session import PermissionHandler

session_start_times = {}

async def on_session_start(input_data, invocation):
    session_start_times[invocation["session_id"]] = input_data["timestamp"]
    return None

async def on_session_end(input_data, invocation):
    start_time = session_start_times.get(invocation["session_id"])
    duration = input_data["timestamp"] - start_time if start_time else 0
    
    await record_metrics({
        "session_id": invocation["session_id"],
        "duration": duration,
        "end_reason": input_data["reason"],
    })
    
    session_start_times.pop(invocation["session_id"], None)
    return None

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={
        "on_session_start": on_session_start,
        "on_session_end": on_session_end,
    })

Limpar os recursos

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) {
        // Clean up temp files
        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;
    },
  },
});

Salvar o estado da sessão para retomar

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;
    },
  },
});

Resumo da sessão de log

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];
      console.log(`
Session Summary:
  ID: ${invocation.sessionId}
  Duration: ${(input.timestamp - data.startTime) / 1000}s
  Prompts: ${data.prompts}
  Tool calls: ${data.tools}
  End reason: ${input.reason}
      `.trim());
      
      delete sessionData[invocation.sessionId];
      return null;
    },
  },
});

Práticas recomendadas

  1.           **Mantenha `onSessionStart` rápido** – os usuários estão aguardando a sessão ficar pronta.

  2.           **Trate todos os motivos de encerramento** – não presuma que as sessões se encerrem sem problemas; trate erros e abortos.

  3. Limpar recursos – Use onSessionEnd para liberar todos os recursos alocados durante a sessão.

  4.           **Armazenar o estado mínimo** – se estiver acompanhando os dados da sessão, mantenha-os leves.

  5.           **Tornar a limpeza idempotente** - `onSessionEnd` pode não ser chamado se o processo falhar.

Consulte também