aipoch/remote-compute-ssh

Este skill cobre computação remota via SSH, incluindo execução direta e submissão ao Slurm: listar hosts, criar manipuladores, executar comandos remotos curtos (callCommand), ler/escrever documentos de conhecimento do host e o ciclo de vida completo de trabalhos assíncronos — submeter → salvar job_id → ler snapshots não bloqueantes por esse ID → coletar → turno de análise → publicar artefatos.

Onde host.compute é executado: host.compute vive APENAS no kernel REPL de controle — execute cada exemplo abaixo com a ferramenta repl_execute (JavaScript), o mesmo kernel que hospeda host.mcp. Os kernels de dados python/r NÃO têm host.compute (SSH e aprovações permanecem dentro do ambiente de trabalho do sandbox); chamá-lo de uma célula python/r falhará com host.compute is undefined.

Escolher um local de execução

Apenas os Hosts de Computação habilitados para esta Sessão são visíveis ou chamáveis. Descubra-os em um catálogo; cada entrada tem função selected ou available. Um pool selecionado não vazio é uma instrução de execução: realizar trabalho de tarefa baseado em ferramentas em um ou mais hosts selecionados conforme a tarefa exigir. O pool não tem prioridade e não implica agendamento automático em vários hosts. Se nenhum host estiver selecionado, escolha entre as entradas disponíveis. Leia details() apenas para candidatos que precisam de avaliação mais aprofundada.

Nunca adivinhe ou reutilize um ID de provedor ausente do catálogo. Um usuário nomeando um host desabilitado não o torna chamável; explique que ele deve primeiro ser habilitado para esta Sessão. Se nenhum host elegível for utilizável, explique o bloqueador e pergunte ao usuário como proceder.

const hosts = await host.compute.listHosts()
const selectedHosts = hosts.filter((host) => host.role === 'selected')
const candidates = selectedHosts.length > 0 ? selectedHosts : hosts

Cada item da lista é um resumo compacto com provider_id, display_name, shape, execution_mode, status e role (last_probe_ok, probe_failed ou not_probed). last_probe_ok significa que a Sondagem persistida mais recente foi bem-sucedida; não afirma conectividade ao vivo. Documentos de conhecimento e instantâneos de sonda de recursos são deliberadamente excluídos dos resultados da descoberta.

Referência da API

// Listar os hosts habilitados desta Sessão como um catálogo compacto com papéis
const hosts = await host.compute.listHosts()

// Nomes de descoberta de compatibilidade ainda disponíveis; ambos ocultam hosts desabilitados.
const visibleHosts = await host.compute.listRegistered()
const selectedHosts = await host.compute.listPreferred()

// Criar um manipulador para um host específico (sem chamada de rede)
const c = host.compute.create('ssh:<alias>')

// Executar um comando remoto curto (lança erro em approval_denied / host_unreachable / timeout)
const result = await c.callCommand('<comando shell>', '<intenção de uma linha para o cartão de aprovação>', {
  loginShell: true, // padrão: true — executa perfis de login, depois ~/.bashrc legível, antes deste comando
  timeoutSeconds: 60 // opcional — o host aplica seu próprio padrão (60s) quando omitido
})
// result → { exit_code, stdout, stderr, truncated }

// Ler as instruções de operação persistidas e o instantâneo independente da sonda de recursos.
// doc é sempre o texto salvo exato (incluindo '' antes de instruções serem salvas).
// probe é explicitamente null quando este host nunca foi sondado.
const info = await host.compute.details('ssh:<alias>', { mode: 'read' })

// Adicionar uma nota ao documento de conhecimento do host persistido (escrita por agente; limite de 32 KB).
// Append altera apenas doc; nunca copia ou altera observações da sonda.
await host.compute.details('ssh:<alias>', {
  mode: 'append',
  text: '\n## Nota\naprendido X em <data>'
})

// Alternativamente, substituir todo o documento de conhecimento do host. Leia novamente antes de substituir,
// especialmente se você anexou acima: oldText deve corresponder exatamente ao doc persistido.
const latest = await host.compute.details('ssh:<alias>', { mode: 'read' })
await host.compute.details('ssh:<alias>', {
  mode: 'replace',
  text: '<novo documento completo>',
  oldText: latest.doc
})

Trate doc como instruções de operação e conhecimento durável do host. Trate probe como uma observação datada: os valores dos recursos podem mudar, e detectar um agendador não autoriza submeter um trabalho ou selecionar uma conta, partição ou fila. Em caso de incompatibilidade de documento ou erro details_conflict, leia novamente e mescle seu rascunho com o documento mais recente antes de tentar novamente. Uma atualização de sonda apenas de recursos não altera doc nem causa conflito de substituição. Após escrever, leia novamente para verificar o conteúdo salvo. Um resultado bem-sucedido de append ou replace é apenas { ok: true }. O resultado da escrita não contém doc ou probe; sempre leia novamente para verificar o doc persistido exato em vez de ler campos do resultado da escrita.

Com loginShell: true, os perfis de login Bash remoto são executados primeiro e, em seguida, o Open-Science tenta originar ~/.bashrc quando este é legível. Um .bashrc pode deliberadamente retornar cedo para shells não interativos, portanto, variáveis declaradas após tal proteção não estão disponíveis. Um .bashrc ausente é uma não operação. Defina loginShell: false para executar o comando sem nenhuma das etapas de inicialização. Falhas de inicialização são relatadas através do comportamento normal de resultado/erro do comando.

Referência da API (trabalhos assíncronos)

Use submitJob para computações de longa duração (minutos a horas). Ele retorna imediatamente com um job_id; o trabalho é executado no host remoto em segundo plano. Quando o trabalho termina, o aplicativo automaticamente coleta as saídas e inicia um novo turno de análise se você ainda não leu o resultado terminal. Salve o job_id exato do resultado da submissão em seu contexto de trabalho; não há intencionalmente uma varredura histórica de Trabalhos para redescobri-lo. Leituras de status e resultado usam apenas esse ID salvo e retornam instantâneos locais não bloqueantes.

Para uma entrada local, src é relativo ao espaço de trabalho da Sessão do Agente — o mesmo espaço de trabalho usado por ferramentas de escrita de arquivos. Escreva um script ou pequena entrada gerada lá, depois passe seu caminho relativo. O Open-Science captura entradas aceitas antes da aprovação e expedição. Não passe caminhos absolutos locais arbitrários nem copie arquivos para diretórios gerenciados pelo aplicativo notebooks/.... Um src absoluto é válido apenas quando é o caminho exato retornado por host.artifactPath(versionId) ou um caminho de entrada registrado de Sessão já fornecido no contexto do Notebook.

// Reutilize os `candidates` selecionados acima do catálogo da Sessão.

// Submeter um trabalho não bloqueante — retorna imediatamente após o usuário aprovar.
// O modo de execução configurado do Host de Computação seleciona SSH direto ou Slurm.
const c = host.compute.create('ssh:<alias>')
const job = await c.submitJob(
  '<intenção de uma linha para o cartão de aprovação>', // mostrado no cartão de aprovação
  '<comando shell>', // comando a ser executado remotamente
  {
    environment: 'protein-gpu', // nome lógico opcional; veja Ativação de Ambiente abaixo
    timeoutSeconds: 3600, // opcional; padrão 24 h, máximo 7 dias
    inputs: [
      { src: 'in.dat', dstFilename: 'in.dat' }, // preparar um arquivo do espaço de trabalho da Sessão do Agente
      { remotePath: 'ssh:<alias>/<caminho_abs>' } // vincular um arquivo remoto (sem transferência)
    ],
    outputs: [
      '*.result', // em destaque (visibilidade padrão)
      { glob: '*.json', visibility: 'featured' }, // explicitamente em destaque
      { glob: '*.log', visibility: 'hidden' }, // oculto (diagnóstico, não mostrado no cartão)
      { glob: 'checkpoints/**', residency: 'remote' } // deixar no remoto — registrado em left_on_remote
    ],
    harvest: {
      exclude: ['work/**'], // nunca coletar esses caminhos
      maxFileMb: 100, // máximo absoluto por arquivo (100 MiB)
      maxTotalMb: 500 // máximo absoluto por trabalho, incluindo stdout/stderr (500 MiB)
    }
  }
)
// job → { job_id, provider_id, status: 'submitted' | 'queued', remote_workdir }
const savedJobId = job.job_id // reter este id exato para a etapa dependente posterior
return { ...job, job_id: savedJobId }

Ler um instantâneo de Trabalho salvo

Use o ID salvo quando o estado ou resultado do Trabalho for relevante. .status() e .result() são leituras locais não bloqueantes em todos os estados; nenhum espera por conclusão, aciona SSH ou inicia outra coleta. .result() também inclui listas de arquivos coletados. Ambas as chamadas relatam follow_up_delivery. Uma leitura final .result() retorna suppressed quando impede a entrega de fallback, ou committed quando esse fallback já cruzou sua barreira de expedição. Um instantâneo .status() permanece pending porque omite listas de arquivos coletados. Use o ID exato da submissão em vez de pesquisar Trabalhos antigos.

const snapshot = await c.attachJob(savedJobId).result()
if (!snapshot.result_final) {
  return {
    job_id: savedJobId,
    status: snapshot.status,
    result_final: false,
    follow_up_delivery: snapshot.follow_up_delivery
  }
}
return snapshot

Trate apenas result_final: true como o resultado final. Isso significa que a resposta automática está pronta: success, failed e timeout ainda podem estar esperando pela coleta local, enquanto cancelled e error são finais sem esperar pela coleta parcial de saída. output_files contém apenas arquivos realmente disponíveis localmente; uma lista vazia não prova que não há saídas remotas. O aplicativo gerencia a sondagem do provedor e a coleta em segundo plano. Um resultado final não lido é entregue em um Turno de Agente posterior. Um instantâneo final .result() relata follow_up_delivery: 'suppressed' quando suprime esse fallback, ou committed se a entrega automática já venceu a corrida e permanece autoritativa. .status() nunca consome o resultado completo.

SSH Direto ou Slurm

O modo de execução configurado do Host de Computação seleciona como cada trabalho é iniciado. direct_ssh executa o comando como um processo destacado no destino SSH. slurm submete-o com sbatch; coloque as diretivas #SBATCH exigidas pelo cluster no topo de command. O Open-Science gerencia submissão, sondagem de status do agendador, cancelamento e coleta. Não chame sbatch, squeue ou scancel em torno de submitJob você mesmo.

Para um erro de status do Slurm ou cancelamento falho, leia Resolução de problemas do Slurm. Nesse caminho excepcional, compute.callCommand pode inspecionar o mesmo trabalho e suas saídas e realizar recuperação dentro da autorização de tarefa existente do usuário. Mantenha a submissão comum na API de Computação.

Leia listHosts() para o modo configurado e details() para diretivas específicas do provedor; não tente substituir o modo por trabalho ou inferi-lo apenas da carga de trabalho. Se o Slurm estiver indisponível ou rejeitar o script, relate o erro retornado e o próximo passo concreto (por exemplo, adicionar uma diretiva de conta ou partição). Não execute novamente silenciosamente a carga de trabalho diretamente em um nó de login.

O Open-Science aceita diretivas comuns de trabalho único, como partição, conta, CPUs, memória e GPUs. Defina timeoutSeconds para o tempo de execução da carga de trabalho. Você pode definir o limite de alocação do agendador com uma diretiva #SBATCH --time=value; quando ausente, o Open-Science deriva um limite de alocação padrão de timeoutSeconds. O Open-Science gerencia o nome do trabalho, diretório de trabalho, stdout e stderr como diretivas. Evite arrays de trabalhos porque um trabalho do Open-Science rastreia um trabalho do agendador e uma coleta de saída. Submeta trabalhos independentes como trabalhos separados e use o limite de concorrência da Sessão quando necessário.

Para Slurm, solicite recursos com uma diretiva #SBATCH --option=value por linha (ou uma flag sem valor como #SBATCH --exclusive). A opção legada resources é metadados descritivos; não aloca CPUs, memória ou GPUs. timeoutSeconds limita o tempo de execução da carga de trabalho, não a espera na fila; #SBATCH --time define o limite de alocação do agendador. Nenhum é uma promessa de tempo de início na fila.

Os instantâneos não bloqueantes status() e result() do trabalho incluem scheduler_job_id quando conhecido, error: { code, message } em um erro no nível do trabalho, e last_poll_error quando observação ou recuperação de submissão precisa de atenção. Uma razão pendente ou linha de contabilidade atrasada não significa que a carga de trabalho falhou. Se uma submissão não for confirmada, use a identidade do trabalho relatada e diagnósticos do provedor antes de decidir se submeter novamente; o Open-Science não submete automaticamente uma duplicata.

Ativação de ambiente

O valor opcional environment é um nome lógico, não um comando shell. O Open-Science origina ~/.open-science/environments/<nome>.sh antes da carga de trabalho para trabalhos diretos e Slurm. Os nomes têm 1–64 letras, números, pontos, sublinhados ou hífens e devem começar com uma letra ou número. O arquivo e todos os caminhos de software/cache que ele referencia devem estar visíveis no nó de execução.

Se uma submissão relatar que este arquivo de ativação está faltando, carregue o Skill de Configuração de Ambiente de Computação para preparar instruções exatas de configuração, reparo e remoção para o usuário ou administrador do host executar fora do Open-Science. Valide a ativação gerenciada pelo usuário após eles aplicarem o plano, depois tente novamente. Não adivinhe um nome conda, adicione uma instalação inline ao trabalho científico ou oculte ativação em .bashrc. Omita environment quando o comando deliberadamente usa o ambiente padrão do host.

Limites de segurança de coleta

• Arquivos de saída declarados são selecionados antes de stdout e stderr; logs usam o orçamento restante por trabalho.
• O aplicativo rejeita limites fornecidos pelo modelo acima de 100 MiB por arquivo ou 500 MiB por trabalho.
• A coleta também preserva um espaço fixo de 2 GiB de disco local livre. Arquivos que não cabem permanecem remotos.

Limites de comportamento

• Enquanto o trabalho está em execução: a conversa está aberta. O usuário pode enviar mensagens; você pode lidar com outras tarefas. Cada consulta de status/resultado retorna imediatamente com o instantâneo local atual.
• Quando o trabalho termina: se você não leu ativamente seu resultado terminal, o aplicativo inicia um novo turno de análise automaticamente. Você não aciona este fallback.

Verificar status do trabalho (leitura não bloqueante, para uso informativo)

// Leitura não bloqueante do banco de dados — sem SSH. Use se precisar de um instantâneo de status no meio da conversa.
const handle = c.attachJob(job.job_id)
const s = await handle.status()
// s → {
//   job_id, scheduler_job_id?, status, result_final, cancellation?, exit_code,
//   error?, last