agents-relay 1.0.75 → 1.0.77

package/README.md

@@ -135,6 +135,8 @@ events, durable-thread reuse, resume, or retry behavior.
 
 Open the dashboard on localhost port 8787. The marker format is intentionally public and append-friendly; the CLI uses GitHubStore with the authenticated gh client in operational mode.
 
+External product feedback uses the reusable `src/feedback.ts` contract. See [docs/feedback-intake.md](docs/feedback-intake.md) for the schema, attachment limits, privacy rules, materialization path, and provenance envelope for later Jobs/Tasks/PRs.
+
 reconcile leases and launches ready tasks without waiting inside the runtime scheduler; the CLI waits only long enough for its launched workers to persist results. agents-relayd (or the equivalent npx agents-relay serve) is the watchdog/dashboard mode. Model-backed workers require --events nats; the event transport carries authoritative terminal worker events as well as wake/progress traffic. See [docs/service.md](docs/service.md). --file PATH is explicit local demo/test mode only.
 
 `agents-relayd` without `--pr`/`--id` runs in workspace mode by default: it discovers nested Git repositories under `~/Workspace`, keeps only GitHub `origin` remotes, and aggregates their managed PR jobs into one dashboard and worker pool. Pass `--workspace PATH` to use another root. `--repo OWNER/REPO` remains the single-repository pool mode.

package/dist/dashboard.js

@@ -80,6 +80,7 @@ export const dashboardHtml = `<!doctype html>
     .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; }
+    .job-search { width:190px; max-width:28vw; border:1px solid var(--border); border-radius:.35rem; background:var(--surface); color:var(--text); padding:.27rem .45rem; font:inherit; font-size:.72rem; }
     .quick-filter { border:1px solid var(--border); border-radius:.35rem; background:var(--surface); color:var(--muted); padding:.27rem .42rem; font:inherit; font-size:.7rem; font-weight:750; cursor:pointer; }
     .quick-filter[aria-pressed="true"] { border-color:var(--accent); background:var(--accent2); color:var(--accent); }
     .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; }
@@ -125,6 +126,12 @@ export const dashboardHtml = `<!doctype html>
     .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; }
     .task-actions { display:flex; justify-content:flex-end; gap:.25rem; margin-bottom:.5rem; }
+    .task-link { color:var(--accent); font-weight:700; }
+    .agent-graph { display:grid; gap:.45rem; margin-top:.55rem; padding:.55rem; border:1px solid var(--border); border-radius:.4rem; background:var(--surface2); overflow:auto; }
+    .agent-wave { display:flex; align-items:center; gap:.4rem; min-width:max-content; }
+    .agent-node { padding:.32rem .48rem; border:1px solid var(--border); border-radius:.35rem; background:var(--surface); font:.73rem ui-monospace,SFMono-Regular,Menlo,monospace; }
+    .agent-arrow { color:var(--muted); font-weight:800; }
+    .agent-graph-source { margin:.1rem 0 0; padding:.45rem; border-radius:.35rem; background:var(--surface); color:var(--muted); font:.7rem/1.45 ui-monospace,SFMono-Regular,Menlo,monospace; white-space:pre; overflow:auto; }
     .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; }
@@ -159,7 +166,7 @@ export const dashboardHtml = `<!doctype html>
 </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="quick-status" class="job-filter" aria-label="Filter jobs by derived status"><option value="">STATUS</option></select><button id="quick-autonomous" class="quick-filter" type="button" aria-pressed="false">AUTONOMOUS</button><button id="quick-draft" class="quick-filter" type="button" aria-pressed="false">DRAFT</button><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-head"><h2>Jobs</h2><div class="panel-actions"><div class="job-filters"><input id="job-search" class="job-search" type="search" placeholder="Search title or PR #" aria-label="Search jobs by title or PR number"><select id="quick-status" class="job-filter" aria-label="Filter jobs by derived status"><option value="">STATUS</option></select><button id="quick-autonomous" class="quick-filter" type="button" aria-pressed="false">AUTONOMOUS</button><button id="quick-draft" class="quick-filter" type="button" aria-pressed="false">DRAFT</button><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">
@@ -207,6 +214,7 @@ 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 jobSearch=document.querySelector('#job-search');
 const repoFilter=document.querySelector('#repo-filter');
 const quickStatus=document.querySelector('#quick-status');
 const quickAutonomous=document.querySelector('#quick-autonomous');
@@ -229,6 +237,7 @@ let selectedTaskId=sessionStorage.getItem('agents-relay:selected-task');
 let selectedRepo=sessionStorage.getItem('agents-relay:repo-filter')||'';
 let quickMode=sessionStorage.getItem('agents-relay:quick-filter')||'jobs';
 let selectedRuntimeStatus=sessionStorage.getItem('agents-relay:runtime-status-filter')||'';
+let searchQuery=sessionStorage.getItem('agents-relay:job-search')||'';
 let eventTaskId=selectedTaskId;
 const displayedEventIds=new Set();
 
@@ -245,12 +254,17 @@ function relativeTime(timestamp){if(!timestamp)return '—';const parsed=Date.pa
 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 taskCommentField(task){const box=element('div','detail-group');box.append(element('p','detail-label',text('PR comment')));const line=element('p','detail-value');if(typeof task.taskUrl==='string'&&task.taskUrl.startsWith('https://github.com/')){const link=document.createElement('a');link.className='task-link';link.href=task.taskUrl;link.target='_blank';link.rel='noopener noreferrer';link.textContent='Open task comment';line.append(link);}else line.append(text('—'));box.append(line);return box;}
+function parseAgentGraphSource(source){if(typeof source!=='string'||!source.trim())return null;const agents=new Map(),edges=[];for(const raw of source.split(/\\r?\\n/)){const line=raw.trim();if(!line||line.startsWith('%%')||line.startsWith('flowchart '))continue;let match=line.match(/^([A-Za-z_][A-Za-z0-9_.-]*)(?:\\[agent:([A-Za-z_][A-Za-z0-9_.-]*)\\])?\\s*-->\\s*([A-Za-z_][A-Za-z0-9_.-]*)(?:\\[agent:([A-Za-z_][A-Za-z0-9_.-]*)\\])?$/);if(match){agents.set(match[1],match[2]||agents.get(match[1])||match[1]);agents.set(match[3],match[4]||agents.get(match[3])||match[3]);edges.push([match[1],match[3]]);continue;}match=line.match(/^([A-Za-z_][A-Za-z0-9_.-]*)\\[agent:([A-Za-z_][A-Za-z0-9_.-]*)\\]$/);if(match){agents.set(match[1],match[2]);continue;}return null;}const incoming=new Map([...agents.keys()].map(id=>[id,0]));for(const [,to] of edges)incoming.set(to,(incoming.get(to)||0)+1);const remaining=new Map(incoming),waves=[];let ready=[...remaining].filter(([,degree])=>degree===0).map(([id])=>id).sort();while(ready.length){waves.push(ready);const next=[];for(const id of ready)for(const [from,to] of edges)if(from===id){const degree=(remaining.get(to)||0)-1;remaining.set(to,degree);if(degree===0)next.push(to);}ready=[...new Set(next)].sort();}return {agents,waves};}
+function agentGraphField(task){if(typeof task.agentGraph!=='string'||!task.agentGraph.trim())return null;const box=element('div','detail-group');box.style.gridColumn='1 / -1';box.append(element('p','detail-label',text('Task agent graph')));const graph=element('div','agent-graph');const parsed=parseAgentGraphSource(task.agentGraph);if(parsed&&parsed.waves.length){parsed.waves.forEach((wave,index)=>{const row=element('div','agent-wave');if(index>0)row.append(element('span','agent-arrow',text('↓')));for(const id of wave)row.append(element('span','agent-node',text(id+' · '+(parsed.agents.get(id)||id))));graph.append(row);});}const source=document.createElement('pre');source.className='agent-graph-source';source.textContent=task.agentGraph;graph.append(source);box.append(graph);return box;}
 function clearEvents(){displayedEventIds.clear();eventFeed.replaceChildren(element('li','empty',text('Waiting for events.')));}
 async function loadEventHistory(){if(!selectedJob){clearEvents();return;}const params=new URLSearchParams({job:selectedJob,limit:String(MAX_EVENTS)});if(eventTaskId)params.set('task',eventTaskId);try{const history=await loadJSON('/api/events?'+params.toString());clearEvents();for(const event of Array.isArray(history)?history.slice().reverse():[])addEvent(event);}catch{clearEvents();}}
 function selectJob(id){selectedJob=id;selectedTaskId=null;eventTaskId=null;rememberSelection();clearEvents();location.hash=id?'#/jobs/'+encodeURIComponent(id):'#/jobs';renderAll();void loadEventHistory();}
 function matchesQuickFilter(job){if(quickMode==='autonomous')return job.executionMode==='autonomous';if(quickMode==='draft')return job.draft||job.state==='DRAFT';if(quickMode==='status')return !!selectedRuntimeStatus&&(job.runtimeStatus||'IDLE')===selectedRuntimeStatus;return true;}
-function filteredJobs(){return jobs.filter(job=>(!selectedRepo||job.repository===selectedRepo)&&matchesQuickFilter(job));}
+function matchesSearch(job){const query=searchQuery.trim().toLowerCase();if(!query)return true;const pr=String(job.prNumber||'');const normalized=query.replace(/^pr\s*#?/,'').replace(/^#/,'');return String(job.title||job.id||'').toLowerCase().includes(query)||pr.includes(normalized);}
+function filteredJobs(){return jobs.filter(job=>(!selectedRepo||job.repository===selectedRepo)&&matchesQuickFilter(job)&&matchesSearch(job));}
 function setQuickMode(mode,status=''){quickMode=mode;selectedRuntimeStatus=mode==='status'?status:'';sessionStorage.setItem('agents-relay:quick-filter',quickMode);if(selectedRuntimeStatus)sessionStorage.setItem('agents-relay:runtime-status-filter',selectedRuntimeStatus);else sessionStorage.removeItem('agents-relay:runtime-status-filter');syncFilters();renderJobList();}
+function toggleQuickMode(mode){setQuickMode(quickMode===mode?'jobs':mode);}
 function syncFilters(){
   const repos=[...new Set(jobs.map(job=>job.repository).filter(Boolean))].sort();
   const previousRepo=selectedRepo;
@@ -265,6 +279,7 @@ function syncFilters(){
   quickStatus.value=quickMode==='status'?selectedRuntimeStatus:'';
   quickAutonomous.setAttribute('aria-pressed',String(quickMode==='autonomous'));
   quickDraft.setAttribute('aria-pressed',String(quickMode==='draft'));
+  jobSearch.value=searchQuery;
 }
 function actionEnabled(job,action){if(action==='start')return job.state==='DRAFT'&&job.githubState!=='CLOSED'&&job.githubState!=='MERGED';if(action==='reconcile')return job.state==='ACTIVE'&&job.githubState==='OPEN';if(action==='cancel')return job.state!=='COMPLETED'&&job.state!=='CANCELLED'&&job.githubState==='OPEN';return false;}
 function actionButton(job,action,label,icon){const button=document.createElement('button');button.type='button';button.className='job-action';button.textContent=icon;button.title=label;button.setAttribute('aria-label',label);button.disabled=!actionEnabled(job,action);button.addEventListener('click',event=>{event.stopPropagation();void runJobAction(job,action,button);});return button;}
@@ -278,7 +293,7 @@ function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Nu
 function taskActionEnabled(task,action){if(action==='retry')return ['FAILED','BLOCKED'].includes(task.state);if(action==='cancel')return ['DRAFT','QUEUED','BLOCKED','FAILED'].includes(task.state);return false;}
 function taskActionButton(task,action,label,icon){const button=document.createElement('button');button.type='button';button.className='job-action';button.textContent=icon;button.title=label;button.setAttribute('aria-label',label);button.disabled=!taskActionEnabled(task,action);button.addEventListener('click',()=>void runTaskAction(task,action,button));return button;}
 async function runTaskAction(task,action,button){const job=selected();if(!job)return;button.disabled=true;try{const response=await fetch('/api/task-action?id='+encodeURIComponent(job.id)+'&task='+encodeURIComponent(task.id)+'&action='+encodeURIComponent(action),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);const updated=await response.json();const index=jobs.findIndex(candidate=>candidate.id===job.id);if(index>=0)jobs[index]=updated;else jobs.push(updated);renderAll();void loadEventHistory();}catch(error){button.title=(action==='retry'?'Restart':'Cancel')+': '+error.message;}finally{renderAll();}}
-function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const actions=element('div','task-actions');actions.append(taskActionButton(task,'retry','Restart task','↻'),taskActionButton(task,'cancel','Cancel task','×'));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('Planning decision',task.planningDecisionId||'—'),field('Planning source',task.planningSource||'—'),field('Planning round',task.planningRound===undefined?'—':String(task.planningRound)),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(actions,groups);}
+function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const actions=element('div','task-actions');actions.append(taskActionButton(task,'retry','Restart task','↻'),taskActionButton(task,'cancel','Cancel task','×'));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('Planning decision',task.planningDecisionId||'—'),field('Planning source',task.planningSource||'—'),field('Planning round',task.planningRound===undefined?'—':String(task.planningRound)),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'),taskCommentField(task),chatField(task));const graph=agentGraphField(task);if(graph)groups.append(graph);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(actions,groups);}
 function reviewStatus(job){const review=job?.review;if(!review)return 'Not started';if(review.outcome==='approved'&&review.headSha===job.headSha)return 'MERGE READY · approved';const stale=Array.isArray(job?.tasks)&&job.tasks.some(task=>task.agentName==='reviewer'&&task.reviewHeadSha&&job.headSha&&task.reviewHeadSha!==job.headSha);if(stale)return 'STALE · awaiting review';return String(review.outcome||'pending').replace('_',' ').toUpperCase();}
 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;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('PR state',job.githubState||'UNKNOWN'),field('Lifecycle state',job.state),field('Runtime status',job.runtimeStatus||'IDLE'),field('Execution mode',job.executionMode||'fixed'),field('Review',reviewStatus(job)),field('Review head SHA',job.review?.headSha||job.headSha||'—'),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}
 function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();}
@@ -309,8 +324,9 @@ jobsTab.addEventListener('click',()=>{location.hash=selectedJob?'#/jobs/'+encode
 jobsRefresh.addEventListener('click',()=>void refresh(true));
 eventsAllTasks.addEventListener('click',()=>{eventTaskId=null;clearEvents();renderEventScope();void loadEventHistory();});
 repoFilter.addEventListener('change',()=>{selectedRepo=repoFilter.value;sessionStorage.setItem('agents-relay:repo-filter',selectedRepo);renderJobList();});
-quickAutonomous.addEventListener('click',()=>setQuickMode('autonomous'));
-quickDraft.addEventListener('click',()=>setQuickMode('draft'));
+jobSearch.addEventListener('input',()=>{searchQuery=jobSearch.value;sessionStorage.setItem('agents-relay:job-search',searchQuery);renderJobList();});
+quickAutonomous.addEventListener('click',()=>toggleQuickMode('autonomous'));
+quickDraft.addEventListener('click',()=>toggleQuickMode('draft'));
 quickStatus.addEventListener('change',()=>setQuickMode(quickStatus.value?'status':'jobs',quickStatus.value));
 selectedJobRefresh.addEventListener('click',()=>void refreshSelected());
 usageTab.addEventListener('click',()=>{location.hash='#/usage';showView('usage');});

package/dist/feedback.js

@@ -0,0 +1,234 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+export const FEEDBACK_MARKER = 'agents-relay:feedback:v1';
+export const FEEDBACK_SCHEMA = 'agents-relay.feedback';
+export const FEEDBACK_SCHEMA_VERSION = 1;
+export const FEEDBACK_MAX_TEXT_LENGTH = 20_000;
+export const FEEDBACK_MAX_ATTACHMENTS = 10;
+export const FEEDBACK_MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export const FEEDBACK_IMAGE_TYPES = ['image/gif', 'image/jpeg', 'image/png', 'image/webp'];
+export const DEFAULT_FEEDBACK_LIMITS = {
+    maxTextLength: 20_000,
+    maxAttachments: 5,
+    maxAttachmentBytes: 10 * 1024 * 1024,
+    allowedMediaTypes: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'],
+};
+function effectiveLimits(limits = {}) {
+    return {
+        maxTextLength: limits.maxTextLength ?? DEFAULT_FEEDBACK_LIMITS.maxTextLength,
+        maxAttachments: limits.maxAttachments ?? DEFAULT_FEEDBACK_LIMITS.maxAttachments,
+        maxAttachmentBytes: limits.maxAttachmentBytes ?? DEFAULT_FEEDBACK_LIMITS.maxAttachmentBytes,
+        allowedMediaTypes: limits.allowedMediaTypes ?? DEFAULT_FEEDBACK_LIMITS.allowedMediaTypes,
+    };
+}
+function fail(message) { throw new Error(`Invalid feedback: ${message}`); }
+function safeId(id) {
+    if (!/^[a-f0-9-]{36}$/i.test(id))
+        fail('feedback id is invalid');
+    return id;
+}
+function cleanFilename(filename) {
+    const cleaned = basename(filename).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120);
+    if (!cleaned || cleaned === '.' || cleaned === '..')
+        fail('attachment filename is invalid');
+    return cleaned;
+}
+function cleanOptional(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (value.length > 500)
+        fail(`${field} is too long`);
+    return value;
+}
+function validateProvenance(input) {
+    if (!input.product.trim())
+        fail('provenance.product is required');
+    if (!input.submittedAt || Number.isNaN(Date.parse(input.submittedAt)))
+        fail('provenance.submittedAt must be an ISO timestamp');
+    if (input.contact && !input.contact.value.trim())
+        fail('contact value must not be empty');
+    // Only the explicitly documented fields are copied. Upload/browser/provider metadata is never persisted.
+    return {
+        source: input.source,
+        product: input.product.trim().slice(0, 200),
+        surface: cleanOptional(input.surface, 'surface'),
+        setupStep: cleanOptional(input.setupStep, 'setupStep'),
+        actorClass: input.actorClass,
+        version: cleanOptional(input.version, 'version'),
+        build: cleanOptional(input.build, 'build'),
+        submittedAt: new Date(input.submittedAt).toISOString(),
+        ...(input.contact ? { contact: { channel: input.contact.channel, value: input.contact.value.trim().slice(0, 500) } } : {}),
+    };
+}
+export function marker(label, value) {
+    return `<!-- ${label} ${JSON.stringify(value).replace(/>/g, '\\u003e')} -->`;
+}
+export function renderFeedbackMarker(record) {
+    const { userContent: _userContent, ...metadata } = record;
+    return marker(FEEDBACK_MARKER, metadata);
+}
+export function parseFeedbackMarker(value) {
+    const match = value.match(/<!--\s*agents-relay:feedback:v1\s+([\s\S]*?)\s*-->/);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[1]);
+        return parsed.schema === FEEDBACK_MARKER && parsed.schemaVersion === FEEDBACK_SCHEMA_VERSION ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class FileFeedbackStore {
+    root;
+    limits;
+    constructor(root, limits = {}) {
+        this.root = resolve(root);
+        this.limits = effectiveLimits(limits);
+    }
+    async submit(submission) {
+        const existing = submission.idempotencyKey ? await this.findByIdempotencyKey(submission.idempotencyKey) : null;
+        if (existing)
+            return { record: existing, recordRef: this.recordPath(existing.id) };
+        const text = submission.text.trim();
+        if (!text)
+            fail('text is required');
+        if (text.length > this.limits.maxTextLength)
+            fail(`text exceeds ${this.limits.maxTextLength} characters`);
+        const inputs = submission.attachments ?? [];
+        if (inputs.length > this.limits.maxAttachments)
+            fail(`at most ${this.limits.maxAttachments} attachments are allowed`);
+        const now = new Date().toISOString();
+        const id = randomUUID();
+        const attachmentDir = join(this.root, 'attachments', id);
+        const attachments = [];
+        await mkdir(attachmentDir, { recursive: true });
+        try {
+            for (const input of inputs) {
+                if (!this.limits.allowedMediaTypes.includes(input.mediaType.toLowerCase()))
+                    fail(`unsupported attachment type: ${input.mediaType}`);
+                if (input.data.byteLength === 0 || input.data.byteLength > this.limits.maxAttachmentBytes)
+                    fail(`attachment exceeds ${this.limits.maxAttachmentBytes} bytes`);
+                const attachmentId = randomUUID();
+                const filename = cleanFilename(input.filename);
+                const relative = join('attachments', id, `${attachmentId}-${filename}`);
+                await writeFile(join(this.root, relative), input.data, { flag: 'wx' });
+                attachments.push({ id: attachmentId, filename, mediaType: input.mediaType.toLowerCase(), sizeBytes: input.data.byteLength, sha256: createHash('sha256').update(input.data).digest('hex'), storageRef: relative, uploadedAt: now });
+            }
+            const record = {
+                schema: FEEDBACK_MARKER, schemaVersion: FEEDBACK_SCHEMA_VERSION, id,
+                ...(submission.idempotencyKey ? { idempotencyKey: submission.idempotencyKey } : {}),
+                userContent: { text }, attachments, systemProvenance: validateProvenance(submission.provenance),
+                triage: { status: 'new', updatedAt: now }, downstream: [], createdAt: now,
+            };
+            await mkdir(join(this.root, 'records'), { recursive: true });
+            const recordRef = this.recordPath(id);
+            const temp = `${recordRef}.${randomUUID()}.tmp`;
+            await writeFile(temp, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+            await rename(temp, recordRef);
+            return { record, recordRef };
+        }
+        catch (error) {
+            await this.removeAttachmentDirectory(attachmentDir);
+            throw error;
+        }
+    }
+    async read(id) {
+        const parsed = JSON.parse(await readFile(this.recordPath(safeId(id)), 'utf8'));
+        if (parsed.schema !== FEEDBACK_MARKER || parsed.schemaVersion !== FEEDBACK_SCHEMA_VERSION)
+            fail('record schema is unsupported');
+        return parsed;
+    }
+    recordPath(id) { return join(this.root, 'records', `${id}.json`); }
+    async findByIdempotencyKey(key) {
+        const directory = join(this.root, 'records');
+        let entries;
+        try {
+            entries = await readdir(directory);
+        }
+        catch {
+            return null;
+        }
+        for (const entry of entries.filter(item => item.endsWith('.json'))) {
+            const record = JSON.parse(await readFile(join(directory, entry), 'utf8'));
+            if (record.idempotencyKey === key)
+                return record;
+        }
+        return null;
+    }
+    async removeAttachmentDirectory(path) {
+        try {
+            await rm(path, { recursive: true, force: true });
+        }
+        catch { /* best-effort cleanup; the record was not materialized */ }
+    }
+}
+export async function materializeFeedbackRecord(root, submission, limits) {
+    return new FileFeedbackStore(root, limits).submit(submission);
+}
+/** Redacts common bearer/API-key shapes before a product stores user text. */
+export function redactSensitiveText(text) {
+    return text
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [REDACTED]')
+        .replace(/\b(?:sk|pk)_[A-Za-z0-9_-]{12,}\b/g, '[REDACTED_KEY]')
+        .replace(/\b(?:api[_-]?key|token|secret)\s*[:=]\s*[^\s,;]+/gi, '$1=[REDACTED]');
+}
+export function createFeedbackRecord(submission, options = {}) {
+    if (typeof submission.text !== 'string' || submission.text.length === 0 || submission.text.length > FEEDBACK_MAX_TEXT_LENGTH)
+        fail(`text must contain 1-${FEEDBACK_MAX_TEXT_LENGTH} characters`);
+    const attachments = (submission.attachments ?? []).map((input, index) => {
+        if (!FEEDBACK_IMAGE_TYPES.includes(input.mimeType))
+            fail(`attachments[${index}] has an unsupported image format`);
+        if (!Number.isSafeInteger(input.sizeBytes) || input.sizeBytes <= 0 || input.sizeBytes > FEEDBACK_MAX_ATTACHMENT_BYTES)
+            fail(`attachments[${index}] exceeds the ${FEEDBACK_MAX_ATTACHMENT_BYTES} byte limit`);
+        if (!input.reference || input.reference.length > 2_000 || /[?#]/.test(input.reference) || /:\/\/[^/]*:[^@]+@/.test(input.reference))
+            fail('attachment reference must be a stable, credential-free reference');
+        return { ...input, id: `attachment-${index + 1}` };
+    });
+    if (attachments.length > FEEDBACK_MAX_ATTACHMENTS)
+        fail(`at most ${FEEDBACK_MAX_ATTACHMENTS} attachments are supported`);
+    const visibility = submission.visibility ?? 'private';
+    const sanitized = options.sanitize === true || submission.sanitized === true;
+    if (visibility === 'public' && !sanitized)
+        fail('public feedback must be explicitly sanitized');
+    const provenance = validateProvenance(submission.provenance);
+    return {
+        schema: FEEDBACK_SCHEMA, schemaVersion: FEEDBACK_SCHEMA_VERSION, id: options.id ?? `feedback-${randomUUID()}`,
+        userContent: { text: sanitized ? redactSensitiveText(submission.text) : submission.text }, attachments, provenance,
+        systemMetadata: { receivedAt: options.receivedAt ?? new Date().toISOString(), visibility, sanitized },
+        ...(submission.contact ? { contact: submission.contact } : {}), triage: { status: 'new' }, downstream: { work: [] },
+    };
+}
+export function feedbackWorkProvenance(record) {
+    return { feedbackId: record.id, feedbackSchema: `${record.schema}/v${record.schemaVersion}`, feedbackReference: `feedback://${record.id}`, feedbackSubmittedAt: record.provenance.submittedAt };
+}
+export function feedbackFingerprint(record) {
+    return createHash('sha256').update(JSON.stringify({ text: record.userContent.text, attachments: record.attachments.map(item => item.sha256 ?? item.reference), provenance: record.provenance })).digest('hex');
+}
+export function renderFeedbackMarkdown(record) {
+    const markerBody = { schema: record.schema, schemaVersion: record.schemaVersion, id: record.id, provenance: record.provenance, attachmentIds: record.attachments.map(item => item.id), triage: record.triage, downstream: record.downstream };
+    const attachments = record.attachments.length === 0 ? '_None._' : record.attachments.map(item => `- ${item.id}: ${item.mimeType}, ${item.sizeBytes} bytes, ref \`${item.reference}\``).join('\n');
+    return `${marker(FEEDBACK_MARKER, markerBody)}\n# Feedback ${record.id}\n\n## User report\n\n${record.userContent.text}\n\n## Attachments\n\n${attachments}\n`;
+}
+export async function materializeFeedback(first, second, third) {
+    if (typeof first === 'string')
+        return materializeFeedbackRecord(first, second, third);
+    const path = second;
+    const format = third ?? 'json';
+    if (!path || path.includes('\0'))
+        throw new Error('Feedback materialization path is invalid');
+    await mkdir(resolve(path, '..'), { recursive: true });
+    const body = format === 'markdown' ? renderFeedbackMarkdown(first) : `${JSON.stringify(first, null, 2)}\n`;
+    await writeFile(path, body, { encoding: 'utf8', mode: 0o600 });
+}
+export async function readFeedbackAttachment(root, attachment) {
+    const path = resolve(root, attachment.storageRef);
+    const rootPath = resolve(root);
+    if (!path.startsWith(`${rootPath}/`))
+        fail('attachment reference escapes storage root');
+    const bytes = await readFile(path);
+    if (bytes.byteLength !== attachment.sizeBytes || createHash('sha256').update(bytes).digest('hex') !== attachment.sha256)
+        fail('attachment integrity check failed');
+    return bytes;
+}

package/dist/markers.js

@@ -56,12 +56,14 @@ ${JOB_OBJECTIVE_END}`;
 }
 export function renderTaskComment(task) {
     const result = task.result?.summary?.trim() ? `\n\n### Result\n\n${task.result.summary.trim()}` : '';
+    const graph = task.agentGraph?.trim() ? `\n\n### Agent graph\n\n\`\`\`mermaid\n${task.agentGraph.trim()}\n\`\`\`` : '';
     const { input: _input, ...metadata } = task;
     return `${marker(TASK_MARKER, metadata)}
 ## Task: ${task.id}
 
 - **State:** ${task.state}
 - **Priority:** ${task.priority ?? 'P2'}
+${graph}
 
 ### Work
 

package/dist/store.js

@@ -5,7 +5,7 @@ export async function loadManagedGitHubPullRequestGraphql(client, repository, pr
     const [owner, name] = repository.split('/', 2);
     if (!owner || !name || !Number.isInteger(prNumber) || prNumber <= 0 || !client.graphql)
         return [];
-    const query = 'query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){state isDraft merged mergedAt closedAt body comments(last:100){nodes{author{login} body}}}}}';
+    const query = 'query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){state isDraft merged mergedAt closedAt body comments(last:100){nodes{databaseId url author{login} body}}}}}';
     const data = await client.graphql(query, { owner, name, number: prNumber });
     const repo = data.repository;
     const pr = repo?.pullRequest;
@@ -20,7 +20,14 @@ export async function loadManagedGitHubPullRequestGraphql(client, repository, pr
     const bodyJob = parseJob(typeof pr.body === 'string' ? pr.body : '');
     const commentJobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
     const jobs = bodyJob ? [bodyJob] : commentJobs;
-    const tasks = trusted.map(item => parseTask(String(item.body ?? ''))).filter((item) => item !== null);
+    const tasks = trusted.map(item => {
+        const row = item;
+        const task = parseTask(String(row.body ?? ''));
+        if (!task)
+            return null;
+        const taskUrl = typeof row.url === 'string' ? row.url : Number.isInteger(row.databaseId) ? `https://github.com/${repository}/pull/${prNumber}#issuecomment-${row.databaseId}` : undefined;
+        return taskUrl ? { ...task, taskUrl } : task;
+    }).filter((item) => item !== null);
     const state = String(pr.state ?? '').toUpperCase();
     const githubState = pr.merged === true ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';
     return jobs.map(job => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.75",
+  "version": "1.0.77",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {