Worked examples

import { requestAgentHq } from 'jg-agent-hq';
import type { IActionReceipt, IProviderId } from 'jg-agent-hq/contracts';
import { waitUntil } from 'jg-utilities';

/**
 * Creates one native session, sends explicit input and returns actual observations.
 * Start the local controller and sign in to the selected native CLI first. Retain
 * actionIds before calling; inspect those receipts after a lost client response.
 * Acknowledgement is delivery, while completion and tool permission remain native.
 */
export const controlSession = async (input: {
  stateRoot: string;
  workspaceRoot: string;
  provider: IProviderId;
  name: string;
  text: string;
  actionIds: { create: string; message: string };
}) => {
  const { stateRoot } = input;
  const status = await requestAgentHq(stateRoot, { kind: 'status' });
  if (status.kind !== 'status') throw new Error('Expected runtime status');
  const runtimeEpoch = status.result.runtimeEpoch;

  /** Reads the same admitted action; it never retries its native effect. */
  const acknowledged = (actionId: string): Promise<IActionReceipt> =>
    waitUntil(
      async () => {
        const response = await requestAgentHq(stateRoot, { kind: 'receipt', actionId });
        if (response.kind !== 'receipt') throw new Error('Expected action receipt');
        const receipt = response.result;
        if (!receipt || ['queued', 'submitted'].includes(receipt.delivery)) return;
        if (receipt.delivery !== 'acknowledged')
          throw new Error(`Inspect action ${actionId}: ${receipt.delivery}`);
        return receipt;
      },
      { timeoutSeconds: 30, intervalSeconds: 0.1 },
    );

  await requestAgentHq(stateRoot, {
    kind: 'action',
    action: {
      id: input.actionIds.create,
      runtimeEpoch,
      command: {
        kind: 'thread-create',
        provider: input.provider,
        workspaceRoot: input.workspaceRoot,
        name: input.name,
      },
    },
  });
  const created = await acknowledged(input.actionIds.create);
  if (!created.threadId) throw new Error('Creation has no managed thread');
  const threadId = created.threadId;
  const thread = await waitUntil(
    async () => {
      const response = await requestAgentHq(stateRoot, { kind: 'managed-thread', threadId });
      if (response.kind !== 'managed-thread') throw new Error('Expected managed thread');
      if (response.result?.ownership === 'uncertain' || response.result?.state === 'failed')
        throw new Error(`Inspect thread ${threadId} before sending input`);
      return response.result?.state === 'idle' ? response.result : undefined;
    },
    { timeoutSeconds: 30, intervalSeconds: 0.1 },
  );

  await requestAgentHq(stateRoot, {
    kind: 'action',
    action: {
      id: input.actionIds.message,
      runtimeEpoch,
      command: { kind: 'message', threadId, input: { kind: 'text', text: input.text } },
    },
  });
  const receipt = await acknowledged(input.actionIds.message);
  const [liveItems, approvals, usage] = await Promise.all([
    requestAgentHq(stateRoot, { kind: 'live-items', threadId }),
    requestAgentHq(stateRoot, { kind: 'approvals', threadId, state: 'pending' }),
    requestAgentHq(stateRoot, { kind: 'usage', provider: input.provider }),
  ]);
  if (liveItems.kind !== 'live-items' || approvals.kind !== 'approvals' || usage.kind !== 'usage')
    throw new Error('Expected session observations');
  return {
    thread,
    receipt,
    liveItems: liveItems.result,
    approvals: approvals.result.data,
    usage: usage.result,
  };
};

import { requestAgentHq } from 'jg-agent-hq';
import type {
  ICollaborationCommand,
  ICollaborationRequestRecord,
  ICollaborationResponse,
  IRequestSpecification,
} from 'jg-agent-hq/contracts';
import { waitUntil } from 'jg-utilities';

/**
 * Requests a review and returns its exact report reference for author assessment.
 * The host has already created the task, stream, memberships and any selected skill grants.
 * Either agent may use any provider. A null skill selection requires no installed skills.
 * Connect confirmRequest to an actual operator decision; native permissions stay separate.
 */
export const reviewHandoff = async (input: {
  stateRoot: string;
  operatorRef: string;
  taskId: string;
  streamId: string;
  requestIds: { review: string; feedback: string };
  dispatchIds: { review: string; feedback: string };
  review: IRequestSpecification;
  feedback: Omit<IRequestSpecification, 'targetReferences'>;
  confirmRequest: (
    phase: 'review' | 'feedback',
    specification: IRequestSpecification,
  ) => Promise<boolean>;
}): Promise<{
  review: ICollaborationRequestRecord | null;
  feedback: ICollaborationRequestRecord | null;
}> => {
  const call = async (command: ICollaborationCommand): Promise<ICollaborationResponse> => {
    const response = await requestAgentHq(input.stateRoot, {
      kind: 'collaboration',
      actor: { kind: 'host', operatorRef: input.operatorRef },
      command,
    });
    if (response.kind !== 'collaboration') throw new Error('Expected collaboration response');
    return response.result;
  };
  const read = async (requestId: string): Promise<ICollaborationRequestRecord> => {
    const result = await call({ kind: 'request-read', taskId: input.taskId, requestId });
    if (result.kind !== 'request') throw new Error('Expected request');
    return result.request;
  };
  const send = async (phase: 'review' | 'feedback', specification: IRequestSpecification) => {
    if (!(await input.confirmRequest(phase, specification))) return null;
    const id = input.requestIds[phase];
    await call({
      kind: 'message-publish',
      id,
      taskId: input.taskId,
      streamId: input.streamId,
      messageKind: 'request',
      summary: phase === 'review' ? 'Review the selected work' : 'Assess the review findings',
      body: specification.arguments,
      references: specification.targetReferences,
      replyToMessageId: null,
      request: specification,
    });
    await call({
      kind: 'request-dispatch',
      id: input.dispatchIds[phase],
      taskId: input.taskId,
      requestId: id,
    });
    return read(id);
  };
  let review = await send('review', input.review);
  if (review === null) return { review: null, feedback: null };
  // These are bounded host reads, with no inference or replacement request on timeout.
  review = await waitUntil(
    async () => {
      const current = await read(input.requestIds.review);
      return ['resolved', 'canceled', 'interrupted', 'waiting-input'].includes(current.state)
        ? current
        : undefined;
    },
    { timeoutSeconds: 30, intervalSeconds: 0.1 },
  );
  if (review.state !== 'resolved' || review.outcome !== 'completed' || !review.lastReportId)
    return { review, feedback: null };
  const report = await call({
    kind: 'report-read',
    taskId: input.taskId,
    reportId: review.lastReportId,
  });
  if (report.kind !== 'report') throw new Error('Expected report reference');
  const feedback = await send('feedback', {
    ...input.feedback,
    targetReferences: [
      { kind: 'report', reportId: report.result.report.id, sha256: report.result.report.sha256 },
    ],
  });
  return { review, feedback };
};

import { requestAgentHq } from 'jg-agent-hq';
import type {
  IActionEnvelope,
  IPlanActionScope,
  IPlanCommandInput,
  IPlanCheckout,
  IPlanOperatorAction,
  IPlanStatus,
  IPlanTarget,
} from 'jg-agent-hq/contracts';
import { inspectPlan } from 'jg-plans';
import { waitUntil } from 'jg-utilities';

/**
 * Revises a selected sequence through native skills and fresh operator decisions.
 * Supply an available unbound planning thread in the same workspace. The host handles
 * native permissions/questions separately, retains all action IDs before calling,
 * and presents exact source before issuing each approval action. On interruption,
 * inspect those identities and the retained revision; never restart this whole flow
 * to retry an uncertain native effect.
 */
export const revisePlan = async (input: {
  stateRoot: string;
  target: IPlanTarget;
  planningThreadId: string;
  amendments: string;
  begin: IPlanOperatorAction;
  threadIds: string[];
  checkouts: IPlanCheckout[];
  finalize: IPlanOperatorAction;
  nativeActionIds: { plan: string; resume: string; breakdown: string; close: string };
  approvePlan: (source: string, status: IPlanStatus) => Promise<IPlanOperatorAction | null>;
  requestBreakdown: (status: IPlanStatus) => Promise<IPlanOperatorAction | null>;
  approveSequence: (
    source: string | null,
    status: IPlanStatus,
  ) => Promise<IPlanOperatorAction | null>;
  authorize: (status: IPlanStatus) => Promise<{
    action: IPlanOperatorAction;
    mode: 'supervised' | 'auto';
    milestoneIds: string[];
  } | null>;
  planningTimeoutSeconds?: number;
}): Promise<IPlanStatus> => {
  const { stateRoot, target, planningThreadId: threadId } = input;
  const runtime = await requestAgentHq(stateRoot, { kind: 'status' });
  if (runtime.kind !== 'status') throw new Error('Expected runtime status');
  const runtimeEpoch = runtime.result.runtimeEpoch;
  const waitOptions = { timeoutSeconds: input.planningTimeoutSeconds ?? 300, intervalSeconds: 0.2 };

  /** Reads current authority without treating a native turn as approval. */
  const status = async (): Promise<IPlanStatus> => {
    const response = await requestAgentHq(stateRoot, {
      kind: 'plan',
      command: { kind: 'status', target },
    });
    if (response.kind !== 'plan' || response.result.kind !== 'status')
      throw new Error('Expected plan status');
    return response.result.result;
  };
  /** Submits one explicit operator command with the current semantic revision. */
  const plan = (command: IPlanCommandInput) => requestAgentHq(stateRoot, { kind: 'plan', command });
  /** Waits for actual native delivery/completion; permission replies remain with the host. */
  const native = async (action: IActionEnvelope, completed = false) => {
    await requestAgentHq(stateRoot, { kind: 'action', action });
    return waitUntil(async () => {
      const response = await requestAgentHq(stateRoot, { kind: 'receipt', actionId: action.id });
      if (response.kind !== 'receipt') throw new Error('Expected action receipt');
      const receipt = response.result;
      if (!receipt) return;
      if (
        ['uncertain', 'failed', 'canceled'].includes(receipt.delivery) ||
        (receipt.completion && receipt.completion !== 'completed')
      )
        throw new Error(`Inspect native action ${action.id} before continuing`);
      return receipt.delivery === 'acknowledged' &&
        (!completed || receipt.completion === 'completed')
        ? receipt
        : undefined;
    }, waitOptions);
  };
  /** Uses the exact native inventory identity, never a fabricated skill name as input. */
  const invoke = async (name: 'jg-plan' | 'jg-breakdown', scope: IPlanActionScope, id: string) => {
    const catalog = await requestAgentHq(stateRoot, {
      kind: 'skills',
      threadId,
      search: name,
      limit: 128,
    });
    if (
      catalog.kind !== 'skills' ||
      catalog.result.state === 'unavailable' ||
      catalog.result.nextCursor
    )
      throw new Error('Select a complete available native skill inventory');
    const skills = catalog.result.data.filter(
      (skill) => skill.name === name && skill.isEnabled && skill.kind !== 'unavailable',
    );
    if (skills.length !== 1) throw new Error(`Expected one available ${name} skill`);
    await native(
      {
        id,
        runtimeEpoch,
        plan: scope,
        command: {
          kind: 'message',
          threadId,
          input: {
            kind: 'skill',
            skillId: skills[0]!.id,
            arguments: `Use the exact selected directory ${JSON.stringify(target.directory)}. ${name === 'jg-plan' ? input.amendments : 'Refresh coverage while retaining verified work and milestone identities.'}`,
          },
        },
      },
      true,
    );
  };

  await plan({
    kind: 'begin-revision',
    target,
    action: input.begin,
    expected: (await status()).revision,
    intent: 'plan',
    threadIds: input.threadIds,
    checkouts: input.checkouts,
  });
  await waitUntil(async () => {
    const current = await status();
    if (current.coordination.revision?.phase === 'blocked')
      throw new Error('Inspect the blocked revision');
    return current.coordination.revision?.phase === 'editing' ? current : undefined;
  }, waitOptions);
  await invoke(
    'jg-plan',
    { kind: 'planning', revisionId: input.begin.id, invocationId: input.begin.id },
    input.nativeActionIds.plan,
  );
  let current = await status();
  const observed = await inspectPlan(target.directory);
  if (observed.plan.state !== 'readable' || observed.plan.sha256 !== current.inspection.plan)
    throw new Error('Present the current plan again after the source change');
  const approval = await input.approvePlan(observed.plan.value.source, current);
  if (!approval) return current;
  await plan({
    kind: 'approve',
    target,
    action: approval,
    expected: current.revision,
    scope: 'plan',
    presentationHash: observed.plan.sha256,
  });

  current = await status();
  const breakdown = await input.requestBreakdown(current);
  if (!breakdown) return current;
  await plan({
    kind: 'revision-invoke',
    target,
    action: breakdown,
    expected: current.revision,
    revisionId: input.begin.id,
    skill: 'jg-breakdown',
  });
  await waitUntil(async () => {
    const current = await status();
    if (current.coordination.revision?.phase === 'blocked')
      throw new Error('Inspect the blocked revision');
    return current.coordination.revision?.phase === 'editing' ? current : undefined;
  }, waitOptions);
  const scope = {
    kind: 'planning' as const,
    revisionId: input.begin.id,
    invocationId: breakdown.id,
  };
  await native({
    id: input.nativeActionIds.resume,
    runtimeEpoch,
    plan: scope,
    command: { kind: 'thread-resume', threadId, operatorConfirmation: breakdown.source.reference },
  });
  await invoke('jg-breakdown', scope, input.nativeActionIds.breakdown);
  await native({
    id: input.nativeActionIds.close,
    runtimeEpoch,
    command: { kind: 'thread-close', threadId },
  });

  current = await status();
  // finalization records jg-breakdown's milestone IDs and carries completion evidence by ID
  const finalized = await plan({
    kind: 'finalize',
    target,
    action: input.finalize,
    expected: current.revision,
  });
  if (finalized.kind !== 'plan' || finalized.result.kind !== 'finalized')
    throw new Error('Expected finalized presentation');
  current = finalized.result.result;
  const sequenceApproval = await input.approveSequence(finalized.result.content, current);
  if (!sequenceApproval) return current;
  if (finalized.result.content !== null)
    await plan({
      kind: 'approve',
      target,
      action: sequenceApproval,
      expected: current.revision,
      scope: 'sequence',
      presentationHash: current.inspection.milestones!,
    });
  current = await status();
  const execution = await input.authorize(current);
  if (!execution) return current;
  await plan({ kind: 'authorize', target, expected: current.revision, ...execution });
  return status();
};