@arungeorgesaji/assembly 0.1.0

package/src/report.js

@@ -0,0 +1,46 @@
+export function createFinalReport({ request, plan, state, events }) {
+  const completedEvents = events.filter((event) =>
+    ["task.complete", "task.blocked", "task.failed"].includes(event.type),
+  );
+  const resultByTaskId = new Map(completedEvents.map((event) => [event.taskId, event.data]));
+  const risks = completedEvents.flatMap((event) => event.data?.risks ?? []);
+
+  return [
+    "# Assembly Run Report",
+    "",
+    `Run: ${state.runId}`,
+    `Status: ${state.status}`,
+    `Request: ${request.request}`,
+    "",
+    "## Summary",
+    "",
+    plan.summary,
+    "",
+    "## Tasks",
+    "",
+    ...plan.tasks.flatMap((task) => {
+      const taskState = state.tasks[task.id];
+      const result = resultByTaskId.get(task.id);
+      const profile = plan.agentProfiles?.find((candidate) => candidate.id === task.agentProfileId);
+      return [
+        `### ${task.title}`,
+        "",
+        `- ID: ${task.id}`,
+        `- Owner: ${task.owner}`,
+        `- Agent profile: ${profile?.label ?? task.agentProfileId ?? "none"}`,
+        `- Status: ${taskState?.status ?? "unknown"}`,
+        `- Summary: ${result?.summary ?? "No result produced."}`,
+        `- Artifacts: ${(result?.artifacts ?? []).join(", ") || "none"}`,
+        "",
+      ];
+    }),
+    "## Risks",
+    "",
+    ...(risks.length > 0 ? risks.map((risk) => `- ${risk}`) : ["- None reported."]),
+    "",
+    "## Verification",
+    "",
+    ...plan.verification.map((step) => `- ${step}`),
+    "",
+  ].join("\n");
+}

package/src/result-validation.js

@@ -0,0 +1,55 @@
+import { validateFileUpdatesForTask } from "./file-updates.js";
+import { validateChangedFilesWithinScope } from "./scope.js";
+import { validatePatchForTask } from "./patch.js";
+
+const TERMINAL_STATUSES = new Set(["complete", "blocked", "failed"]);
+
+export function validateTaskResult(task, result) {
+  const errors = [];
+
+  if (!isObject(result)) {
+    return [`task ${task.id} returned a non-object result`];
+  }
+
+  if (result.taskId !== task.id) {
+    errors.push(`result taskId must match dispatched task ${task.id}`);
+  }
+  if (!TERMINAL_STATUSES.has(result.status)) {
+    errors.push(`task ${task.id} result status must be complete, blocked, or failed`);
+  }
+  if (!isNonEmptyString(result.summary)) {
+    errors.push(`task ${task.id} result must include a summary`);
+  }
+  if (!Array.isArray(result.changedFiles)) {
+    errors.push(`task ${task.id} result changedFiles must be an array`);
+  }
+  if (!Array.isArray(result.artifacts)) {
+    errors.push(`task ${task.id} result artifacts must be an array`);
+  }
+  if (!Array.isArray(result.risks)) {
+    errors.push(`task ${task.id} result risks must be an array`);
+  }
+  if (result.status === "complete" && Array.isArray(result.artifacts) && result.artifacts.length === 0) {
+    errors.push(`completed task ${task.id} must include at least one artifact`);
+  }
+  if (Array.isArray(result.changedFiles)) {
+    errors.push(...validateChangedFilesWithinScope(task, result.changedFiles));
+  }
+  if (result.patch !== undefined && typeof result.patch !== "string") {
+    errors.push(`task ${task.id} result patch must be a string when provided`);
+  }
+  if (typeof result.patch === "string") {
+    errors.push(...validatePatchForTask(task, result));
+  }
+  errors.push(...validateFileUpdatesForTask(task, result));
+
+  return errors;
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/src/review-agent-runner.js

@@ -0,0 +1,127 @@
+import { getOpenAIConfig } from "./config.js";
+import { buildTaskContext } from "./context-builder.js";
+import { readRun } from "./run-store.js";
+
+const REVIEW_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["taskId", "status", "summary", "changedFiles", "artifacts", "risks", "patch", "fileUpdates"],
+  properties: {
+    taskId: { type: "string" },
+    status: { type: "string", enum: ["complete", "blocked", "failed"] },
+    summary: { type: "string" },
+    changedFiles: {
+      type: "array",
+      items: { type: "string" },
+    },
+    artifacts: {
+      type: "array",
+      items: { type: "string" },
+    },
+    risks: {
+      type: "array",
+      items: { type: "string" },
+    },
+    patch: { type: "string" },
+    fileUpdates: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["path", "content"],
+        properties: {
+          path: { type: "string" },
+          content: { type: "string" },
+        },
+      },
+    },
+  },
+};
+
+export function createOpenAIReviewRunner(config = getOpenAIConfig()) {
+  return async function runOpenAIReview(task, runContext = {}) {
+    const rootDir = runContext.rootDir ?? process.cwd();
+    const taskContext = await buildTaskContext(task, rootDir);
+    const run = await readRun(runContext.runId, rootDir);
+    const agentProfile = run.plan.agentProfiles?.find((profile) => profile.id === task.agentProfileId);
+
+    const response = await fetch(`${config.baseUrl}/responses`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: config.model,
+        input: [
+          {
+            role: "developer",
+            content: [
+              {
+                type: "input_text",
+                text:
+                  "You are an Assembly review agent. Return only JSON matching the schema. " +
+                  "Review the completed task results, changed files, artifacts, and verification output. " +
+                  "If task.agentProfileId is present, use the matching agentProfile to check ownership boundaries. " +
+                  "Return status complete when the work is acceptable. Return blocked for human input needed. " +
+                  "Return failed for concrete correctness, scope, security, or verification problems. " +
+                  "Do not edit files; patch must be empty and fileUpdates must be empty.",
+              },
+            ],
+          },
+          {
+            role: "user",
+            content: [
+              {
+                type: "input_text",
+                text: JSON.stringify(
+                  {
+                    request: run.plan.request,
+                    task,
+                    agentProfile,
+                    state: run.state,
+                    events: run.events,
+                    scopedFiles: taskContext.files,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          },
+        ],
+        text: {
+          format: {
+            type: "json_schema",
+            name: "assembly_review_result",
+            strict: true,
+            schema: REVIEW_SCHEMA,
+          },
+        },
+      }),
+    });
+
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      const message = payload?.error?.message ?? "unknown OpenAI API error";
+      throw new Error(`OpenAI API request failed with status ${response.status}: ${message}`);
+    }
+
+    const outputText = payload?.output_text ?? findOutputText(payload);
+    if (!outputText) {
+      throw new Error("OpenAI review response did not include structured output text");
+    }
+    return JSON.parse(outputText);
+  };
+}
+
+function findOutputText(payload) {
+  for (const item of payload?.output ?? []) {
+    for (const content of item.content ?? []) {
+      if (content.type === "output_text" && typeof content.text === "string") {
+        return content.text;
+      }
+    }
+  }
+  return null;
+}

package/src/root.js

@@ -0,0 +1,51 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function resolveRootDir({ cwd = process.cwd(), repo, env = process.env, exec = execFileAsync } = {}) {
+  const explicitRepo = repo || env.ASSEMBLY_REPO;
+  if (explicitRepo) {
+    return path.resolve(cwd, explicitRepo);
+  }
+
+  try {
+    const { stdout } = await exec("git", ["rev-parse", "--show-toplevel"], { cwd });
+    const gitRoot = stdout.trim();
+    return gitRoot ? path.resolve(gitRoot) : cwd;
+  } catch {
+    return cwd;
+  }
+}
+
+export function parseGlobalOptions(argv) {
+  const args = [];
+  const errors = [];
+  let repo;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--repo") {
+      if (!argv[index + 1] || argv[index + 1].startsWith("--")) {
+        errors.push("--repo requires a path");
+        continue;
+      }
+      repo = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--repo=")) {
+      const value = arg.slice("--repo=".length);
+      if (!value) {
+        errors.push("--repo requires a path");
+        continue;
+      }
+      repo = value;
+      continue;
+    }
+    args.push(arg);
+  }
+
+  return { args, repo, errors };
+}

package/src/run-store.js

@@ -0,0 +1,104 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const ROOT_DIR = ".assembly";
+const RUNS_DIR = "runs";
+
+export function createRunId(date = new Date()) {
+  const timestamp = date.toISOString().replaceAll(":", "").replace(/\.\d{3}Z$/, "Z");
+  const suffix = Math.random().toString(36).slice(2, 8);
+  return `${timestamp}-${suffix}`;
+}
+
+export function getRunDir(runId, rootDir = process.cwd()) {
+  return path.join(rootDir, ROOT_DIR, RUNS_DIR, runId);
+}
+
+export async function initializeRun({ runId, request, plan, metadata = {} }, rootDir = process.cwd()) {
+  const runDir = getRunDir(runId, rootDir);
+  await mkdir(path.join(runDir, "artifacts"), { recursive: true });
+
+  const state = {
+    runId,
+    status: "created",
+    currentTaskId: null,
+    tasks: Object.fromEntries(
+      plan.tasks.map((task) => [
+        task.id,
+        {
+          status: "pending",
+          owner: task.owner,
+          agentProfileId: task.agentProfileId,
+          title: task.title,
+        },
+      ]),
+    ),
+  };
+
+  await writeJson(path.join(runDir, "request.json"), {
+    id: runId,
+    request,
+    createdAt: new Date().toISOString(),
+    ...metadata,
+  });
+  await writeJson(path.join(runDir, "plan.json"), plan);
+  await writeJson(path.join(runDir, "state.json"), state);
+  await appendEvent(runId, { type: "run.created", data: { request, metadata } }, rootDir);
+
+  return state;
+}
+
+export async function readRun(runId, rootDir = process.cwd()) {
+  const runDir = getRunDir(runId, rootDir);
+  const [request, plan, state, eventsText] = await Promise.all([
+    readJson(path.join(runDir, "request.json")),
+    readJson(path.join(runDir, "plan.json")),
+    readJson(path.join(runDir, "state.json")),
+    readFile(path.join(runDir, "events.jsonl"), "utf8").catch(() => ""),
+  ]);
+
+  return {
+    request,
+    plan,
+    state,
+    events: eventsText
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line)),
+  };
+}
+
+export async function writeState(runId, state, rootDir = process.cwd()) {
+  await writeJson(path.join(getRunDir(runId, rootDir), "state.json"), state);
+}
+
+export async function writeArtifact(runId, taskId, name, data, rootDir = process.cwd()) {
+  const artifactDir = path.join(getRunDir(runId, rootDir), "artifacts", taskId);
+  await mkdir(artifactDir, { recursive: true });
+  await writeJson(path.join(artifactDir, name), data);
+}
+
+export async function writeRunFile(runId, name, content, rootDir = process.cwd()) {
+  await writeFile(path.join(getRunDir(runId, rootDir), name), content);
+}
+
+export async function appendEvent(runId, event, rootDir = process.cwd()) {
+  const enrichedEvent = {
+    runId,
+    timestamp: new Date().toISOString(),
+    ...event,
+  };
+  await writeFile(
+    path.join(getRunDir(runId, rootDir), "events.jsonl"),
+    `${JSON.stringify(enrichedEvent)}\n`,
+    { flag: "a" },
+  );
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+async function writeJson(filePath, data) {
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}

package/src/scope.js

@@ -0,0 +1,107 @@
+import path from "node:path";
+
+export function createScope({ paths = [], allowlist = [], denylist = [] } = {}) {
+  return {
+    paths,
+    allowlist,
+    denylist,
+  };
+}
+
+export function validateChangedFilesWithinScope(task, changedFiles) {
+  const errors = [];
+  const scope = task.scope ?? createScope();
+
+  for (const changedFile of changedFiles) {
+    const normalized = normalizeRelativePath(changedFile);
+    if (!normalized) {
+      errors.push(`task ${task.id} changed file ${changedFile} is not a safe relative path`);
+      continue;
+    }
+
+    if (matchesAny(normalized, scope.denylist)) {
+      errors.push(`task ${task.id} changed denied path ${changedFile}`);
+      continue;
+    }
+
+    if (matchesAny(normalized, scope.allowlist)) {
+      continue;
+    }
+
+    if (!matchesAny(normalized, scope.paths)) {
+      errors.push(`task ${task.id} changed file ${changedFile} outside assigned scope`);
+    }
+  }
+
+  return errors;
+}
+
+export function validateScope(scope, taskId) {
+  const errors = [];
+
+  if (!scope || typeof scope !== "object" || Array.isArray(scope)) {
+    return [`task ${taskId} must include a scope object`];
+  }
+
+  for (const key of ["paths", "allowlist", "denylist"]) {
+    if (!Array.isArray(scope[key])) {
+      errors.push(`task ${taskId} scope.${key} must be an array`);
+      continue;
+    }
+    for (const scopePath of scope[key]) {
+      if (!normalizeRelativePath(scopePath)) {
+        errors.push(`task ${taskId} scope.${key} contains unsafe path ${scopePath}`);
+      }
+    }
+  }
+
+  if (scope.paths.length === 0 && scope.allowlist.length === 0) {
+    errors.push(`task ${taskId} scope must include at least one path or allowlist entry`);
+  }
+
+  return errors;
+}
+
+function matchesAny(changedFile, scopePaths) {
+  return scopePaths.some((scopePath) => matchesScopePath(changedFile, scopePath));
+}
+
+function matchesScopePath(changedFile, scopePath) {
+  const normalizedScopePath = normalizeRelativePath(scopePath);
+  if (!normalizedScopePath) {
+    return false;
+  }
+
+  if (normalizedScopePath.includes("*")) {
+    const pattern = new RegExp(`^${normalizedScopePath.split("*").map(escapeRegex).join("[^/]*")}$`);
+    return pattern.test(changedFile);
+  }
+
+  if (normalizedScopePath.endsWith("/")) {
+    return changedFile.startsWith(normalizedScopePath);
+  }
+
+  return changedFile === normalizedScopePath || changedFile.startsWith(`${normalizedScopePath}/`);
+}
+
+function normalizeRelativePath(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return null;
+  }
+
+  const normalized = value.replaceAll("\\", "/");
+  if (path.posix.isAbsolute(normalized)) {
+    return null;
+  }
+
+  const collapsed = path.posix.normalize(normalized);
+  if (collapsed === "." || collapsed === ".." || collapsed.startsWith("../")) {
+    return null;
+  }
+
+  return normalized.endsWith("/") && !collapsed.endsWith("/") ? `${collapsed}/` : collapsed;
+}
+
+function escapeRegex(value) {
+  return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}

package/src/slack-thread-store.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const THREADS_DIR = ".assembly/slack-threads";
+
+export async function readSlackThreadState({ teamId, channel, threadTs }, rootDir = process.cwd()) {
+  try {
+    return JSON.parse(await readFile(getThreadPath({ teamId, channel, threadTs }, rootDir), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function writeSlackThreadState(state, rootDir = process.cwd()) {
+  await mkdir(path.join(rootDir, THREADS_DIR), { recursive: true });
+  const updatedState = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+  };
+  await writeFile(getThreadPath(state, rootDir), `${JSON.stringify(updatedState, null, 2)}\n`);
+  return updatedState;
+}
+
+function getThreadPath({ teamId, channel, threadTs }, rootDir) {
+  const key = [teamId || "unknown-team", channel, threadTs].map(sanitizeKeyPart).join("__");
+  return path.join(rootDir, THREADS_DIR, `${key}.json`);
+}
+
+function sanitizeKeyPart(value) {
+  return String(value ?? "").replace(/[^a-zA-Z0-9._-]+/g, "_");
+}

package/src/slack-webhooks.js

@@ -0,0 +1,120 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { getSlackSigningSecret } from "./config.js";
+import { enqueueJob, findJobByDelivery } from "./job-store.js";
+import { postSlackMessage } from "./slack.js";
+
+const FIVE_MINUTES_SECONDS = 60 * 5;
+
+export function verifySlackSignature(
+  rawBody,
+  signature,
+  timestamp,
+  secret = getSlackSigningSecret(),
+  nowSeconds = Math.floor(Date.now() / 1000),
+) {
+  if (!secret) {
+    throw new Error("SLACK_SIGNING_SECRET is required for webhook verification");
+  }
+  if (!signature?.startsWith("v0=") || !timestamp) {
+    return false;
+  }
+  if (Math.abs(nowSeconds - Number(timestamp)) > FIVE_MINUTES_SECONDS) {
+    return false;
+  }
+
+  const base = `v0:${timestamp}:${rawBody}`;
+  const expected = `v0=${createHmac("sha256", secret).update(base).digest("hex")}`;
+  const expectedBuffer = Buffer.from(expected);
+  const actualBuffer = Buffer.from(signature);
+  return expectedBuffer.length === actualBuffer.length && timingSafeEqual(expectedBuffer, actualBuffer);
+}
+
+export async function handleSlackWebhook({ signature, timestamp, rawBody }, rootDir = process.cwd()) {
+  if (!verifySlackSignature(rawBody, signature, timestamp)) {
+    return { status: 401, body: { error: "invalid signature" } };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(rawBody);
+  } catch {
+    return { status: 400, body: { error: "invalid JSON payload" } };
+  }
+
+  if (payload.type === "url_verification") {
+    return { status: 200, body: { challenge: payload.challenge } };
+  }
+
+  const normalized = normalizeSlackWebhook(payload);
+  if (normalized.ignored) {
+    return { status: 202, body: normalized };
+  }
+
+  const existingJob = await findJobByDelivery(normalized.delivery, rootDir);
+  if (existingJob) {
+    return { status: 202, body: { queued: false, duplicate: true, jobId: existingJob.id } };
+  }
+
+  const job = await enqueueJob({
+    type: normalized.type,
+    delivery: normalized.delivery,
+    payload: normalized.payload,
+  }, rootDir);
+  await acknowledgeSlackJob(job);
+
+  return { status: 202, body: { queued: true, jobId: job.id } };
+}
+
+export function normalizeSlackWebhook(payload) {
+  if (payload.type !== "event_callback") {
+    return { ignored: true, reason: "unsupported slack payload type" };
+  }
+
+  const event = payload.event ?? {};
+  if (event.bot_id || event.subtype === "bot_message") {
+    return { ignored: true, reason: "bot messages are ignored" };
+  }
+  if (!["app_mention", "message"].includes(event.type)) {
+    return { ignored: true, reason: "unsupported slack event type" };
+  }
+  if (event.type === "message" && event.channel_type !== "im") {
+    return { ignored: true, reason: "non-DM messages must mention the app" };
+  }
+
+  const text = stripSlackAppMention(event.text ?? "").trim();
+  if (!text) {
+    return { ignored: true, reason: "slack event does not include a request" };
+  }
+
+  return {
+    type: "slack.request",
+    delivery: payload.event_id,
+    payload: {
+      kind: event.type,
+      teamId: payload.team_id,
+      eventId: payload.event_id,
+      channel: event.channel,
+      user: event.user,
+      text,
+      threadTs: event.thread_ts ?? event.ts,
+      ts: event.ts,
+    },
+  };
+}
+
+function stripSlackAppMention(text) {
+  return String(text).replace(/<@[A-Z0-9]+>\s*/gi, "");
+}
+
+async function acknowledgeSlackJob(job) {
+  try {
+    await postSlackMessage({
+      channel: job.payload.channel,
+      threadTs: job.payload.threadTs,
+      text: `On it. Queued Assembly job ${job.id}.`,
+    });
+  } catch {
+    // The queued job remains the source of truth even if the fast ack fails.
+  }
+}

package/src/slack.js

@@ -0,0 +1,31 @@
+import { getSlackBotToken } from "./config.js";
+
+export async function postSlackMessage(
+  { channel, text, threadTs },
+  { token = getSlackBotToken(), fetchImpl = globalThis.fetch } = {},
+) {
+  if (!token) {
+    throw new Error("SLACK_BOT_TOKEN is required to post Slack messages");
+  }
+  if (!fetchImpl) {
+    throw new Error("fetch is required to post Slack messages");
+  }
+
+  const response = await fetchImpl("https://slack.com/api/chat.postMessage", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json; charset=utf-8",
+    },
+    body: JSON.stringify({
+      channel,
+      text,
+      thread_ts: threadTs,
+    }),
+  });
+  const result = await response.json();
+  if (!result.ok) {
+    throw new Error(`Slack chat.postMessage failed: ${result.error ?? "unknown_error"}`);
+  }
+  return result;
+}