@brainervirus/workit-core 8.15.0 → 8.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.15.0",
+  "version": "8.16.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/task-contract.ts

@@ -823,6 +823,27 @@ export const taskSummarySchema = z
   })
   .strict();
 export type TaskSummary = z.infer<typeof taskSummarySchema>;
+/** Bounded `inspect` projection (`view: "summary"`): under 4 KB however long the task history is. */
+export type TaskBrief = {
+  id: string;
+  revision: string;
+  workspaceRevision: string;
+  updatedAt: string;
+  objective: string;
+  status: TaskSummary["status"];
+  closure: { outcome: Closure["outcome"]; at: string; summary: string } | null;
+  progress: {
+    summary: string;
+    nextAction: string | null;
+    blockers: { reason: string; dependentAction: string }[];
+  };
+  requirements: {
+    total: number;
+    unmet: number;
+    open: { dimension: Dimension; before: string; status: RequirementEvaluation["status"] }[];
+  };
+  truncated: boolean;
+};
 export const taskListItemSchema = taskSummarySchema
   .omit({ policy: true, requirements: true })
   .extend({ source: provenanceSchema.pick({ host: true, kind: true }) })

package/src/core/task-engine.ts

@@ -35,6 +35,7 @@ import {
   type Result,
   type Scope,
   type TaskRecord,
+  type TaskBrief,
   type TaskListItem,
   type TaskSummary,
   type TaskView,
@@ -81,6 +82,7 @@ import {
   type NativeWorkerVerifier,
 } from "./workers";
 import {
+  boundTaskSummary,
   captureCandidate,
   checkPin,
   signalFreshness,
@@ -115,6 +117,8 @@ export type OperationContext = {
   now: Utc | (() => Utc);
   nativeWorker?: NativeWorkerVerifier;
   workerId?: string | null;
+  /** A child session with no worker record: it may only read the bounded task summary. */
+  readOnlyChild?: boolean;
 };
 
 export type ObserveCheckRequest = {
@@ -872,19 +876,27 @@ export class WorkitCore {
     return failure("invalid_input", "unknown state action");
   }
 
-  task(request: unknown): Result<TaskSummary | TaskListItem[] | TaskView> {
+  task(request: unknown): Result<TaskSummary | TaskBrief | TaskListItem[] | TaskView> {
     const resolved = this.implicitTask("task", request);
     if (!resolved.ok) return resolved;
     const value = resolved.data;
     return this.retryOmittedRevisions(value, () => this.taskOnce(value));
   }
 
-  private taskOnce(request: unknown): Result<TaskSummary | TaskListItem[] | TaskView> {
+  private taskOnce(request: unknown): Result<TaskSummary | TaskBrief | TaskListItem[] | TaskView> {
     const root = this.contextRootError();
     if (!root.ok) return root;
     const parsed = parseOperation("task", request);
     if (!parsed.ok) return parsed;
     const input = parsed.data;
+    if (this.context.readOnlyChild) {
+      if (input.action !== "inspect")
+        return failure("permission_denied", "child sessions can only inspect the task summary");
+      const task = this.store.readTask(input.taskId);
+      if (!task.ok) return task;
+      const summary = this.summary(task.data);
+      return summary.ok ? { ...summary, data: boundTaskSummary(summary.data) } : summary;
+    }
     if ((this.context.workerId ?? null) !== null) {
       if (input.action !== "inspect" && input.action !== "list")
         return failure("permission_denied", "helpers cannot control task lifecycle or scope");

package/src/core/task-evaluation.ts

@@ -18,6 +18,8 @@ import {
   type EvidenceEvaluation,
   type Outcome,
   type Requirement,
+  type TaskBrief,
+  type TaskSummary,
   type Result,
   type Scope,
   type TaskRecord,
@@ -1074,3 +1076,72 @@ export function evaluateClosure(
     requirementIds: evaluations.map((item) => item.requirementId),
   });
 }
+
+export const TASK_BRIEF_MAX_BYTES = 4096;
+const BRIEF_TEXT = 250;
+const BRIEF_BLOCKERS = 3;
+const BRIEF_OPEN = 8;
+
+/** Cut `value` until its JSON-escaped form fits `BRIEF_TEXT` bytes. */
+const clip = (value: string): string => {
+  const fits = (text: string) => Buffer.byteLength(JSON.stringify(text)) <= BRIEF_TEXT;
+  if (fits(value)) return value;
+  let length = Math.min(value.length, BRIEF_TEXT);
+  while (length > 0 && !fits(`${value.slice(0, length)}…`)) length -= 1;
+  return `${value.slice(0, length)}…`;
+};
+
+/**
+ * Bound a task summary for `inspect --view summary`: text is clipped, lists
+ * capped and the policy reduced to the requirements still owed, so the JSON
+ * stays under {@link TASK_BRIEF_MAX_BYTES} however long the task history is.
+ */
+export function boundTaskSummary(summary: TaskSummary): TaskBrief {
+  const rules = new Map((summary.policy?.requirements ?? []).map((item) => [item.id, item]));
+  const unmet = summary.requirements.filter(
+    (item) => item.status === "unsatisfied" || item.status === "unavailable",
+  );
+  const { progress, closure } = summary;
+  const next = progress.nextAction;
+  const open = unmet.slice(0, BRIEF_OPEN).map((item) => ({
+    dimension: rules.get(item.requirementId)?.dimension ?? "verification",
+    before: rules.get(item.requirementId)?.before ?? "close",
+    status: item.status,
+  }));
+  const brief: TaskBrief = {
+    id: summary.id,
+    revision: summary.revision,
+    workspaceRevision: summary.workspaceRevision,
+    updatedAt: summary.updatedAt,
+    objective: clip(summary.objective),
+    status: summary.status,
+    closure: closure && {
+      outcome: closure.outcome,
+      at: closure.at,
+      summary: clip(closure.summary),
+    },
+    progress: {
+      summary: clip(progress.summary),
+      nextAction: next && clip(next),
+      blockers: progress.blockers.slice(0, BRIEF_BLOCKERS).map((item) => ({
+        reason: clip(item.reason),
+        dependentAction: clip(item.dependentAction),
+      })),
+    },
+    requirements: { total: summary.requirements.length, unmet: unmet.length, open },
+    truncated: false,
+  };
+  brief.truncated =
+    JSON.stringify(brief).includes("…") ||
+    progress.blockers.length > BRIEF_BLOCKERS ||
+    unmet.length > BRIEF_OPEN;
+  return brief;
+}
+
+/** For a child or unattested caller: `task inspect` with the summary view returns the brief. */
+export function briefInspectResult(request: unknown, result: Result<unknown>): Result<unknown> {
+  const { action, view } = (request ?? {}) as { action?: unknown; view?: unknown };
+  return result.ok && action === "inspect" && (view ?? "summary") === "summary"
+    ? { ...result, data: boundTaskSummary(result.data as TaskSummary) }
+    : result;
+}

package/src/core/workers.ts

@@ -51,3 +51,12 @@ export const workerBlocksTransition = (
   transition: "pause" | "resume" | "revise" | "close",
   state: WorkerState,
 ): boolean => (transition === "pause" ? false : isUncertainWorker(state));
+
+/**
+ * A worker may be continued in its own session only while it holds live
+ * state: a running process, or uncommitted changes in its worktree. A worker
+ * that reported and is clean is continued by a fresh worker on the same
+ * slice. An unreadable worktree counts as no live state.
+ */
+export const holdsLiveState = (state: WorkerState, dirty: boolean | null): boolean =>
+  state === "running" || dirty === true;