Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .node-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
24
1 change: 1 addition & 0 deletions .nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
24
48 changes: 46 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ A job-search review workspace that keeps research, application history, and exac
- Consolidate repeated posting URLs while preserving source history.
- Keep interview notes and follow-ups without resetting application status.
- Accept an exact draft; changing the wording requires review again.
- Import a tracker CSV through explicit column mapping and a record preview. Source statuses remain research; existing Relay status and accepted drafts are preserved.
- Explore fictional example records; no real applicant data is included.

## Integrations
Expand All @@ -22,6 +23,7 @@ A job-search review workspace that keeps research, application history, and exac
- **[Notion](integrations/README.md)**: Read-only research import through the local command connector.
- **[Claude](integrations/README.md)**: Draft preparation through the Claude API with your own credentials.
- **[Grok Bot](integrations/GROK_BOT.md)**: Validated research and draft file exchange in the Bot's VM.
- **[Tracker CSV](integrations/README.md)**: Explicit column mapping and preview of a local comma-separated tracker file as research.

Integrations require explicit setup or file handoffs. Returned drafts require human review. No automatic application sending or background account sync is included.

Expand All @@ -34,6 +36,20 @@ Tracker CSV imports are also available through explicit column mapping and previ

[Development workflow](CONTRIBUTING.md) | [Delivery and review](docs/delivery.md) | [Team board](https://github.com/orgs/SyberLabs/projects/1)

## Why Relay

When another assistant rediscovers a role or rewrites a draft, you need to know what came before and whether the new text was actually reviewed. Relay makes those distinctions explicit:

- **Research keeps its history.** Matching posting URLs join the existing opportunity; changed source notes remain separate observations. Rediscovery preserves an existing interview or submitted status.
- **Acceptance belongs to the text.** An imported Ready label does not approve a new draft. Accept it in Relay; changing the accepted text requires another review.
- **Handoffs belong to a job and version.** Draft packets and editor checks reject stale work instead of silently replacing a newer review.
- **Bring the tools you already use.** Selected notes and validated files can supply research and drafts. Relay keeps the review record across those handoffs.

For example: import a role from Notion, prepare a draft with Claude, accept it, and later add an Obsidian research note for the same posting. The note adds context without replacing your draft or approving new wording. A later draft change needs review again.

This is Relay's product focus, not a claim of exclusive features or a proven advantage. Job tracking, AI writing, interview notes, and human review already exist elsewhere. Relay records acceptance inside its workspace; it does not verify every claim or prove which words were submitted to an employer. URL matching also cannot identify every repost across different job boards.


## GrokCell bot templates

For model-specific research practices, reusable handoffs, and a proposed evaluation plan, see [Context management for Relay](context-management/README.md). The guide distinguishes documented provider capabilities from Relay's implemented integrations.
Expand Down Expand Up @@ -63,6 +79,13 @@ The project, organization, personal profile and website share one [maintained pr
Node 24 and pnpm are required. From the repository root:

```sh
# .nvmrc / .node-version are `24`
nvm install && nvm use # or: fnm install && fnm use
# mise use node@24
# asdf install nodejs 24 && asdf set nodejs 24

node scripts/ensure-node.mjs # checks the running Node version; no Bash required
node -v # must be >= 24
pnpm install --frozen-lockfile
pnpm build
pnpm exec wrangler d1 execute DB --local --config dist/server/wrangler.json --persist-to .wrangler/state --file drizzle/0000_sticky_robbie_robertson.sql
Expand All @@ -71,7 +94,28 @@ pnpm exec wrangler d1 execute DB --local --config dist/server/wrangler.json --pe
pnpm dev
```

Open the local URL printed by the server. Local sign-in is simulated by the Sites development plugin; do not expose this development server to the internet. Load fictional examples or import your own records. The product introduction is at `/about`.
`pnpm dev` binds **http://localhost:3000/** (Vite `strictPort`). Use that URL. Miniflare/workerd may also print an internal `127.0.0.1:NNNN` bind — ignore it for the browser and curl.

`pnpm start` (after `pnpm build`) binds the built Worker at **http://127.0.0.1:8787/**.

Do not expose either server to the internet. Load fictional examples or import your own records. The product introduction is at `/about`.

### Local sign-in

On `pnpm dev`, the Sites Vite plugin mocks ChatGPT sign-in on the Vite URL only:

- Browser: **Sign in with ChatGPT** → `/signin-with-chatgpt?return_to=/`
- Mock identity: `local_seedy` / `seedy@sites.test`

`/signin-with-chatgpt` is not a Worker route. `pnpm start` and any workerd-only port return 404 for it. Send Sites identity headers instead (fictional values only):

```sh
curl -sS http://127.0.0.1:8787/api/workspace \
-H 'oai-authenticated-user-id: local-dev' \
-H 'oai-authenticated-user-email: local@example.com'
```

The Sites plugin on `pnpm dev` strips caller-supplied `oai-authenticated-user-*` headers and injects the mock user only after the sign-in cookie. Header mock is for the built Worker. Production must use the Access gateway from the delivery foundation.

## Integration boundaries

Expand All @@ -96,7 +140,7 @@ pnpm lint
node tests/api.test.mjs
```

For an existing local database already on migration 0001, apply only 0002 from the setup commands. It preserves observations and repairs imported Ready records that lack matching accepted text. Imported Ready is research evidence; a new record stays Held until its exact draft is accepted in Relay.
For an existing local database still on migration 0001, apply 0002 from the setup commands. Migration 0002 preserves observations and repairs imported Ready records that lack matching accepted text. Imported Ready is research evidence; a new record stays Held until its exact draft is accepted in Relay.

The last command needs a running local server and writes only fictional test records. Domain, import, editor and connector tests cover status preservation, duplicate matching, imported acceptance, observation identity, editor version conflicts, draft review rules, provider errors and pagination. Connector tests mock vendor responses; they do not prove live account access. API checks verify database read-back, stale edits, exact acceptance, status-preserving follow-up edits and authentication rejection. Local browser and WebMCP reads/import checks were exercised. Preview works before the first import. Browser file import, save and reload preserved source history. Browser acceptance, reload, and post-acceptance reimport preserved the exact accepted draft, Ready status, two observations, and history. The assisted trial ran on `3b1efd7`; a read-only reopen after fast-forward still showed the accepted record on `59ec7ac`.

Expand Down
38 changes: 36 additions & 2 deletions app/api/workspace/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ import {
} from '../../../lib/domain';
import seed from '../../../lib/seed.json';
import { packets } from '../../../lib/packets';
import {
historyPageSize,
INITIAL_EVENT_LIMIT,
} from '../../../lib/workspace-events';
export const dynamic = 'force-dynamic';
const reply = (data: unknown, status = 200) =>
Response.json(data, { status, headers: { 'Cache-Control': 'no-store' } });
Expand All @@ -28,9 +32,9 @@ export async function GET() {
.all();
const events = await db
.prepare(
'SELECT * FROM events WHERE owner=? ORDER BY created DESC LIMIT 200',
'SELECT * FROM events WHERE owner=? ORDER BY created DESC LIMIT ?',
)
.bind(user)
.bind(user, INITIAL_EVENT_LIMIT)
.all();
return reply({
jobs: jobs.results,
Expand Down Expand Up @@ -155,6 +159,36 @@ export async function POST(request: Request) {
return reply({ error: 'Record changed. Reload before saving.' }, 409);
return reply({ ok: true });
}
if (b.action === 'history') {
const job = await db
.prepare('SELECT id FROM jobs WHERE id=? AND owner=?')
.bind(b.id, user)
.first();
if (!job) return reply({ error: 'Record not found.' }, 404);
const limit = historyPageSize(b.limit);
const before = typeof b.before === 'string' && b.before ? b.before : null;
const rows = before
? await db
.prepare(
'SELECT * FROM events WHERE owner=? AND job_id=? AND created < ? ORDER BY created DESC LIMIT ?',
)
.bind(user, b.id, before, limit)
.all()
: await db
.prepare(
'SELECT * FROM events WHERE owner=? AND job_id=? ORDER BY created DESC LIMIT ?',
)
.bind(user, b.id, limit)
.all();
const events = rows.results;
return reply({
events,
next:
events.length === limit
? events[events.length - 1]?.created || null
: null,
});
}
return reply({ error: 'Unknown action.' }, 400);
} catch (e) {
return reply(
Expand Down
115 changes: 83 additions & 32 deletions app/connections.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ import {
import {
readIntegrationFiles,
draftFromResult,
draftFromPastedJson,
selectedJobPacket,
} from '../lib/integration-files';

function downloadFile(content: string, filename: string, type: string) {
Expand All @@ -37,7 +39,7 @@ export function Connections({
id: string;
job_key: string;
name: string;
url: string;
url: string | null;
version: number;
status: string;
session?: string;
Expand All @@ -56,24 +58,53 @@ export function Connections({
}) {
const [facts, setFacts] = useState('');
const [note, setNote] = useState('');
const [pasted, setPasted] = useState('');
const [workflow, setWorkflow] =
useState<keyof typeof obsidianWorkflows>('research');
const [loading, setLoading] = useState(false);
function editorTarget() {
return current?.session
? {
jobId: current.id,
session: current.session,
version: current.version,
draft,
job_key: current.job_key,
}
: undefined;
}
function packetText() {
return current
? JSON.stringify(selectedJobPacket(current, facts, draft), null, 2)
: '';
}
async function copy() {
if (!current) return;
try {
await navigator.clipboard.writeText(packetText());
setNote(
'Packet copied. It includes only this job, the visible draft, and the facts you supplied.',
);
} catch {
setNote('Unable to copy to the clipboard. Download the packet instead.');
}
}
function loadPastedDraft() {
try {
const started = editorTarget();
onDraft(draftFromPastedJson(pasted, started), started);
setNote(
'JSON checked. Review the visible draft before saving; if your selection or draft changed, load it again.',
);
} catch (error) {
setNote(
error instanceof Error ? error.message : 'Unable to read draft JSON.',
);
}
}
function download(assistant?: Assistant) {
if (!current) return;
const packet = {
schema: 'relay.packet.v1',
job: {
id: current.id,
key: current.job_key,
name: current.name,
url: current.url,
version: current.version,
status: current.status,
},
facts,
draft,
};
const packet = selectedJobPacket(current, facts, draft);
if (assistant) {
try {
downloadFile(
Expand All @@ -91,11 +122,7 @@ export function Connections({
}
return;
}
downloadFile(
JSON.stringify(packet, null, 2),
'relay-packet.json',
'application/json',
);
downloadFile(packetText(), 'relay-packet.json', 'application/json');
setNote(
'Packet downloaded. It includes only this job, the visible draft, and the facts you supplied.',
);
Expand Down Expand Up @@ -138,10 +165,14 @@ export function Connections({
className="secondary"
disabled={!current?.url}
onClick={() => {
if (!current) return;
if (!current?.url) return;
const id = crypto.randomUUID();
downloadFile(
obsidianResearchNote(current, workflow, id),
obsidianResearchNote(
{ ...current, url: current.url },
workflow,
id,
),
`relay-${workflow}-${id}.md`,
'text/markdown',
);
Expand Down Expand Up @@ -185,10 +216,13 @@ export function Connections({
className="secondary"
disabled={!current?.url}
onClick={() => {
if (!current) return;
if (!current?.url) return;
try {
downloadFile(
obsidianDraftNote({ ...current, key: current.job_key }, draft),
obsidianDraftNote(
{ ...current, key: current.job_key, url: current.url },
draft,
),
`relay-draft-${current.id}.md`,
'text/markdown',
);
Expand Down Expand Up @@ -228,6 +262,13 @@ export function Connections({
>
Download selected job packet
</button>
<button
className="secondary"
disabled={!current}
onClick={() => void copy()}
>
Copy selected job packet
</button>
<button
className="secondary"
disabled={!current}
Expand Down Expand Up @@ -255,15 +296,7 @@ export function Connections({
const files = Array.from(e.target.files || []);
if (!files.length) return;
setLoading(true);
const started = current?.session
? {
jobId: current.id,
session: current.session,
version: current.version,
draft,
job_key: current.job_key,
}
: undefined;
const started = editorTarget();
const value = await readIntegrationFiles(files);
if (Array.isArray(value)) {
onImport(JSON.stringify(value, null, 2));
Expand Down Expand Up @@ -298,6 +331,24 @@ export function Connections({
local command tool. Returned wording needs review; loading never accepts
or sends it.
</p>
<label className="field">
Paste complete relay.draft.v1 JSON
<textarea
aria-label="Paste complete relay.draft.v1 JSON"
value={pasted}
onChange={(e) => setPasted(e.target.value)}
placeholder='{"schema":"relay.draft.v1","job":{"id":"…","key":"…","url":"…","version":1},"draft":"…"}'
/>
</label>
<div className="actions">
<button
className="secondary"
disabled={!current || loading}
onClick={loadPastedDraft}
>
Load draft for review
</button>
</div>
{loading && <output>Reading selected files…</output>}
{note && <output>{note}</output>}
</details>
Expand Down
Loading
Loading