npm - agents-relay - Versions diffs - 1.0.0 - Mend

agents-relay 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (62) hide show

package/.github/workflows/publish.yml +91 -0
package/AGENTS.md +16 -0
package/LICENSE +21 -0
package/README.md +102 -0
package/dist/adapters.js +311 -0
package/dist/cli.js +455 -0
package/dist/continuation.js +21 -0
package/dist/dashboard.js +446 -0
package/dist/events.js +36 -0
package/dist/github-auth.js +34 -0
package/dist/github-webhook.js +47 -0
package/dist/markers.js +42 -0
package/dist/planner.js +172 -0
package/dist/pool.js +98 -0
package/dist/reconciler.js +434 -0
package/dist/registry.js +27 -0
package/dist/relayd.js +177 -0
package/dist/scheduler.js +49 -0
package/dist/store.js +586 -0
package/dist/types.js +6 -0
package/dist/usage.js +370 -0
package/dist/workspace.js +76 -0
package/docs/agent-network.md +34 -0
package/docs/architecture.md +120 -0
package/docs/autonomous-objective-jobs.md +121 -0
package/docs/example.md +30 -0
package/docs/github-app-rate-limit.md +124 -0
package/docs/service.md +43 -0
package/pack.json +326 -0
package/package.json +14 -0
package/scripts/npm-version.mjs +11 -0
package/skills/agents-relay/SKILL.md +77 -0
package/skills/agents-relay/agents/planner.agent.md +28 -0
package/src/adapters.ts +231 -0
package/src/cli.ts +324 -0
package/src/continuation.ts +6 -0
package/src/dashboard.ts +421 -0
package/src/events.ts +25 -0
package/src/github-auth.ts +35 -0
package/src/github-webhook.ts +37 -0
package/src/markers.ts +33 -0
package/src/planner.ts +150 -0
package/src/pool.ts +87 -0
package/src/reconciler.ts +235 -0
package/src/registry.ts +35 -0
package/src/relayd.ts +137 -0
package/src/scheduler.ts +27 -0
package/src/store.ts +526 -0
package/src/types.ts +45 -0
package/src/usage.ts +385 -0
package/src/workspace.ts +62 -0
package/test/adapters.test.js +303 -0
package/test/autonomous.test.js +119 -0
package/test/core.test.js +363 -0
package/test/dashboard.test.js +178 -0
package/test/github-auth.test.js +51 -0
package/test/github-webhook.test.js +21 -0
package/test/service.test.js +116 -0
package/test/store.test.js +390 -0
package/test/usage.test.js +88 -0
package/test/workspace.test.js +95 -0
package/tsconfig.json +4 -0

package/src/dashboard.ts ADDED Viewed

@@ -0,0 +1,421 @@
+import { createServer, Server } from 'node:http';
+import { DurableStore, ManagedJobOverview } from './store.js';
+import { EventBus } from './events.js';
+import { UsageRegistry } from './usage.js';
+import { Job } from './types.js';
+import { DeliveryDeduper, parseGitHubWebhook, verifyGitHubWebhook } from './github-webhook.js';
+const GITHUB_REPOSITORY_PATTERN = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,36}[A-Za-z0-9])?)\/([A-Za-z0-9._-]{1,100})$/;
+const SSE_HEARTBEAT_MS = 15000;
+function isPositiveInteger(candidate: unknown): candidate is number {
+  return typeof candidate === 'number' && Number.isInteger(candidate) && candidate > 0;
+}
+function isSafeRepositorySegment(segment: string): boolean {
+  return segment !== '.' && segment !== '..';
+}
+export function githubPrUrl(repository: unknown, prNumber: unknown): string | null {
+  if (typeof repository !== 'string' || !isPositiveInteger(prNumber)) return null;
+  const match = GITHUB_REPOSITORY_PATTERN.exec(repository);
+  if (!match) return null;
+  const [, owner, repo] = match;
+  if (!isSafeRepositorySegment(owner) || !isSafeRepositorySegment(repo)) return null;
+  return `https://github.com/${owner}/${repo}/pull/${prNumber}`;
+}
+export const dashboardHtml = `<!doctype html>
+<html lang="en" data-dashboard-contract="safe-dom,named-relay-events,snapshot-events,bounded-event-history">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Agents Relay Console</title>
+  <style>
+    :root { color-scheme: light dark; --bg:#f3f5f8; --surface:#fff; --surface2:#f8fafc; --border:#d8dee7; --text:#17202b; --muted:#687587; --accent:#285f86; --accent2:#e8f1f8; --ok:#19703a; --warn:#8b5b08; --bad:#a33c3c; --shadow:0 1px 2px rgba(15,23,42,.06); }
+    * { box-sizing:border-box; }
+    [hidden] { display:none !important; }
+    body { margin:0; min-height:100vh; background:var(--bg); color:var(--text); font:14px/1.45 ui-sans-serif,system-ui,sans-serif; }
+    header { position:sticky; top:0; z-index:3; background:var(--surface); border-bottom:1px solid var(--border); padding:.8rem 1rem; }
+    .brand { display:flex; align-items:baseline; gap:.65rem; min-width:0; }
+    h1 { margin:0; font-size:1.08rem; letter-spacing:-.02em; }
+    .tagline,.subtle { color:var(--muted); font-size:.78rem; }
+    .warning-banner { margin:.65rem 0 0; padding:.5rem .65rem; border:1px solid #e6bf62; border-radius:.4rem; background:#fff4d6; color:#6f4b00; font-size:.78rem; font-weight:700; }
+    .tagline { margin:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    nav[role="tablist"] { display:flex; gap:.3rem; margin-top:.65rem; }
+    nav button { border:0; border-radius:.35rem; background:transparent; color:var(--muted); padding:.38rem .68rem; font:inherit; font-weight:700; cursor:pointer; }
+    nav button[aria-selected="true"] { background:var(--accent); color:#fff; }
+    button:focus-visible,a:focus-visible { outline:2px solid var(--accent); outline-offset:2px; }
+    main { max-width:1500px; margin:auto; padding:1rem; display:grid; grid-template-columns:minmax(280px,340px) minmax(0,1fr); gap:1rem; align-items:start; }
+    .panel { min-width:0; background:var(--surface); border:1px solid var(--border); border-radius:.55rem; box-shadow:var(--shadow); }
+    .panel-head { display:flex; align-items:center; justify-content:space-between; gap:.6rem; padding:.65rem .75rem; border-bottom:1px solid var(--border); }
+    .panel-head h2,.panel-head h3 { margin:0; color:var(--muted); font-size:.75rem; letter-spacing:.07em; text-transform:uppercase; }
+    .panel-actions { display:flex; align-items:center; gap:.45rem; }
+    .job-filters { display:flex; gap:.35rem; align-items:center; flex-wrap:wrap; }
+    .job-filter { max-width:145px; border:1px solid var(--border); border-radius:.35rem; background:var(--surface); color:var(--text); padding:.27rem .4rem; font:inherit; font-size:.72rem; }
+    .refresh-button { border:1px solid var(--border); border-radius:.35rem; background:var(--surface); color:var(--muted); padding:.28rem .55rem; font:inherit; font-size:.72rem; font-weight:700; cursor:pointer; }
+    .refresh-button:disabled { cursor:default; opacity:.55; }
+    .panel-body { padding:.75rem; overflow:auto; max-height:calc(100vh - 11.5rem); }
+    #jobs-workspace > .panel:first-child .panel-body { overflow:visible; max-height:none; }
+    .jobs-panel { grid-row:1/span 2; }
+    .workspace { display:grid; gap:1rem; }
+    .job-list,.tree,.event-list { list-style:none; margin:0; padding:0; }
+    .job-list { display:grid; gap:.35rem; }
+    .job-button { width:100%; display:grid; gap:.2rem; padding:.5rem; border:1px solid transparent; border-radius:.4rem; background:transparent; color:inherit; text-align:left; font:inherit; cursor:pointer; }
+    .job-button[aria-current="true"] { border-color:var(--accent); background:var(--accent2); }
+    .job-button.complete-unmerged { border-color:#d69a1b; background:#fff8df; }
+    .job-button.complete-unmerged[aria-current="true"] { border-color:#b77900; background:#fff0bd; }
+    .job-title { font-weight:750; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    .job-meta { display:flex; gap:.4rem; flex-wrap:wrap; color:var(--muted); font-size:.7rem; }
+    .job-meta span { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    .status-pill,.badge { display:inline-flex; align-items:center; border-radius:999px; padding:.06rem .42rem; min-height:1.35rem; font-size:.68rem; font-weight:800; }
+    .status-pill.ok,.badge.RUNNING,.badge.SUCCEEDED,.badge.COMPLETED { background:#e5f3e9; color:var(--ok); }
+    .status-pill.warn,.badge.BLOCKED,.badge.WAITING,.badge.QUEUED,.badge.READY,.badge.OPEN { background:#fff1d2; color:var(--warn); }
+    .status-pill.bad,.badge.FAILED { background:#ffe8e8; color:var(--bad); }
+    .status-pill.neutral,.badge.CANCELLED { background:#edf0f4; color:var(--muted); }
+    .badge.DRAFT { background:#eef2ff; color:#3f51b5; }
+    .badge.MERGE_PENDING { background:#ffe3a3; color:#7a4a00; }
+    .job-summary,.detail-groups { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:.55rem; }
+    .detail-group { min-width:0; padding:.5rem; background:var(--surface2); border:1px solid var(--border); border-radius:.4rem; }
+    .detail-label { margin:0; color:var(--muted); font-size:.66rem; text-transform:uppercase; letter-spacing:.04em; }
+    .detail-value { margin:.12rem 0 0; font-weight:650; overflow-wrap:anywhere; }
+    .section-title { margin:.8rem 0 .35rem; color:var(--muted); font-size:.72rem; letter-spacing:.05em; text-transform:uppercase; }
+    ul.tree { display:grid; gap:.25rem; }
+    ul.tree ul { list-style:none; margin:.2rem 0 .1rem .6rem; padding-left:.6rem; border-left:1px solid var(--border); }
+    .task-row { width:100%; display:flex; align-items:center; gap:.4rem; min-width:0; padding:.32rem .38rem; border:0; border-radius:.35rem; background:transparent; color:inherit; font:inherit; text-align:left; cursor:pointer; }
+    .task-row[aria-current="true"] { background:var(--accent2); }
+    .task-id { min-width:0; flex:1; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; font: .77rem ui-monospace,SFMono-Regular,Menlo,monospace; }
+    .event-list { display:grid; gap:.45rem; }
+    .event-item { padding-bottom:.4rem; border-bottom:1px solid var(--border); }
+    .event-meta { display:flex; flex-wrap:wrap; gap:.4rem; color:var(--muted); font-size:.68rem; }
+    .event-kind { color:var(--accent); font-weight:800; }
+    .event-message { margin:.12rem 0 0; overflow-wrap:anywhere; }
+    #usage-view { grid-column:1 / -1; }
+    .usage-providers { display:grid; gap:.55rem; }
+    .usage-provider { display:grid; grid-template-columns:minmax(130px,180px) minmax(0,1fr); gap:1rem; align-items:center; padding:.7rem .8rem; border:1px solid var(--border); border-radius:.45rem; background:var(--surface2); }
+    .usage-provider h3 { margin:0; font-size:.86rem; }
+    .usage-bars { display:grid; gap:1rem; }
+    .usage-row { display:grid; gap:.35rem; }
+    .usage-label { display:flex; justify-content:space-between; gap:1rem; font-weight:700; }
+    .usage-track { height:.72rem; overflow:hidden; border:1px solid var(--border); border-radius:999px; background:var(--surface2); }
+    .usage-fill { height:100%; width:0; border-radius:inherit; background:var(--accent); transition:width .2s ease; }
+    .empty,.error-state { padding:.85rem; border:1px dashed var(--border); border-radius:.4rem; color:var(--muted); }
+    .error-state,.error-text { color:var(--bad); }
+    .skeleton { height:3.2rem; border-radius:.4rem; background:linear-gradient(90deg,#edf0f4,#fafbfc,#edf0f4); animation:pulse 1.2s infinite; }
+    @keyframes pulse { 50% { opacity:.55; } }
+    @media (max-width:1050px) { main { grid-template-columns:1fr; } .jobs-panel { grid-row:auto; } .panel-body { max-height:24rem; } #jobs-workspace > .panel:first-child .panel-body { max-height:none; } }
+    @media (max-width:650px) { main { padding:.65rem; } .job-summary,.detail-groups { grid-template-columns:1fr; } .tagline { display:none; } }
+    @media (prefers-reduced-motion:reduce) { .skeleton { animation:none; } .usage-fill { transition:none; } }
+  </style>
+</head>
+<body>
+<header>
+  <div class="brand"><h1>Agents Relay Console</h1><p class="tagline">Durable PR state is authoritative; events are observability.</p></div>
+  <div id="rate-limit-warning" class="warning-banner" role="status" hidden></div>
+  <nav role="tablist" aria-label="Console views">
+    <button id="jobs-tab" type="button" role="tab" aria-selected="true" aria-controls="jobs-view">Jobs</button>
+    <button id="usage-tab" type="button" role="tab" aria-selected="false" aria-controls="usage-view">Usage</button>
+  </nav>
+</header>
+<main>
+  <section id="jobs-view" role="tabpanel" aria-labelledby="jobs-tab" class="panel jobs-panel">
+    <div class="panel-head"><h2>Jobs</h2><div class="panel-actions"><div class="job-filters"><select id="repo-filter" class="job-filter" aria-label="Filter jobs by repository"><option value="">All repos</option></select></div><button id="jobs-refresh" class="refresh-button" type="button">Refresh</button></div></div>
+    <div class="panel-body" aria-live="polite"><ul id="job-list" class="job-list"><li class="skeleton" aria-hidden="true"></li></ul></div>
+  </section>
+  <div class="workspace" id="jobs-workspace">
+    <section class="panel" aria-labelledby="workspace-heading">
+      <div class="panel-head"><h2 id="workspace-heading">Selected job <span id="selected-job-title" class="subtle"></span></h2><div class="panel-actions"><button id="selected-job-refresh" class="refresh-button" type="button">Refresh</button><span id="connection" aria-live="polite">Connecting…</span></div></div>
+      <div class="panel-body">
+        <div id="job-detail"><div class="skeleton"></div></div>
+        <h3 class="section-title">Task hierarchy</h3>
+        <ul id="task-tree" class="tree"><li class="skeleton"></li></ul>
+        <h3 class="section-title">Task detail</h3>
+        <div id="task-detail"><p class="empty">Select a task to inspect execution details.</p></div>
+      </div>
+    </section>
+    <section class="panel" id="events-panel" aria-labelledby="events-heading">
+      <div class="panel-head"><h2 id="events-heading">Events</h2><span class="subtle">Newest first · 60 max</span></div>
+      <div class="panel-body"><ol id="event-feed" class="event-list"><li class="empty">Waiting for events.</li></ol></div>
+    </section>
+  </div>
+  <section id="usage-view" role="tabpanel" aria-labelledby="usage-tab" hidden>
+    <div class="panel">
+      <div class="panel-head"><h2 id="usage-heading">Usage</h2><span id="usage-meta" class="subtle"></span></div>
+      <div class="panel-body" id="usage-root" aria-live="polite"><div class="skeleton"></div></div>
+    </div>
+  </section>
+</main>
+<script>
+'use strict';
+// Compatibility contracts retained for dashboard tests:
+// function taskDetail(
+// location.hash = selectedJob ? '#/jobs/' + encodeURIComponent(selectedJob) : '#/jobs'
+// const url = githubPrUrl(job.repository, job.prNumber);
+// const link = document.createElement('a');
+// link.href = url;
+// link.target = '_blank';
+// link.rel = 'noopener noreferrer';
+// link.textContent = 'PR #' + job.prNumber;
+// while (eventFeed.children.length > MAX_EVENTS)
+// function usageBar(label, window)
+const MAX_EVENTS=60;
+const jobsTab=document.querySelector('#jobs-tab');
+const usageTab=document.querySelector('#usage-tab');
+const jobsView=document.querySelector('#jobs-view');
+const usageView=document.querySelector('#usage-view');
+const jobsWorkspace=document.querySelector('#jobs-workspace');
+const jobList=document.querySelector('#job-list');
+const jobsRefresh=document.querySelector('#jobs-refresh');
+const repoFilter=document.querySelector('#repo-filter');
+const selectedJobRefresh=document.querySelector('#selected-job-refresh');
+const jobDetail=document.querySelector('#job-detail');
+const taskTree=document.querySelector('#task-tree');
+const taskDetailRoot=document.querySelector('#task-detail');
+const eventFeed=document.querySelector('#event-feed');
+const connection=document.querySelector('#connection');
+const selectedJobTitle=document.querySelector('#selected-job-title');
+const usageRoot=document.querySelector('#usage-root');
+const usageMeta=document.querySelector('#usage-meta');
+const rateLimitWarning=document.querySelector('#rate-limit-warning');
+let jobs=[];
+let selectedJob=sessionStorage.getItem('agents-relay:selected-job');
+let selectedTaskId=sessionStorage.getItem('agents-relay:selected-task');
+let selectedRepo=sessionStorage.getItem('agents-relay:repo-filter')||'';
+function value(input){return input===null||input===undefined||input===''?'—':String(input);}
+function text(input){return document.createTextNode(value(input));}
+function element(name,className,child){const node=document.createElement(name);if(className)node.className=className;if(child)node.append(child);return node;}
+function field(label,input){const box=element('div','detail-group');box.append(element('p','detail-label',text(label)),element('p','detail-value',text(input)));return box;}
+function markdownField(label,input){const box=element('div','detail-group');box.append(element('p','detail-label',text(label)),markdownValue(input));return box;}
+function rememberSelection(){if(selectedJob)sessionStorage.setItem('agents-relay:selected-job',selectedJob);else sessionStorage.removeItem('agents-relay:selected-job');if(selectedTaskId)sessionStorage.setItem('agents-relay:selected-task',selectedTaskId);else sessionStorage.removeItem('agents-relay:selected-task');}
+function selected(){return jobs.find(job=>job.id===selectedJob)||jobs[0]||null;}
+function counts(tasks){const out={};for(const task of Array.isArray(tasks)?tasks:[])out[task.state]=(out[task.state]||0)+1;return out;}
+function compactCounts(input){const order=['RUNNING','BLOCKED','FAILED','QUEUED','READY','WAITING','SUCCEEDED','CANCELLED'];return order.filter(state=>input[state]).map(state=>input[state]+' '+state).join(', ')||'No tasks';}
+function relativeTime(timestamp){if(!timestamp)return '—';const parsed=Date.parse(timestamp);if(!Number.isFinite(parsed))return value(timestamp);const seconds=Math.max(0,Math.round((Date.now()-parsed)/1000));if(seconds<60)return 'just now';if(seconds<3600)return Math.floor(seconds/60)+'m ago';if(seconds<86400)return Math.floor(seconds/3600)+'h ago';return Math.floor(seconds/86400)+'d ago';}
+function safePrUrl(repository,prNumber){if(typeof repository!=='string'||!Number.isInteger(prNumber)||prNumber<=0)return null;const parts=repository.split('/');if(parts.length!==2)return null;const [owner,repo]=parts;if(!owner||!repo||owner==='.'||owner==='..'||repo==='.'||repo==='..')return null;if(!/^[A-Za-z0-9-]+$/.test(owner)||!/^[A-Za-z0-9._-]+$/.test(repo))return null;return 'https://github.com/'+owner+'/'+repo+'/pull/'+prNumber;}
+function prField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('GitHub PR')));const line=element('p','detail-value');const url=safePrUrl(job.repository,job.prNumber);if(url){const link=document.createElement('a');link.href=url;link.target='_blank';link.rel='noopener noreferrer';link.textContent='PR #'+job.prNumber;line.append(link);}else line.append(text('unavailable'));box.append(line);return box;}
+function chatField(task){const box=element('div','detail-group');box.append(element('p','detail-label',text('Chat')));const line=element('p','detail-value');if(task.adapter==='chatgpt'&&typeof task.threadId==='string'&&task.threadId){const link=document.createElement('a');link.href='https://chatgpt.com/c/'+encodeURIComponent(task.threadId);link.target='_blank';link.rel='noopener noreferrer';link.textContent='Open chat';line.append(link);}else line.append(text('—'));box.append(line);return box;}
+function selectJob(id){selectedJob=id;selectedTaskId=null;rememberSelection();location.hash=id?'#/jobs/'+encodeURIComponent(id):'#/jobs';renderAll();}
+function filteredJobs(){return jobs.filter(job=>!selectedRepo||job.repository===selectedRepo);}
+function syncFilters(){
+  const repos=[...new Set(jobs.map(job=>job.repository).filter(Boolean))].sort();
+  const previousRepo=selectedRepo;
+  repoFilter.replaceChildren(new Option('All repos',''),...repos.map(repo=>new Option(repo,repo)));
+  selectedRepo=repos.includes(previousRepo)?previousRepo:'';
+  repoFilter.value=selectedRepo;
+}
+function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const button=document.createElement('button');button.type='button';button.className='job-button'+(isCompleteUnmerged(job)?' complete-unmerged':'');button.setAttribute('aria-current',String(job.id===selectedJob));button.title=job.title||job.id;button.addEventListener('click',()=>selectJob(job.id));const meta=element('span','job-meta');meta.append(element('span','badge '+value(job.state),text(job.state)),element('span','badge mode-'+value(job.executionMode||'fixed'),text(value(job.executionMode||'fixed').toUpperCase())),element('span',job.draft?'badge DRAFT':'',text(job.draft?'DRAFT':value(job.githubState||'UNKNOWN'))));if(isCompleteUnmerged(job))meta.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));meta.append(element('span','',text(job.repository||'unknown repo')),element('span','',text(relativeTime(job.updatedAt))));button.append(element('span','job-title',text('PR#'+value(job.prNumber)+': '+value(job.title||job.id))),meta,element('span','subtle',text(compactCounts(counts(job.tasks)))));jobList.append(element('li','',button));}}
+function taskNode(task,children,depth){const li=element('li');const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{selectedTaskId=task.id;rememberSelection();renderAll();});const id=element('span','task-id',text(task.id));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));li.append(row);const nested=children.get(task.id)||[];if(nested.length){const ul=element('ul','tree');for(const child of nested)ul.append(taskNode(child,children,depth+1));li.append(ul);}return li;}
+function buildTree(tasks){taskTree.replaceChildren();if(!Array.isArray(tasks)||!tasks.length){taskTree.append(element('li','empty',text('No tasks in durable state.')));return;}const known=new Set(tasks.map(task=>task.id));const children=new Map();const roots=[];for(const task of tasks){if(!task.parentTaskId||!known.has(task.parentTaskId))roots.push(task);else{const siblings=children.get(task.parentTaskId)||[];siblings.push(task);children.set(task.parentTaskId,siblings);}}for(const task of roots)taskTree.append(taskNode(task,children,0));}
+function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Number(task?.maxAttempts)||0;if(max>=3&&max%3===0)return attempt+' / 3×'+(max/3);return attempt+' / '+max;}
+function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Task',task.id),field('Kind',task.kind||'work'),field('State',task.state),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),chatField(task));if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));taskDetailRoot.append(groups);}
+function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent='— '+value(job.title||job.id);if(job.id!==selectedJob){selectedJob=job.id;selectedTaskId=null;rememberSelection();}const summary=element('div','job-summary');summary.append(field('GitHub state',job.githubState||'UNKNOWN'),field('Durable state',job.state),field('Execution mode',job.executionMode||'fixed'),field('Objective',job.objective||job.description||job.title),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(counts(job.tasks))));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);}
+function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();}
+function isCompleteUnmerged(job){return job.state==='COMPLETED'&&job.githubState==='OPEN';}
+function isTerminalJob(job){return ['COMPLETED','CANCELLED'].includes(job.state)||['MERGED','CLOSED'].includes(job.githubState);}
+function compareJobs(a,b){const mergePendingDelta=Number(isCompleteUnmerged(b))-Number(isCompleteUnmerged(a));if(mergePendingDelta)return mergePendingDelta;const terminalDelta=Number(isTerminalJob(a))-Number(isTerminalJob(b));return terminalDelta||String(b.updatedAt).localeCompare(String(a.updatedAt));}
+async function loadJSON(url){const response=await fetch(url);if(!response.ok)throw new Error(response.status+' '+response.statusText);return response.json();}
+function renderRateLimitStatus(status){
+  if(!status?.limited){rateLimitWarning.hidden=true;rateLimitWarning.textContent='';return;}
+  const until=status.cooldownUntil?new Date(status.cooldownUntil):null;
+  const suffix=until&&!Number.isNaN(until.getTime())?' Live GitHub refresh will retry after '+until.toLocaleTimeString()+'.':' Live GitHub refresh is temporarily paused.';
+  rateLimitWarning.textContent='GitHub API rate limit reached. Showing cached job data.'+suffix;
+  rateLimitWarning.hidden=false;
+}
+async function refreshStatus(){try{renderRateLimitStatus(await loadJSON('/api/status'));}catch{renderRateLimitStatus(null);}}
+async function refresh(force=false){jobsRefresh.disabled=true;jobsRefresh.textContent='Refreshing…';try{const discovered=await loadJSON('/api/jobs'+(force?'?refresh=1':''));jobs=Array.isArray(discovered)?discovered:[];jobs.sort(compareJobs);if(selectedJob&&!jobs.some(job=>job.id===selectedJob)){selectedJob=null;selectedTaskId=null;}if(!selectedJob){const match=location.hash.match(/^#\\/jobs\\/(.+)$/);const fromHash=match?decodeURIComponent(match[1]):null;selectedJob=jobs.some(job=>job.id===fromHash)?fromHash:(jobs[0]?.id||null);}rememberSelection();renderAll();connection.textContent='Live · durable state connected';connection.className='status-pill ok';}catch(error){connection.textContent='Error · durable state unavailable';connection.className='status-pill bad';jobList.replaceChildren(element('li','error-state',text('Could not load jobs: '+error.message)));}finally{jobsRefresh.disabled=false;jobsRefresh.textContent='Refresh';}}
+function addEvent(event,level){if(!event||selectedJob&&event.job_id&&event.job_id!==selectedJob)return;const item=element('li','event-item');const meta=element('div','event-meta');meta.append(element('span','event-kind',text(event.type||'event')),element('span','',text(relativeTime(event.timestamp))),element('span','',text('task: '+value(event.task_id))));item.append(meta);const message=element('p','event-message',text(event.message||'Event received'));if(level==='error'||event.level==='error')message.classList.add('error-text');item.append(message);eventFeed.querySelector('.empty')?.remove();eventFeed.prepend(item);while(eventFeed.children.length>MAX_EVENTS)eventFeed.lastElementChild?.remove();}
+function usageBar(label,windowData){const percent=Math.max(0,Math.min(100,100-windowData.usedPercent));const row=element('div','usage-row');const heading=element('div','usage-label');heading.append(element('span','',text(label)),element('span','',text(Math.round(percent)+'%')));const track=element('div','usage-track');track.setAttribute('role','progressbar');track.setAttribute('aria-label',label+' available');track.setAttribute('aria-valuemin','0');track.setAttribute('aria-valuemax','100');track.setAttribute('aria-valuenow',String(percent));const fill=element('div','usage-fill');fill.style.width=percent+'%';track.append(fill);row.append(heading,track);return row;}
+function usageProvider(provider){const card=element('section','usage-provider');card.append(element('h3','',text(provider.label)));const usage=provider.usage||{};if(!usage.available||!usage.fiveHour||!usage.weekly){card.append(element('p','empty',text(usage.reason||'Account usage telemetry is unavailable.')));return card;}const bars=element('div','usage-bars');bars.append(usageBar('5-hour remaining',usage.fiveHour),usageBar('Weekly remaining',usage.weekly));card.append(bars);return card;}
+function formatCredit(value,currency){if(value===null||value===undefined||!Number.isFinite(Number(value)))return '—';const number=Number(value);if(currency==='USD')return '$'+number.toFixed(2);if(currency==='CNY')return '¥'+number.toFixed(2);return number.toFixed(2)+' '+currency;}
+function creditProvider(provider){const row=element('section','usage-provider');row.append(element('h3','',text(provider.label)));const credits=provider.credits||{};if(!credits.available||!Array.isArray(credits.balances)||!credits.balances.length){row.append(element('p','empty',text(credits.reason||'Credit balance is unavailable.')));return row;}const balance=credits.balances[0];row.append(element('div','detail-value',text(formatCredit(balance.remaining,balance.currency))));return row;}
+async function drawUsage(){try{const overview=await loadJSON('/api/usage');usageRoot.replaceChildren();usageMeta.textContent='Real account telemetry when available';const providers=Array.isArray(overview.providers)?overview.providers:[];const credits=Array.isArray(overview.credits)?overview.credits:[];if(!providers.length&&!credits.length){usageRoot.append(element('p','empty',text('Usage telemetry is unavailable.')));return;}const grid=element('div','usage-providers');for(const provider of providers)grid.append(usageProvider(provider));for(const provider of credits)grid.append(creditProvider(provider));usageRoot.append(grid);}catch(error){usageMeta.textContent='Unavailable';usageRoot.replaceChildren(element('p','error-state',text('Usage unavailable: '+error.message)));}}
+function showView(view){const isJobs=view==='jobs';jobsView.hidden=!isJobs;jobsWorkspace.hidden=!isJobs;usageView.hidden=isJobs;jobsTab.setAttribute('aria-selected',String(isJobs));usageTab.setAttribute('aria-selected',String(!isJobs));if(isJobs)void refresh();else void drawUsage();}
+jobsTab.addEventListener('click',()=>{location.hash=selectedJob?'#/jobs/'+encodeURIComponent(selectedJob):'#/jobs';showView('jobs');});
+jobsRefresh.addEventListener('click',()=>void refresh(true));
+repoFilter.addEventListener('change',()=>{selectedRepo=repoFilter.value;sessionStorage.setItem('agents-relay:repo-filter',selectedRepo);renderJobList();});
+selectedJobRefresh.addEventListener('click',()=>void refreshSelected());
+usageTab.addEventListener('click',()=>{location.hash='#/usage';showView('usage');});
+window.addEventListener('keydown',event=>{if(event.key==='Tab'&&event.altKey){event.preventDefault();showView(location.hash==='#/usage'?'jobs':'usage');}});
+function parseMessage(message){try{return JSON.parse(message.data);}catch{return null;}}
+const stream=new EventSource('/events');
+stream.onopen=()=>{connection.textContent='Live · event stream connected';connection.className='status-pill ok';};
+stream.onerror=()=>{connection.textContent='Degraded · event stream reconnecting';connection.className='status-pill warn';};
+stream.onmessage=message=>{const payload=parseMessage(message);if(payload?.job){const index=jobs.findIndex(job=>job.id===payload.job.id);if(index>=0)jobs[index]=payload.job;else jobs.push(payload.job);renderAll();}};
+stream.addEventListener('relay',message=>{const payload=parseMessage(message);if(payload?.job){const index=jobs.findIndex(job=>job.id===payload.job.id);if(index>=0)jobs[index]=payload.job;else jobs.push(payload.job);}if(payload?.event)addEvent(payload.event);renderAll();});
+if(location.hash==='#/usage')showView('usage');else showView('jobs');
+setInterval(()=>{if(location.hash!=='#/usage')void refresh();},300000);
+setInterval(()=>{if(location.hash==='#/usage')void drawUsage();},30000);
+async function refreshSelected(){if(!selectedJob){await refresh();return;}selectedJobRefresh.disabled=true;selectedJobRefresh.textContent='Refreshing…';try{const updated=await loadJSON('/api/job?id='+encodeURIComponent(selectedJob));const index=jobs.findIndex(job=>job.id===selectedJob);if(index>=0)jobs[index]=updated;else jobs.push(updated);rememberSelection();renderAll();connection.textContent='Live · durable state connected';connection.className='status-pill ok';}catch(error){connection.textContent='Error · durable state unavailable';connection.className='status-pill bad';}finally{selectedJobRefresh.disabled=false;selectedJobRefresh.textContent='Refresh';}}
+</script>
+</body>
+</html>`;
+export function serveDashboard(
+  store: DurableStore,
+  port = 8787,
+  bus?: EventBus,
+  refreshMs = 300000,
+  jobId?: string,
+  usageRegistry?: UsageRegistry,
+  overviewProvider?: (forceRefresh?: boolean) => Promise<ManagedJobOverview[]>,
+  webhook?: { secret: string; repositories: ReadonlySet<string>; pullRequest?: number; wake: (event: import('./github-webhook.js').GitHubWebhookWake) => void | Promise<void> },
+  statusProvider?: () => { limited: boolean; cooldownUntil: string | null },
+  exactJobProvider?: (jobId: string) => Promise<Job | null>,
+): Server {
+  const webhookDeliveries = new DeliveryDeduper();
+  const clients = new Set<import('node:http').ServerResponse>();
+  const subscribedJobs = new Set<string>();
+  let lastKnownJobs: Array<Job & { githubState?: string; mergedAt?: string | null; closedAt?: string | null; draft?: boolean }> | null = null;
+  const discoveredJobs = async (forceRefresh = false) => {
+    try {
+      const jobs = overviewProvider
+        ? (await overviewProvider(forceRefresh)).map(item => ({ ...item.job, githubState: item.githubState, mergedAt: item.mergedAt, closedAt: item.closedAt, draft: item.draft }))
+        : jobId ? [await store.load(jobId)] : [];
+      lastKnownJobs = jobs;
+      return jobs;
+    } catch (error) {
+      if (lastKnownJobs) return lastKnownJobs;
+      if (jobId) {
+        try {
+          const job = await store.load(jobId);
+          lastKnownJobs = [job];
+          return lastKnownJobs;
+        } catch { /* durable backend unavailable too */ }
+      }
+      throw error;
+    }
+  };
+  const subscribeDiscovered = async (): Promise<void> => {
+    if (!bus) return;
+    const jobs = await discoveredJobs().catch(() => []);
+    for (const job of jobs) {
+      if (subscribedJobs.has(job.id)) continue;
+      subscribedJobs.add(job.id);
+      try {
+        await bus.subscribe(job.id, async event => {
+          const current = (await discoveredJobs()).find(candidate => candidate.id === job.id) ?? job;
+          const payload = JSON.stringify({ event, job: current });
+          for (const client of clients) client.write(`event: relay\ndata: ${payload}\n\n`);
+        });
+      } catch {
+        subscribedJobs.delete(job.id);
+      }
+    }
+  };
+  const snapshot = async (requestedJobId = jobId, forceRefresh = false): Promise<{ id: string; json: string }> => {
+    await subscribeDiscovered();
+    if (overviewProvider) {
+      if (forceRefresh && requestedJobId && exactJobProvider) {
+        const exact = await exactJobProvider(requestedJobId);
+        if (exact) return { id: exact.id, json: JSON.stringify(exact) };
+      }
+      const candidates = await discoveredJobs();
+      const job = requestedJobId ? candidates.find(candidate => candidate.id === requestedJobId) : candidates[0];
+      if (!job) throw new Error(`Managed job ${requestedJobId ?? ''} not found`);
+      return { id: job.id, json: JSON.stringify(job) };
+    }
+    if (!jobId) throw new Error('Dashboard requires a durable job id');
+    if (requestedJobId !== jobId) throw new Error(`Managed job ${requestedJobId ?? ''} not found`);
+    return { id: jobId, json: JSON.stringify(await store.load(jobId)) };
+  };
+  const usage = async (): Promise<string> => {
+    if (!usageRegistry) throw new Error('Account usage telemetry is unavailable');
+    return JSON.stringify(await usageRegistry.snapshot());
+  };
+  const server = createServer(async (req, res) => {
+    if (req.url === '/') {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      res.end(dashboardHtml);
+      return;
+    }
+    if (req.url === '/webhooks/github' && req.method === 'POST') {
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      const body = Buffer.concat(chunks);
+      const signature = typeof req.headers['x-hub-signature-256'] === 'string' ? req.headers['x-hub-signature-256'] : undefined;
+      if (!webhook || !verifyGitHubWebhook(webhook.secret, body, signature)) { res.writeHead(401); res.end('Invalid signature'); return; }
+      const event = parseGitHubWebhook(req.headers, body);
+      if (!event) { res.writeHead(202); res.end('Ignored'); return; }
+      if (!event.repository || !webhook.repositories.has(event.repository) || (webhook.pullRequest !== undefined && event.pullRequest !== null && event.pullRequest !== webhook.pullRequest)) { res.writeHead(202); res.end('Ignored'); return; }
+      if (!webhookDeliveries.accept(event.deliveryId)) { res.writeHead(202); res.end('Duplicate'); return; }
+      res.writeHead(202); res.end('Accepted');
+      queueMicrotask(() => { void webhook.wake(event); });
+      return;
+    }
+    if (new URL(req.url ?? '/', 'http://127.0.0.1').pathname === '/api/jobs') {
+      try {
+        await subscribeDiscovered();
+        const forceRefresh = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('refresh') === '1';
+        const jobs = await discoveredJobs(forceRefresh);
+        if (!res.headersSent) res.writeHead(200, { 'content-type': 'application/json' });
+        if (!res.writableEnded) res.end(JSON.stringify(jobs));
+      } catch (error) {
+        if (!res.headersSent) res.writeHead(502);
+        if (!res.writableEnded) res.end(error instanceof Error ? error.message : String(error));
+      }
+      return;
+    }
+    if (new URL(req.url ?? '/', 'http://127.0.0.1').pathname === '/api/job') {
+      try {
+        const requestedJobId = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('id') ?? undefined;
+        const body = (await snapshot(requestedJobId, true)).json;
+        if (!res.headersSent) res.writeHead(200, { 'content-type': 'application/json' });
+        if (!res.writableEnded) res.end(body);
+      } catch (error) {
+        if (!res.headersSent) res.writeHead(404);
+        if (!res.writableEnded) res.end(error instanceof Error ? error.message : String(error));
+      }
+      return;
+    }
+    if (req.url === '/api/status') {
+      const status = statusProvider ? statusProvider() : { limited: false, cooldownUntil: null };
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify(status));
+      return;
+    }
+    if (req.url === '/api/usage') {
+      try {
+        const body = await usage();
+        if (!res.headersSent) res.writeHead(200, { 'content-type': 'application/json' });
+        if (!res.writableEnded) res.end(body);
+      } catch (error) {
+        if (!res.headersSent) res.writeHead(503);
+        if (!res.writableEnded) res.end(error instanceof Error ? error.message : String(error));
+      }
+      return;
+    }
+    if (req.url === '/events') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      clients.add(res);
+      res.flushHeaders();
+      res.write(': connected\n\n');
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+    res.writeHead(404);
+    res.end('Not found');
+  });
+  const interval = setInterval(() => {
+    if (clients.size === 0) return;
+    void snapshot().then(value => {
+      for (const client of clients) client.write(`data: ${value.json}\n\n`);
+    }).catch(() => undefined);
+  }, Math.max(10000, refreshMs));
+  interval.unref();
+  const heartbeat = setInterval(() => {
+    if (clients.size === 0) return;
+    for (const client of clients) client.write(': heartbeat\n\n');
+  }, SSE_HEARTBEAT_MS);
+  heartbeat.unref();
+  server.on('close', () => { clearInterval(interval); clearInterval(heartbeat); clients.clear(); });
+  server.listen(port, '127.0.0.1');
+  return server;
+}

package/src/events.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import { randomUUID } from 'node:crypto';
+import { EventRecord } from './types.js';
+import type { NatsConnection, Subscription } from 'nats';
+type NatsModule = typeof import('nats');
+export interface EventBus { publish(event: EventRecord): Promise<void>; subscribe(jobId: string, wake: (event: EventRecord) => Promise<void>): Promise<() => Promise<void>>; subscribeAll(wake: (event: EventRecord) => Promise<void>): Promise<() => Promise<void>>; }
+export function subjectToken(value: string): string { if (!/^[A-Za-z0-9_-]+$/.test(value)) throw new Error(`Unsafe event subject token: ${value}`); return value; }
+export class MemoryEventBus implements EventBus {
+  private readonly handlers = new Map<string, Set<(event: EventRecord) => Promise<void>>>();
+  async publish(event: EventRecord): Promise<void> { for (const handler of [...(this.handlers.get(event.job_id) ?? []), ...(this.handlers.get('*') ?? [])]) await handler(event); }
+  async subscribe(jobId: string, wake: (event: EventRecord) => Promise<void>): Promise<() => Promise<void>> { const set = this.handlers.get(jobId) ?? new Set(); set.add(wake); this.handlers.set(jobId, set); return async () => { set.delete(wake); }; }
+  async subscribeAll(wake: (event: EventRecord) => Promise<void>): Promise<() => Promise<void>> { const key = '*'; const set = this.handlers.get(key) ?? new Set(); set.add(wake); this.handlers.set(key, set); return async () => { set.delete(wake); }; }
+}
+export class NatsEventBus implements EventBus {
+  private connection: NatsConnection | null = null;
+  private module: NatsModule | null = null;
+  constructor(private readonly url = 'nats://127.0.0.1:4222', private readonly subjectPrefix = 'agents-relay.events.job') { if (!/^[A-Za-z0-9_.-]+$/.test(subjectPrefix)) throw new Error(`Unsafe event subject prefix: ${subjectPrefix}`); }
+  private async moduleLoaded(): Promise<NatsModule> { this.module ??= await import('nats'); return this.module; }
+  private async client(): Promise<NatsConnection> { const nats = await this.moduleLoaded(); this.connection ??= await nats.connect({ servers: this.url }); return this.connection; }
+  async publish(event: EventRecord): Promise<void> { const nats = await this.moduleLoaded(); const subject = `${this.subjectPrefix}.${subjectToken(event.job_id)}.${event.type}`; (await this.client()).publish(subject, nats.StringCodec().encode(JSON.stringify(event))); }
+  async subscribe(jobId: string, wake: (event: EventRecord) => Promise<void>): Promise<() => Promise<void>> { return this.subscribeSubject(`${this.subjectPrefix}.${subjectToken(jobId)}.>`, wake); }
+  async subscribeAll(wake: (event: EventRecord) => Promise<void>): Promise<() => Promise<void>> { return this.subscribeSubject(`${this.subjectPrefix}.>`, wake); }
+  private async subscribeSubject(subject: string, wake: (event: EventRecord) => Promise<void>): Promise<() => Promise<void>> { const nats = await this.moduleLoaded(); const codec = nats.StringCodec(); const subscription: Subscription = (await this.client()).subscribe(subject); let active = true; void (async () => { for await (const message of subscription) { if (!active) break; try { await wake(JSON.parse(codec.decode(message.data)) as EventRecord); } catch { /* malformed events never become durable state */ } } })(); return async () => { active = false; subscription.unsubscribe(); }; }
+}
+export function eventFor(jobId: string, taskId: string, parentTaskId: string | null, type: string, status: string, message: string, visibility: string = 'orchestrator', data?: Record<string, unknown>): EventRecord { return { version: 1, event_id: randomUUID(), job_id: jobId, task_id: taskId, parent_task_id: parentTaskId, type, status, timestamp: new Date().toISOString(), visibility, level: status === 'failed' || status === 'blocked' ? 'error' : 'info', message, data }; }

package/src/github-auth.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { readFile } from 'node:fs/promises';
+import { GhApiClient, GitHubAppAuthOptions } from './store.js';
+function value(args: readonly string[], name: string): string {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] ?? '' : '';
+}
+export type GitHubAuthContext = { client: GhApiClient; trustedAuthors: Set<string>; appAuth: boolean };
+export type GitHubAppConfig = { appId: string; installationId: string; privateKeyFile: string };
+export function githubAppConfig(args: readonly string[], env: NodeJS.ProcessEnv = process.env): GitHubAppConfig | null {
+  const appId = value(args, '--github-app-id') || env.AGENTS_RELAY_GITHUB_APP_ID || '';
+  const installationId = value(args, '--github-app-installation-id') || env.AGENTS_RELAY_GITHUB_APP_INSTALLATION_ID || '';
+  const privateKeyFile = value(args, '--github-app-private-key-file') || env.AGENTS_RELAY_GITHUB_APP_PRIVATE_KEY_FILE || '';
+  const configured = [appId, installationId, privateKeyFile].filter(Boolean).length;
+  if (configured === 0) return null;
+  if (configured !== 3) throw new Error('GitHub App auth requires app id, installation id, and private key file');
+  return { appId, installationId, privateKeyFile };
+}
+export async function githubAuthContext(args: readonly string[], env: NodeJS.ProcessEnv = process.env): Promise<GitHubAuthContext> {
+  const config = githubAppConfig(args, env);
+  let options: GitHubAppAuthOptions | null = null;
+  if (config) options = { appId: config.appId, installationId: config.installationId, privateKey: await readFile(config.privateKeyFile, 'utf8') };
+  const client = new GhApiClient(options);
+  const trustedAuthors = new Set<string>();
+  trustedAuthors.add(await client.currentLogin());
+  for (const author of (value(args, '--trusted-authors') || env.AGENTS_RELAY_TRUSTED_AUTHORS || '').split(',').map(item => item.trim()).filter(Boolean)) trustedAuthors.add(author);
+  if (options) {
+    const local = await client.localLogin();
+    if (local) trustedAuthors.add(local);
+  }
+  return { client, trustedAuthors, appAuth: options !== null };
+}

package/src/github-webhook.ts ADDED Viewed

@@ -0,0 +1,37 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { IncomingHttpHeaders } from 'node:http';
+export type GitHubWebhookWake = { deliveryId: string; event: string; action: string | null; repository: string | null; pullRequest: number | null };
+const WAKE_EVENTS = new Set(['pull_request', 'issue_comment', 'pull_request_review', 'pull_request_review_comment', 'check_run', 'check_suite', 'workflow_run']);
+export function verifyGitHubWebhook(secret: string, body: Buffer, signature: string | undefined): boolean {
+  if (!secret || !signature?.startsWith('sha256=')) return false;
+  const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(body).digest('hex'));
+  const actual = Buffer.from(signature);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+export function parseGitHubWebhook(headers: IncomingHttpHeaders, body: Buffer): GitHubWebhookWake | null {
+  const deliveryId = String(headers['x-github-delivery'] ?? '');
+  const event = String(headers['x-github-event'] ?? '');
+  if (!deliveryId || !WAKE_EVENTS.has(event)) return null;
+  let payload: Record<string, unknown>;
+  try { payload = JSON.parse(body.toString('utf8')) as Record<string, unknown>; } catch { return null; }
+  const repository = payload.repository as Record<string, unknown> | undefined;
+  const pullRequest = payload.pull_request as Record<string, unknown> | undefined;
+  const issue = payload.issue as Record<string, unknown> | undefined;
+  const number = Number(pullRequest?.number ?? (issue?.pull_request ? issue.number : 0));
+  return { deliveryId, event, action: typeof payload.action === 'string' ? payload.action : null, repository: typeof repository?.full_name === 'string' ? repository.full_name : null, pullRequest: Number.isInteger(number) && number > 0 ? number : null };
+}
+export class DeliveryDeduper {
+  private readonly seen = new Map<string, number>();
+  constructor(private readonly ttlMs = 86400000, private readonly maxEntries = 10000) {}
+  accept(id: string, now = Date.now()): boolean {
+    for (const [key, expires] of this.seen) if (expires <= now) this.seen.delete(key);
+    if (this.seen.has(id)) return false;
+    this.seen.set(id, now + this.ttlMs);
+    while (this.seen.size > this.maxEntries) this.seen.delete(this.seen.keys().next().value as string);
+    return true;
+  }
+}

package/src/markers.ts ADDED Viewed

@@ -0,0 +1,33 @@
+import { AgentRegistration, Job, Task } from './types.js';
+export const JOB_MARKER = 'agents-relay:job:v1';
+export const TASK_MARKER = 'agents-relay:task:v1';
+export const AGENT_MARKER = 'agents-relay:agent:v1';
+export function marker(label: string, value: unknown): string { return `<!-- ${label} ${JSON.stringify(value)} -->`; }
+export function parseMarker<T>(body: string, label: string): T | null {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const startMatch = body.match(new RegExp(`<!--\\s*${escaped}\\s+`));
+  if (!startMatch || startMatch.index === undefined) return null;
+  const payloadStart = startMatch.index + startMatch[0].length;
+  let end = body.indexOf('-->', payloadStart);
+  while (end !== -1) {
+    const candidate = body.slice(payloadStart, end).trim();
+    try { return JSON.parse(candidate) as T; } catch { end = body.indexOf('-->', end + 3); }
+  }
+  return null;
+}
+export function renderJobComment(job: Job): string { return `${marker(JOB_MARKER, { ...job, tasks: undefined })}\n# Agents Relay job: ${job.title}\nState: ${job.state}\nPR: #${job.prNumber}`; }
+export function renderTaskComment(task: Task): string { return `${marker(TASK_MARKER, task)}\n## Task ${task.id}\nState: ${task.state}\n${task.result?.summary ?? task.input}`; }
+export function parseJob(body: string): Job | null {
+  const job = parseMarker<Job>(body, JOB_MARKER);
+  if (!job) return null;
+  if (job.executionMode === undefined) return { ...job, executionMode: 'fixed' };
+  if (job.executionMode !== 'fixed' && job.executionMode !== 'autonomous') return null;
+  return job;
+}
+export function parseTask(body: string): Task | null {
+  const task = parseMarker<Task>(body, TASK_MARKER);
+  if (!task) return null;
+  return { ...task, kind: task.kind === 'planner' ? 'planner' : 'work' };
+}
+export function renderAgentComment(agent: AgentRegistration): string { return `${marker(AGENT_MARKER, agent)}\n## Registered agent ${agent.name}\nRole: ${agent.role}\nAvailability: ${agent.availability}`; }
+export function parseAgent(body: string): AgentRegistration | null { return parseMarker<AgentRegistration>(body, AGENT_MARKER); }