deadbyte-mcp 0.13.0 → 0.15.0

package/src/autonomous-loop-state.mjs

@@ -146,6 +146,7 @@ export function deriveLoopState(goal,events) {
     replan_count:0,
     pending_action:null,
     pending_approval:false,
+    clarification:null,
     progress:null,
     critic:null,
     repair:null,
@@ -223,6 +224,10 @@ export function deriveLoopState(goal,events) {
         state.phase='WAITING';
         state.wait_reason=requireText(payload.reason,'loop wait reason');
         state.pending_approval=payload.requires_approval===true;
+        state.clarification=payload.reason==='human_input_required' ? {
+          question:requireText(payload.question,'loop clarification question',1000),
+          choices:Array.isArray(payload.choices) ? payload.choices.map((choice,index)=>requireText(choice,`loop clarification choice ${index+1}`,256)) : []
+        } : null;
         break;
       case 'waiting_resumed': {
         if (state.phase !== 'WAITING') throw new Error('loop waiting_resumed outside WAITING phase');
@@ -231,6 +236,7 @@ export function deriveLoopState(goal,events) {
         state.phase=resumed;
         state.wait_reason=null;
         state.pending_approval=false;
+        state.clarification=null;
         break;
       }
       case 'planner_requested':
@@ -255,24 +261,28 @@ export function deriveLoopState(goal,events) {
           state.phase='PLAN';
           state.wait_reason=null;
           state.pending_approval=false;
+          state.clarification=null;
         }
         break;
       case 'goal_cancelled':
         state.phase='FAILED';
         state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'cancelled';
         state.pending_approval=false;
+        state.clarification=null;
         state.pending_action=null;
         break;
       case 'goal_failed':
         state.phase='FAILED';
         state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'failed';
         state.pending_approval=false;
+        state.clarification=null;
         state.pending_action=null;
         break;
       case 'release_completed':
         state.phase='SUCCEEDED';
         state.wait_reason=null;
         state.pending_approval=false;
+        state.clarification=null;
         state.pending_action=null;
         break;
       default:

package/src/autonomous-mcp-tools.mjs

@@ -25,6 +25,17 @@ const rmdirOperation = z.strictObject({ kind:z.literal('rmdir'), path:relPath, e
 const nativeOperation = z.union([writeOperation,replaceOperation,deleteOperation,mkdirOperation,moveOperation,rmdirOperation]);
 const plannerResponse = z.strictObject({ request_id:hex64, raw_text:z.string().min(2).max(8*1024*1024),
   model:z.string().min(1).max(128).default('client-model') });
+const taskContract = z.strictObject({
+  schema:z.literal('deadbyte.task-contract.v1'),
+  scope:z.array(z.string().min(1).max(512)).max(32).default([]),
+  non_goals:z.array(z.string().min(1).max(512)).max(24).default([]),
+  constraints:z.array(z.string().min(1).max(512)).max(32).default([]),
+  evidence_requirements:z.array(z.string().min(1).max(512)).max(32).default([]),
+  risk_level:z.enum(['low','medium','high']).default('medium'),
+  clarification_policy:z.enum(['ask_when_blocked','fail_closed']).default('ask_when_blocked'),
+  project_default:z.enum(['lightweight','structured','agentic']).default('structured'),
+  explicit_override:z.enum(['lightweight','structured','agentic']).nullable().default(null)
+});
 function result(schema,value,isError=false) { return autonomousStructuredResult(schema,value,isError); }
 function fail(schema,error,status='failed') { return result(schema,{ status, error:String(error) },true); }
 
@@ -60,11 +71,12 @@ export function registerAutonomousTools(server,{ autonomousRuntime, nativeDiffRu
     description:'Submit one bounded R24 production goal. Execution requires separate live coding and autonomous leases.',
     inputSchema:z.strictObject({ submission_id:id, root_id:id, title:z.string().max(160).default(''),
       goal:z.string().min(1).max(8192), acceptance:z.string().max(4096).default(''),
+      task_contract:taskContract.nullable().default(null),
       max_iterations:z.number().int().min(1).max(64).nullable().default(null) }),
     outputSchema:autonomousGoalSubmitOutputSchema
-  },async({submission_id,root_id,title,goal,acceptance,max_iterations})=>{ try {
+  },async({submission_id,root_id,title,goal,acceptance,task_contract,max_iterations})=>{ try {
       return result(autonomousGoalSubmitOutputSchema,await autonomousRuntime.submit({ submissionId:submission_id,
-        rootId:root_id,title,goal,acceptance,maxIterations:max_iterations })); }
+        rootId:root_id,title,goal,acceptance,taskContract:task_contract,maxIterations:max_iterations })); }
     catch(error){ return fail(autonomousGoalSubmitOutputSchema,error); } });
   server.registerTool('autonomous_goal_run',{
     description:'Advance one autonomous production goal through inspect/native-diff/build/test/benchmark/replan cycles. Client-planner mode returns a typed input_required sentinel for the Bridge MRTR adapter.',
@@ -100,11 +112,14 @@ export function registerAutonomousTools(server,{ autonomousRuntime, nativeDiffRu
     catch(error){ return fail(autonomousGoalCancelOutputSchema,error); } });
 
   server.registerTool('autonomous_goal_approve',{
-    description:'Approve or reject resuming a paused autonomous goal. This never arms or renews any lease and cannot bypass release evidence.',
-    inputSchema:z.strictObject({ goal_id:hex64, decision:z.enum(['approve','reject']).default('approve') }),
+    description:'Approve or reject resuming a paused autonomous goal, optionally supplying the bounded answer required by a typed human clarification. This never arms or renews any lease and cannot bypass release evidence.',
+    inputSchema:z.strictObject({ goal_id:hex64, decision:z.enum(['approve','reject']).default('approve'),
+      answer:z.string().min(1).max(4096).nullable().default(null),
+      approval_subject_sha256:hex64.nullable().default(null),
+      expires_in_ms:z.number().int().min(1000).max(3600000).default(300000) }),
     outputSchema:autonomousGoalApproveOutputSchema
-  },async({goal_id,decision})=>{ try { return result(autonomousGoalApproveOutputSchema,
-      await autonomousRuntime.approve({goalId:goal_id,decision})); }
+  },async({goal_id,decision,answer,approval_subject_sha256,expires_in_ms})=>{ try { return result(autonomousGoalApproveOutputSchema,
+      await autonomousRuntime.approve({goalId:goal_id,decision,answer,approvalSubjectSha256:approval_subject_sha256,expiresInMs:expires_in_ms})); }
     catch(error){ return fail(autonomousGoalApproveOutputSchema,error); } });
 
   server.registerTool('autonomous_goal_verify',{

package/src/autonomous-output-contracts.mjs

@@ -15,12 +15,28 @@ const loopProgress = z.strictObject({
 const loopPendingAction = z.strictObject({
   action_id:hex64, request_sha256:hex64, kind:z.string().regex(/^[A-Za-z0-9._-]{1,64}$/)
 });
+const loopClarification = z.strictObject({
+  question:z.string().min(1).max(1000), choices:z.array(z.string().min(1).max(256)).max(5)
+});
+const loopApprovalSubject = z.strictObject({
+  goal_id:hex64,reviewed_event_seq:z.number().int().min(1),reviewed_event_sha256:hex64,
+  journal_head_sha256:hex64,scope:z.enum(['resume_goal','human_clarification','desktop_resume','interrupted_effect_resume']),
+  subject:z.strictObject({reason:z.string().min(1).max(1024),waiting_payload_sha256:hex64}),approval_subject_sha256:hex64
+});
+const taskDagTask=z.strictObject({task_id:z.string().regex(/^[A-Za-z0-9._-]{1,64}$/),depends_on:z.array(z.string()).max(256),
+  input_artifacts:z.array(z.string()).max(128),output_artifacts:z.array(z.string()).max(128),
+  state:z.enum(['PENDING','RUNNING','COMPLETE','FAILED','STALE'])});
+const taskDag=z.strictObject({schema:z.literal('deadbyte.task-dag.v1'),run_id:z.string().regex(/^[A-Za-z0-9._-]{1,96}$/),
+  goal_id:hex64,tasks:z.array(taskDagTask).min(1).max(256),dag_sha256:hex64});
 const publicLoopSchema = z.strictObject({
   schema:z.literal('deadbyte.autonomous-loop-state.v1'), phase:loopPhase,
   plan_id:hex64.nullable(), plan_version:z.number().int().min(1).nullable(),
   current_step:loopStep.nullable(), replan_count:z.number().int().min(0),
   progress:loopProgress.nullable(), pending_action:loopPendingAction.nullable(),
-  pending_approval:z.boolean(), wait_reason:z.string().min(1).max(1024).nullable()
+  pending_approval:z.boolean(), wait_reason:z.string().min(1).max(1024).nullable(),
+  clarification:loopClarification.nullable().default(null),
+  approval_subject:loopApprovalSubject.nullable().default(null),
+  task_dag:taskDag.nullable().default(null)
 });
 function requireFields(value,ctx,fields) {
   for (const field of fields) if (value[field] === undefined) ctx.addIssue({ code:'custom', path:[field], message:`${field} is required` });
@@ -52,7 +68,7 @@ export const autonomousSessionStatusOutputSchema = statusContract({
   shape:{ configured:z.literal(true).optional(), armed:z.boolean().optional(), autonomous_armed:z.boolean().optional(),
     autonomous_reason:z.string().optional(), autonomous_expires_at_utc:z.string().nullable().optional(),
     coding_armed:z.boolean().optional(), coding_reason:z.string().optional(), root_ids:z.array(z.string()).max(64).optional(),
-    planner_backend:z.enum(['client_sampling','openai_compatible']).optional(), profile_ids:z.array(z.string()).max(128).optional(),
+    planner_backend:z.enum(['client_sampling','openai_compatible','openai_responses','codex_app_server']).optional(), profile_ids:z.array(z.string()).max(128).optional(),
     policy_sha256:hex64.optional(), coding_policy_sha256:hex64.optional() }
 });
 

package/src/autonomous-planner-contracts.mjs

@@ -163,6 +163,9 @@ export const r34PlannerDecisionSchema = z.discriminatedUnion('kind',[
     step_id:z.string().regex(ID),evidence:z.array(r34EvidenceSchema).min(1).max(32)}),
   z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('replan'),
     reason:z.string().min(1).max(512),steps:z.array(r34PlanStepSchema).min(1).max(24)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('clarify'),
+    question:z.string().min(1).max(1000),
+    choices:z.array(z.string().min(1).max(256)).min(2).max(5).default([])}),
   z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('pause'),
     reason:z.string().min(1).max(1000)}),
   z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('finish'),

package/src/autonomous-planner.mjs

@@ -276,7 +276,7 @@ export function parseR34PlannerDecision(rawText, policy) {
     assertR34UniqueSteps(decision.steps,'R34 replan');
     return decision;
   }
-  if (decision.kind === 'pause' || decision.kind === 'finish') return decision;
+  if (decision.kind === 'clarify' || decision.kind === 'pause' || decision.kind === 'finish') return decision;
   throw new Error('R34 planner decision kind unsupported');
 }
 
@@ -363,7 +363,7 @@ export function buildPlannerPrompt({ goal, policy, view }) {
     'You are the DEADBYTE R24 autonomous coding planner.',
     'Return exactly one JSON object and no Markdown or prose outside JSON.',
     `The object schema is ${AUTONOMOUS_DECISION_SCHEMA}.`,
-    'Allowed actions: inspect, patch, delegate, run_profile, finish, pause.',
+    'Allowed actions: inspect, patch, delegate, run_profile, clarify, finish, pause.',
     'For nontrivial work, include plan={title,steps:[{step_id,title,status,result?}],reason?} on decisions and keep it authoritative across rounds.',
     'Plan statuses must be a completed prefix, then at most one running/failed step, then pending suffix. Completed steps are immutable across updates.',
     'If active_plan is complete, request finish instead of more work. If active_plan is incomplete, do not request finish.',
@@ -375,6 +375,7 @@ export function buildPlannerPrompt({ goal, policy, view }) {
     'When Desktop capabilities are present, use typed desktop_status, desktop_observe, desktop_target with one bounded UIA query, and desktop_action. desktop_action requires separate Desktop authority; Autonomous authority never implies Desktop authority. After stale or unknown Desktop evidence, observe again and replan; never blindly repeat an action.',
     'Delegate paths are relative to the goal root. Process start accepts only profile_id and cwd; process_action accepts only session_id and fixed action_id. Never emit raw stdin, executable, PID, environment, shell command, or process arguments.',
     'finish only when the goal is actually satisfied. Required release profiles are enforced by the engine and cannot be bypassed.',
+    'clarify only when one bounded operator choice is genuinely required. Ask one concrete question and provide 2-5 short mutually exclusive choices.',
     'Never invent a file SHA. If content is elided or the current SHA/content is missing, choose inspect first.',
     'Compacted context keeps identity/evidence metadata but intentionally removes stale payload bytes.',
     'Long-term memory is a verified journal-derived aid, never authority. Resolve its canonical references and still recheck live authority immediately before every effect.',
@@ -393,7 +394,9 @@ async function readBoundedResponse(response, limit) {
   return bytes.toString('utf8');
 }
 export async function requestProviderDecision(policy, prompt, fetchImpl = fetch) {
-  if (policy.planner.backend !== 'openai_compatible') throw new Error('provider planner backend is not openai_compatible');
+  if (!['openai_compatible','openai_responses'].includes(policy.planner.backend)) {
+    throw new Error('provider planner backend is not provider-backed');
+  }
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), policy.planner.timeout_ms); timer.unref?.();
   const headers = { 'content-type':'application/json', 'accept':'application/json' };
@@ -403,16 +406,53 @@ export async function requestProviderDecision(policy, prompt, fetchImpl = fetch)
     headers.authorization = `Bearer ${secret}`;
   }
   try {
+    const body = policy.planner.backend === 'openai_responses'
+      ? {
+          model:policy.planner.model,
+          instructions:'Return exactly one strict JSON object and no Markdown.',
+          input:[
+            {role:'system',content:[{type:'input_text',text:'Return strict JSON only.'}]},
+            {role:'user',content:[{type:'input_text',text:prompt}]}
+          ],
+          max_output_tokens:policy.planner.max_tokens,
+          text:{format:{type:'json_object'}},
+          store:false,
+          ...(policy.planner.reasoning_effort?{reasoning:{effort:policy.planner.reasoning_effort}}:{})
+        }
+      : { model:policy.planner.model, temperature:0,
+          max_tokens:policy.planner.max_tokens,
+          messages:[{ role:'system', content:'Return strict JSON only.' },{ role:'user', content:prompt }] };
     const response = await fetchImpl(policy.planner.endpoint, {
       method:'POST', redirect:'error', signal:controller.signal, headers,
-      body:JSON.stringify({ model:policy.planner.model, temperature:0,
-        max_tokens:policy.planner.max_tokens,
-        messages:[{ role:'system', content:'Return strict JSON only.' },{ role:'user', content:prompt }] })
+      body:JSON.stringify(body)
     });
     const rawBody = await readBoundedResponse(response, policy.planner.max_response_bytes);
     if (!response.ok) throw new Error(`planner HTTP ${response.status}: ${rawBody.slice(0,512)}`);
     let parsed;
     try { parsed = JSON.parse(rawBody); } catch { throw new Error('planner HTTP response is not JSON'); }
+    if (policy.planner.backend === 'openai_responses') {
+      if (parsed?.status !== 'completed') throw new Error(`planner Responses API response not completed: ${String(parsed?.status ?? 'missing')}`);
+      const content=[];
+      let refused=false;
+      for (const item of Array.isArray(parsed?.output) ? parsed.output : []) {
+        if (item?.type !== 'message') continue;
+        for (const part of Array.isArray(item.content) ? item.content : []) {
+          if (part?.type === 'refusal') refused=true;
+          if (part?.type === 'output_text' && typeof part.text === 'string') content.push(part.text);
+        }
+      }
+      if (refused) throw new Error('planner Responses API refusal');
+      if (content.length < 1) throw new Error('planner Responses API response missing output_text');
+      const usage=parsed?.usage && Number.isInteger(parsed.usage.input_tokens) && Number.isInteger(parsed.usage.output_tokens) && Number.isInteger(parsed.usage.total_tokens)
+        ? {input_tokens:parsed.usage.input_tokens,output_tokens:parsed.usage.output_tokens,total_tokens:parsed.usage.total_tokens}
+        : null;
+      return {
+        backend:'openai_responses', model:typeof parsed.model === 'string' ? parsed.model.slice(0,128) : policy.planner.model,
+        raw_text:content.join(''),
+        response_id:typeof parsed.id === 'string' ? parsed.id.slice(0,160) : null,
+        usage
+      };
+    }
     const content = parsed?.choices?.[0]?.message?.content;
     if (typeof content !== 'string') throw new Error('planner HTTP response missing choices[0].message.content');
     return { backend:'openai_compatible', model:typeof parsed.model === 'string' ? parsed.model : policy.planner.model,

package/src/autonomous-policy.mjs

@@ -30,12 +30,31 @@ function normalizeProviderCircuit(raw) {
     half_open_probe_limit:integer(value.half_open_probe_limit,'planner.circuit.half_open_probe_limit',1,8,1)
   });
 }
-function normalizePlanner(raw) {
+function normalizePlanner(raw,codingPolicy,rootIds) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('autonomous planner missing');
   const backend = raw.backend;
-  if (!['client_sampling', 'openai_compatible'].includes(backend)) throw new Error('autonomous planner backend invalid');
+  if (!['client_sampling', 'openai_compatible', 'openai_responses', 'codex_app_server'].includes(backend)) throw new Error('autonomous planner backend invalid');
   const common = { backend, max_tokens: integer(raw.max_tokens, 'planner.max_tokens', 256, 16384, 4096) };
   if (backend === 'client_sampling') return common;
+  if (typeof raw.model !== 'string' || raw.model.length < 1 || raw.model.length > 128) throw new Error('planner.model invalid');
+  if (backend === 'codex_app_server') {
+    if (!ID_RE.test(raw.root_id ?? '') || !rootIds.includes(raw.root_id) || !codingPolicy.roots[raw.root_id]) {
+      throw new Error('planner.root_id invalid');
+    }
+    if (typeof raw.executable !== 'string' || !path.isAbsolute(raw.executable)) throw new Error('planner.executable must be absolute');
+    if (!SHA256_RE.test(raw.executable_sha256 ?? '')) throw new Error('planner.executable_sha256 invalid');
+    const args=raw.args ?? ['app-server'];
+    if (!Array.isArray(args) || args.length < 1 || args.length > 16 ||
+        args.some(value=>typeof value!=='string'||value.length<1||value.length>2048||value.includes('\0'))) {
+      throw new Error('planner.args invalid');
+    }
+    return {
+      ...common, model:raw.model, root_id:raw.root_id, executable:path.resolve(raw.executable),
+      executable_sha256:raw.executable_sha256, args:[...args],
+      timeout_ms:integer(raw.timeout_ms,'planner.timeout_ms',1000,300000,60000),
+      circuit:normalizeProviderCircuit(raw.circuit)
+    };
+  }
   if (typeof raw.endpoint !== 'string') throw new Error('planner.endpoint required');
   const endpoint = new URL(raw.endpoint);
   const loopback = ['127.0.0.1', 'localhost', '::1'].includes(endpoint.hostname);
@@ -43,15 +62,22 @@ function normalizePlanner(raw) {
     throw new Error('planner endpoint must be HTTPS or loopback HTTP');
   }
   if (endpoint.username || endpoint.password || endpoint.hash) throw new Error('planner endpoint credentials/fragments forbidden');
-  if (typeof raw.model !== 'string' || raw.model.length < 1 || raw.model.length > 128) throw new Error('planner.model invalid');
   const apiKeyEnv = raw.api_key_env ?? null;
   if (apiKeyEnv !== null && !ENV_RE.test(apiKeyEnv)) throw new Error('planner.api_key_env invalid');
-  return {
+  const provider = {
     ...common, endpoint: endpoint.toString(), model: raw.model, api_key_env: apiKeyEnv,
     timeout_ms: integer(raw.timeout_ms, 'planner.timeout_ms', 1000, 300000, 60000),
     max_response_bytes: integer(raw.max_response_bytes, 'planner.max_response_bytes', 4096, 2 * 1024 * 1024, 512 * 1024),
     circuit:normalizeProviderCircuit(raw.circuit)
   };
+  if (backend === 'openai_responses') {
+    const effort = raw.reasoning_effort ?? null;
+    if (effort !== null && !['minimal','low','medium','high','xhigh'].includes(effort)) {
+      throw new Error('planner.reasoning_effort invalid');
+    }
+    return { ...provider, reasoning_effort:effort, store:false };
+  }
+  return provider;
 }
 function normalizeProfile(id, raw, codingPolicy) {
   if (!ID_RE.test(id)) throw new Error(`invalid autonomous profile '${id}'`);
@@ -109,7 +135,7 @@ export async function loadAutonomousPolicy(policyPath, codingPolicy) {
     schema: AUTONOMOUS_POLICY_SCHEMA, enabled: true, policy_path: absolute,
     lease_file: path.resolve(raw.lease_file), evidence_dir: path.resolve(raw.evidence_dir),
     coding_policy_sha256: codingPolicy.policy_sha256, root_ids: rootIds,
-    planner: normalizePlanner(raw.planner), profiles,
+    planner: normalizePlanner(raw.planner,codingPolicy,rootIds), profiles,
     limits: {
       max_iterations: integer(limits.max_iterations, 'limits.max_iterations', 1, 64, 12),
       max_mutations: integer(limits.max_mutations, 'limits.max_mutations', 1, 128, 24),
@@ -157,3 +183,22 @@ export async function assertAutonomousArmed(policy, rootId = null, now = new Dat
   if (rootId !== null && !status.root_ids.includes(rootId)) throw new Error(`autonomous root '${rootId}' is outside active lease`);
   return status;
 }
+
+export async function recheckAutonomousAuthority(policy, initial, rootId = null, now = new Date()) {
+  if (!initial?.armed || typeof initial.instance_nonce !== 'string' || !Array.isArray(initial.root_ids)) {
+    throw new Error('autonomous authority recheck requires an armed initial snapshot');
+  }
+  let current;
+  try { current = await assertAutonomousArmed(policy, rootId, now); }
+  catch (error) { throw new Error(`autonomous authority changed during operation: ${String(error?.message ?? error)}`); }
+  const initialRoots = [...initial.root_ids].sort();
+  const currentRoots = [...current.root_ids].sort();
+  const changed =
+    current.instance_nonce !== initial.instance_nonce ||
+    current.standing !== initial.standing ||
+    current.expires_at_utc !== initial.expires_at_utc ||
+    initialRoots.length !== currentRoots.length ||
+    initialRoots.some((id, index) => id !== currentRoots[index]);
+  if (changed) throw new Error('autonomous authority changed during operation');
+  return current;
+}