@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.35 → 0.1.46

package/packages/azdo/src/activity-log.ts

@@ -0,0 +1,118 @@
+/** A1 agent activity log — design: docs/research/adl-process-handover/process-design.md § Activity log. */
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { resolveAgentIdentity } from './lib/agent-identity.ts';
+
+export interface ActivityEntry {
+  time: string;
+  surface: string;
+  agent: string;
+  repo: string;
+  note: string;
+}
+
+/** Verified child-process surface markers, first match wins; a marker is listed only with a citation to the surface's own docs. */
+const SURFACE_MARKERS: ReadonlyArray<{ readonly surface: string; readonly env: string; readonly equals?: string }> = [
+  // Claude Code spawns set CLAUDECODE=1 (code.claude.com/docs/en/env-vars, verified 2026-10-12).
+  { surface: 'claude', env: 'CLAUDECODE', equals: '1' },
+];
+
+/** The surface this process runs under: first verified marker match, else 'cli' (no marker is not an error). */
+export function resolveSurface(env: NodeJS.ProcessEnv = process.env): string {
+  for (const marker of SURFACE_MARKERS) {
+    const value = env[marker.env];
+    if (value !== undefined && (marker.equals === undefined || value === marker.equals)) {
+      return marker.surface;
+    }
+  }
+  return 'cli';
+}
+
+/** The git work-tree top level of `cwd` (or the process's own), or a loud refusal outside a work tree — the log lives at `<repo>/.adl/agent-activity.sqlite`. */
+export function repoTopLevel(cwd?: string): string {
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    ...(cwd === undefined ? {} : { cwd }),
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  const topLevel = result.status === 0 ? result.stdout.trim() : '';
+  if (!topLevel) {
+    throw new Error(
+      'the activity log lives at <repo>/.adl/agent-activity.sqlite, and this working directory is not a git work tree',
+    );
+  }
+  return topLevel;
+}
+
+/** The ONE place the log's path is built. */
+export function activityDbPath(cwd?: string): string {
+  return join(repoTopLevel(cwd), '.adl', 'agent-activity.sqlite');
+}
+
+function openDb(cwd?: string): DatabaseSync {
+  const path = activityDbPath(cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS activity (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      time TEXT NOT NULL,
+      surface TEXT NOT NULL,
+      agent TEXT NOT NULL,
+      repo TEXT NOT NULL,
+      note TEXT NOT NULL
+    )`,
+  );
+  return db;
+}
+
+function assertNote(note: unknown): asserts note is string {
+  if (typeof note !== 'string' || note.trim() === '') {
+    throw new Error('note must be a non-empty string');
+  }
+}
+
+/** Append one entry, filling time/surface/agent/repo; `env`/`now` keep tests hermetic. Returns the stored entry as JSON. */
+export function activityAdd(
+  note: unknown,
+  opts: { cwd?: string; env?: NodeJS.ProcessEnv; now?: Date } = {},
+): string {
+  assertNote(note);
+  const env = opts.env ?? process.env;
+  const entry: ActivityEntry = {
+    time: (opts.now ?? new Date()).toISOString(),
+    surface: resolveSurface(env),
+    agent: resolveAgentIdentity(env).agent,
+    repo: basename(repoTopLevel(opts.cwd)),
+    note,
+  };
+  const db = openDb(opts.cwd);
+  try {
+    db.prepare('INSERT INTO activity (time, surface, agent, repo, note) VALUES (?, ?, ?, ?, ?)').run(
+      entry.time,
+      entry.surface,
+      entry.agent,
+      entry.repo,
+      entry.note,
+    );
+  } finally {
+    db.close();
+  }
+  return JSON.stringify(entry, null, 2);
+}
+
+/** Every entry, oldest first (the reading order of the ledger this replaces). */
+export function activityList(opts: { cwd?: string } = {}): string {
+  const db = openDb(opts.cwd);
+  let entries: unknown[];
+  try {
+    entries = db
+      .prepare('SELECT time, surface, agent, repo, note FROM activity ORDER BY id ASC')
+      .all();
+  } finally {
+    db.close();
+  }
+  return JSON.stringify({ repo: basename(repoTopLevel(opts.cwd)), entries }, null, 2);
+}

package/packages/azdo/src/azdo-attachments.ts

@@ -0,0 +1,109 @@
+// T2 work-item attachments (board-rules.md § Attachments): Features only, frozen once attached — the one delete allowed is a mistaken upload in its own run, for a plan-r* file while every Feature item is still at or before Awaiting Approval. API facts (WIT REST 7.1): upload POSTs .../_apis/wit/attachments?fileName={name} (octet-stream, returns { id, url }); attach PATCHes the work item adding an AttachedFile relation (test/rev gives optimistic concurrency); Attachments-Delete is 7.2-preview only, so delete detaches and the stored file stays.
+import { AdoClient } from './lib/client.ts';
+
+let client: AdoClient | undefined
+
+async function getClient(): Promise<AdoClient> {
+  client ??= new AdoClient()
+  return client
+}
+
+/** Test seam: forget the cached client — see azdo-wit.ts's resetClientForTests() for why. */
+export function resetClientForTests(): void {
+  client = undefined
+}
+
+export type WorkitemAttachmentsArgs = {
+  id: number;
+  action: 'read' | 'upload' | 'delete';
+  /** upload/delete: the attachment file name. */
+  fileName?: string;
+  /** upload: the file content, sent as an octet-stream body. */
+  content?: string;
+};
+
+interface AttachmentRelation {
+  index: number;
+  name: string;
+  url: string;
+}
+
+function attachedFiles(item: any): AttachmentRelation[] {
+  return (item.relations ?? [])
+    .map((relation: any, index: number) => ({ relation, index }))
+    .filter(({ relation }: any) => relation.rel === 'AttachedFile')
+    .map(({ relation, index }: any) => ({
+      index,
+      name: relation.attributes?.name ?? relation.url,
+      url: relation.url,
+    }));
+}
+
+/** P4 reuses this upload when it attaches the mandatory plan/impl report at PR raise. */
+export async function uploadAttachment(c: AdoClient, workItemId: number, fileName: string, content: string): Promise<void> {
+  const uploaded = await c.post<any>(
+    '/wit/attachments',
+    content,
+    { fileName, 'api-version': '7.1' },
+    'application/octet-stream',
+  );
+  if (!uploaded?.url) throw new Error(`attachment upload for '${fileName}' returned no url`);
+  const item = await c.get<any>(`/wit/workitems/${workItemId}`, { 'api-version': '7.1' });
+  await c.patch<any>(
+    `/wit/workitems/${workItemId}`,
+    [
+      { op: 'test', path: '/rev', value: item.rev ?? item.fields?.['System.Rev'] },
+      { op: 'add', path: '/relations/-', value: { rel: 'AttachedFile', url: uploaded.url } },
+    ],
+    { 'api-version': '7.1' },
+    'application/json-patch+json',
+  );
+}
+
+/** The T2 guard (board-rules.md § Attachments): a plan-r* file refuses deletion once any item of its Feature has left Awaiting Approval — the plan G1 approved stays on the board. */
+async function assertPlanAttachmentDeletable(c: AdoClient, feature: any, fileName: string): Promise<void> {
+  const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
+  // `feature.relations` is always an array here: attachedFiles() returned a target off this same object, so the property was a non-empty array moments earlier -- the nullish fallback was unreachable.
+  const childIds = feature.relations
+    .filter((relation: any) => relation.rel === 'System.LinkTypes.Hierarchy-Forward')
+    .map((relation: any) => relationId(relation.url))
+    .filter((id: number) => Number.isInteger(id));
+  if (!childIds.length) return;
+  const children = await c.post<any>('/wit/workitemsbatch', { ids: childIds, $expand: 'all' }, { 'api-version': '7.1' });
+  const left = (children.value ?? []).find((child: any) => !['New', 'In Planning', 'Awaiting Approval'].includes(child.fields?.['System.State']));
+  if (left) {
+    throw new Error(`refusing to delete '${fileName}': an item of Feature ${feature.id} has left Awaiting Approval (item ${left.id} is at ${left.fields?.['System.State']}) — the approved plan stays on the board`);
+  }
+}
+
+export async function workitemAttachments(args: WorkitemAttachmentsArgs): Promise<string> {
+  const c = await getClient();
+  if (args.action === 'upload') {
+    if (!args.fileName) throw new Error('fileName is required for upload');
+    if (args.content === undefined || args.content === '') throw new Error('content is required for upload');
+    await uploadAttachment(c, args.id, args.fileName, args.content);
+    return JSON.stringify({ id: args.id, attached: args.fileName }, null, 2);
+  }
+  const item = await c.get<any>(`/wit/workitems/${args.id}`, { 'api-version': '7.1', $expand: 'all' });
+  const files = attachedFiles(item);
+  if (args.action === 'read') {
+    return JSON.stringify({ id: args.id, attachments: files.map(({ name, url }) => ({ name, url })) }, null, 2);
+  }
+  if (!args.fileName) throw new Error('fileName is required for delete');
+  const target = files.find((file) => file.name === args.fileName);
+  if (!target) throw new Error(`work item ${args.id} has no AttachedFile named '${args.fileName}'`);
+  if (target.name.startsWith('plan-r')) {
+    await assertPlanAttachmentDeletable(c, item, target.name);
+  }
+  // On 7.1 delete detaches: remove the relation, the stored file stays; test/rev gives the same optimistic concurrency as attach.
+  await c.patch<any>(
+    `/wit/workitems/${args.id}`,
+    [
+      { op: 'test', path: '/rev', value: item.rev ?? item.fields?.['System.Rev'] },
+      { op: 'remove', path: `/relations/${target.index}` },
+    ],
+    { 'api-version': '7.1' },
+    'application/json-patch+json',
+  );
+  return JSON.stringify({ id: args.id, deleted: target.name }, null, 2);
+}

package/packages/azdo/src/azdo-pl.ts

@@ -9,10 +9,38 @@
  * automatically) falling back to the AdoClient defaults. Nothing is
  * hardcoded here.
  *
+ * buildRun carries the second half of H1
+ * (docs/research/adl-process-handover/board-rules.md § Hooks, row
+ * `adl.build-run-role`): the hook has no network access, so it grades only
+ * what the call itself proves and names this function as the re-verifier of
+ * the caller-declared claim. Before queuing, buildRun requires ALL of:
+ *   1. `branch` present (the hook requires it too; the tool refuses on its
+ *      own, never relying on the hook alone);
+ *   2. an OPEN pull request in this repository whose source branch equals
+ *      the call's `branch` (after `refs/heads/` removal);
+ *   3. that PR raised by the CALLING agent identity — `createdBy.id`
+ *      compared against lib/graph-identity.ts's resolveAgentIdentityId, the
+ *      ONE identity-form producer in this repo;
+ *   4. the named definition is that PR's validation pipeline: a run of
+ *      definition `id` exists on the PR's merge ref (`refs/pull/<id>/merge`,
+ *      the sourceBranch ADO queues PR validation builds under — the same ref
+ *      build_list_or_get's poll hint names).
+ *   RESIDUAL APPROXIMATION (stated, not silently widened): check 4 proves
+ *   the definition IS a validation pipeline of THIS PR via a run that
+ *   already exists; a definition whose policy would queue on the PR but has
+ *   never produced a run is refused. That is sound for the re-queue use case
+ *   (an expired check implies a run that existed) but stricter than "any
+ *   policy-bound definition" — the PR resource carries no build-policy
+ *   reference (`completionOptions` names no definition), so an existing run
+ *   on the merge ref is the strongest relationship the REST API exposes.
+ *
  * Timeline model: Stage → Phase → Job → Task, chained by parentId
  * (Checkpoint records carry no user-facing state and are skipped).
  */
-import { AdoClient } from './lib/client.ts'
+import { AdoClient, resolveRepository } from './lib/client.ts'
+import { resolveAgentIdentity } from './lib/agent-identity.ts';
+import { resolveAgentIdentityId } from './lib/graph-identity.ts';
+import { pullRequestsPath } from './azdo-pr.ts'
 
 let client: AdoClient | undefined
 
@@ -21,6 +49,11 @@ async function getClient(): Promise<AdoClient> {
   return client
 }
 
+/** Test seam: forget the cached client — see azdo-pr.ts's resetClientForTests() for why. */
+export function resetClientForTests(): void {
+  client = undefined
+}
+
 /** GET a JSON payload. */
 async function getJson<T>(c: AdoClient, path: string, params?: Record<string, string>): Promise<T> {
   return c.get<T>(path, { 'api-version': '7.1', ...params });
@@ -160,13 +193,77 @@ export async function buildListOrGet(args: BuildListOrGetArgs = {}): Promise<str
 
 export type BuildRunArgs = { id: string; branch?: string };
 
+function normalizeBranchRef(ref: string): string {
+  return ref.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : ref;
+}
+
+/**
+ * H1's azdo half — see this file's header. Queries (all read-only, all
+ * before the queue POST): the open PRs on the named source branch, the
+ * caller's own ADO identity id (Graph Subject Query → Storage Keys), and the
+ * validation runs on the PR's merge ref. Throws with the exact failed check;
+ * queues only when every check passes.
+ */
+async function assertOwnPrValidationBuild(c: AdoClient, definitionId: number, branch: string): Promise<void> {
+  const sourceBranch = normalizeBranchRef(branch.trim());
+  const repository = resolveRepository();
+  const { repositoryId } = await resolveRepositoryId(c);
+  const agent = resolveAgentIdentity().agent;
+
+  const prs = await getJson<any>(c, pullRequestsPath(repository), {
+    'searchCriteria.status': 'active',
+    'searchCriteria.sourceRefName': `refs/heads/${sourceBranch}`,
+    '$top': '100',
+  });
+  const candidates = (prs.value ?? []) as any[];
+  if (candidates.length === 0) {
+    throw new Error(
+      `build_run refused (H1): no open pull request in '${repository}' has source branch '${sourceBranch}' — ` +
+        'build_run may only re-queue the validation pipeline of your own open PR, on that PR\'s source branch',
+    );
+  }
+
+  const callerId = await resolveAgentIdentityId(agent);
+  const mine = candidates.filter((pr) => pr.createdBy?.id === callerId);
+  if (mine.length === 0) {
+    const authors = [...new Set(candidates.map((pr) => pr.createdBy?.displayName ?? 'unknown'))].join(', ');
+    throw new Error(
+      `build_run refused (H1): the open pull request on '${sourceBranch}' was raised by ${authors}, not ${agent} — ` +
+        'build_run may only re-queue the validation pipeline of a PR you raised yourself',
+    );
+  }
+
+  for (const pr of mine) {
+    const runs = await getJson<any>(c, '/build/builds', {
+      branchName: `refs/pull/${pr.pullRequestId}/merge`,
+      repositoryId,
+      repositoryType: 'TfsGit',
+      '$top': '50',
+    });
+    if ((runs.value ?? []).some((run: any) => run.definition?.id === definitionId)) {
+      return;
+    }
+  }
+  const prIds = mine.map((pr) => pr.pullRequestId).join(', ');
+  throw new Error(
+    `build_run refused (H1): build definition ${definitionId} is not a validation pipeline of your pull request(s) ${prIds} ` +
+      `(no run of it exists on refs/pull/<id>/merge) — pass the definition id of your PR's validation build, from build_list_or_get`,
+  );
+}
+
 export async function buildRun(args: BuildRunArgs): Promise<string> {
   if (!args.id) throw new Error('id is required');
   const definitionId = Number(args.id);
   if (!Number.isInteger(definitionId) || definitionId < 1) throw new Error(`id must be a positive integer definition id; got '${args.id}'`);
+  if (typeof args.branch !== 'string' || args.branch.trim() === '') {
+    throw new Error(
+      'branch is required: name the source branch of your own open PR — build_run may only re-queue that PR\'s ' +
+        'validation pipeline, on that PR\'s source branch (H1)',
+    );
+  }
   const c = await getClient()
-  const body: any = { definition: { id: definitionId } };
-  if (args.branch) body.sourceBranch = args.branch;
+  await assertOwnPrValidationBuild(c, definitionId, args.branch);
+  const body: any = { definition: { id: definitionId }, sourceBranch: args.branch };
   const build = await c.post<any>('/build/builds', body, { 'api-version': '7.1' });
   return JSON.stringify({
     id: build.id,