@miadi/connector 0.1.19 → 0.1.20

package/dist/tools.js

@@ -16,17 +16,22 @@ import { reviewIdOf, videoIdOf } from "./reviews.js";
 import { SCOPE_APPROVE, SCOPE_CONTRIBUTE } from "./oauth.js";
 import { CIRCLES, CIRCLE_IDS, CLAIM_CATEGORIES, DOMAINS, HANDOFF_STATES, current, newRecordId, } from "./records.js";
 import { VERSION } from "./version.js";
-import { AlreadyDecided, DECISIONS, DecisionConflict, KIND_LABELS, STILL_RUNNING, StaleVersion, approvalStateOf, consequenceOf, decide, decisionWaitOf, isApprovable, isBeingDecided, logDecision, readQueueState, requestProjection, settleWithin, } from "./approve.js";
+import { AlreadyDecided, DECISIONS, DecisionConflict, KIND_LABELS, ProviderChoiceRequired, STILL_RUNNING, StaleVersion, approvalStateOf, consequenceOf, decide, decisionWaitOf, isApprovable, isBeingDecided, logDecision, readQueueState, requestProjection, settleWithin, } from "./approve.js";
 import { RevisionRefused, requestHistory, revisionRecord, supersedeRecords, versionOf } from "./revisions.js";
 import { DECISIONS_CARD_HTML, DECISIONS_CARD_URI, DECISION_TOKENS_META } from "./decisions.js";
 import { discoverProviders, jevConfigOf, resolveProvider, routerPreflight, PROVIDERS } from "./providers.js";
 import { authorizesActions, missionStatus, primaryIssueOf, resolveMissionSubject } from "./mission-status.js";
+import { authorizationReceipt, authorizeProvider, CHOICE_PROVIDERS, isPersonId, needsPersonChoice, providerPolicyOf } from "./provider-policy.js";
 import { candidatesFor, CRITICALITIES, jevAdapter, modelPreflight, PREFLIGHT_CONTRACT, PREFLIGHT_VERSION, TASK_TYPES, } from "./model-preflight.js";
 import { checkGrant, isBusy, steerAttempts, steeringGrantOf, steerSession } from "./steer.js";
 import { factoryLedgerPath, readFactoryReceipts, receiptsForRecord, recordsForSession } from "./factory-receipt.js";
 import { missionResult, redactResult } from "./mission-result.js";
 import { factoryDir as defaultFactoryDir } from "./queue-state.js";
 import { join } from "node:path";
+import { readingScope, canonicalVideo, suppliedDialogue } from "./reading/contract.js";
+import { workflowId } from "./reading/workflow.js";
+import { readingTask } from "./reading/adapters.js";
+import { canReadReading, readingOwner } from "./reading/privacy.js";
 import { artefactVisibility, readArtefactWeave, saveResearchArtefact } from "@miadi/inquiry-weave";
 import { ResearchUploads, UploadRefusal } from "./uploads.js";
 import { DEFAULT_PAGE_BYTES, FOUNDATIONS_PERMISSION, FileRefusal, MAX_TEXT_BYTES, MIN_PAGE_BYTES, TEXT_TYPES, checkRelativePath, episodeNumberOf, extensionOf, fileRef, holdsFoundationRead, isFoundationDoc, pageOf, parseFileRef, } from "./episode-files.js";
@@ -179,7 +184,14 @@ export function registerTools(server, ctx) {
     const redact = (r) => {
         if (!viewer || viewer.api_tier === "write" || r.actor.person_id === viewer.id)
             return r;
+        if (r.body.reading && r.kind === "observation") {
+            const stage = r.body.reading;
+            return { ...r, refs: [], evidence_refs: [], body: { reading: { workflow_id: stage.workflow_id, stage: stage.stage, status: stage.status, sha256: stage.sha256, visibility: "source_owner_or_factory_operator" } } };
+        }
         const body = { ...r.body };
+        // Grants contain source rights and locators; only the owner and operators inspect them.
+        if (body.reading)
+            body.reading = { visibility: "source_owner_or_factory_operator" };
         // A steer's binding, pane, target and artifact path name the seat as the session does (#922 R2).
         for (const k of ["session", "cwd", "session_id", "binding", "pane"])
             delete body[k];
@@ -222,7 +234,47 @@ export function registerTools(server, ctx) {
     };
     /** Every record, folded; for logic. What a tool returns goes through `shown`. */
     const all = () => current(ledger.all());
-    const records = () => all().map(redact);
+    const records = () => {
+        const raw = all();
+        // Completion results can contain exact drafts too. Hide their parent mission as
+        // well, so missionStatus/get_run_result cannot rehydrate it from trusted records.
+        return raw.filter(r => !viewer || canReadReading(r, raw, viewer)).map(r => {
+            // The source owner can read a factory-authored result for their private mission.
+            if (readingOwner(r, raw) === viewer?.id)
+                return r;
+            return redact(r);
+        });
+    };
+    /** Which provider a run may launch with and who authorized it, as every surface shows it (jgwill/Miadi#926). */
+    const providerAuthorizationOf = (r) => r && r.kind === "run_request" ? authorizeProvider(r, ledger.all(), { requireFresh: r.approval_state === "awaiting_approval" }) : undefined;
+    const authorizationOut = (a) => ({
+        ...authorizationReceipt(a),
+        explanation: a.explanation,
+        ...(a.not_binding ? { not_binding: a.not_binding } : {}),
+    });
+    /** A mission's status with the authorization of its provider, and a note when the provider that ran was never authorized. */
+    const withProviderAuthorization = (status) => {
+        const subject = status?.subject?.id ? all().find((r) => r.id === status.subject.id) : undefined;
+        const a = providerAuthorizationOf(subject);
+        if (!a)
+            return status;
+        // An approval records the authorization it was given; a run approved before jgwill/Miadi#926 recorded none.
+        const given = subject?.completion_receipt?.provider_authorization;
+        const actual = typeof status.provider?.actual === "string" ? status.provider.actual : null;
+        const unauthorizedLaunch = Boolean(actual && needsPersonChoice(actual) && !a.authorized && !given?.authorized);
+        return {
+            ...status,
+            provider_authorization: { ...authorizationOut(a), ...(given ? { at_approval: given } : {}), ...(unauthorizedLaunch ? { launched_without_authorization: true } : {}) },
+            ...(unauthorizedLaunch
+                ? {
+                    notes: [
+                        ...(Array.isArray(status.notes) ? status.notes : []),
+                        `${actual} ran for this mission without ${a.requester.name}'s own choice for it on record (jgwill/Miadi#926). Nothing was stopped or re-run because of it.`,
+                    ],
+                }
+                : {}),
+        };
+    };
     const uploads = new ResearchUploads(join(config.stateDir, "uploads"));
     const touching = (ref) => records().filter((r) => r.refs.includes(ref) || r.evidence_refs.includes(ref) || r.id === ref);
     /** The factory runner's delivery receipts, read fresh: operator data, for the write tier only. */
@@ -248,6 +300,13 @@ export function registerTools(server, ctx) {
             service: "@miadi/connector",
             version: VERSION,
             contract: "jgwill/Miadi#815 Connector v2, jgwill/Miadi#816 Review Bridge",
+            reading_workflow: {
+                contract: "transcript-first-v1",
+                provider_runtime: process.env.MIADI_READING_ADAPTER ? "host_configured_not_verified" : "not_configured",
+                transcript_store: "private connector ledger source-part receipts before generation",
+                import: "blocked_until_authenticated_sha256_cas_v1_handshake",
+                publication: "separate_exact_candidate_approval",
+            },
             signed_in_as: { person_id: person.id, name: person.name, role: person.role ?? null, miadi_api_tier: person.api_tier, via: auth.clientId },
             scopes: auth.scopes,
             can_contribute: auth.scopes.includes(SCOPE_CONTRIBUTE),
@@ -732,7 +791,7 @@ export function registerTools(server, ctx) {
     }, wrap(async ({ ref }, extra) => {
         const { person } = who(extra);
         const writeTier = person.api_tier === "write";
-        return missionStatus(ref.trim(), records(), {
+        return withProviderAuthorization(await missionStatus(ref.trim(), records(), {
             projectOf: (r) => requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
             queueOf: (r) => (r.kind === "run_request" || r.kind === "work_proposal" ? readQueueState(r, ctx.factoryDir) : undefined),
             // Without a lister the host cannot say which sessions live: unknown, never "absent" (jgwill/Miadi#909).
@@ -788,11 +847,11 @@ export function registerTools(server, ctx) {
                 return { state: i.state, title: i.title };
             },
             liveVersionOf: (pkg) => (pkg === "@miadi/connector" ? VERSION : undefined),
-        });
+        }));
     }));
     server.registerTool("provider_capabilities", {
         title: "Which agent providers this host can launch",
-        description: "The provider reality of the connector host (jgwill/Miadi#893): which agent CLIs are installed, their versions, whether sign-in evidence exists, the preference order (Codex, Pi, Copilot; Claude Code only on explicit request), and the read-only Jev routing preflight. No token is read or shown. Needs Miadi's write tier: this is host truth.",
+        description: "The provider reality of the connector host (jgwill/Miadi#893): which agent CLIs are installed, their versions, whether sign-in evidence exists, the preference order (Pi, Copilot by default; Codex and Claude Code only when a request names them), the rule that a named Codex runs only on the requester's own choice for that mission or their own policy (jgwill/Miadi#926), your own provider policy, and the read-only Jev routing preflight. No token is read or shown. Needs Miadi's write tier: this is host truth.",
         inputSchema: {},
         annotations: READ,
     }, wrap(async (_args, extra) => {
@@ -801,9 +860,12 @@ export function registerTools(server, ctx) {
         return {
             preference_order: PROVIDERS.map((p) => p.id),
             explicit_only: PROVIDERS.filter((p) => !p.selectable_by_default).map((p) => p.id),
+            needs_person_choice: [...CHOICE_PROVIDERS],
+            your_policy: providerPolicyOf(ledger.all(), person.id),
+            policy_page: `${config.publicUrl}/providers`,
             providers: discoverProviders(ctx.providersProbe),
             router: await routerPreflight(process.env, ctx.approval?.fetchImpl ?? fetch),
-            note: "A provider name in a task's text selects nothing; request_authorized_run's provider field is verified against this list, and an unavailable provider leaves the mission unstarted.",
+            note: "A provider name in a task's text selects nothing; request_authorized_run's provider field is verified against this list, and an unavailable provider leaves the mission unstarted. A request may name Codex, but it runs only when its requester chooses Codex for that mission on the approval page, or their own policy on the providers page says so; a generic approval, the assistant's provider field, the host's order or Jev never choose it.",
         };
     }));
     server.registerTool("mission_model_preflight", {
@@ -842,7 +904,8 @@ export function registerTools(server, ctx) {
         const body = record.body;
         const provider = (typeof body.resolved_provider === "string" ? body.resolved_provider : typeof body.provider === "string" ? body.provider : null);
         const basis = record.approval_state === "approved" ? "approved" : "requested";
-        const candidates = candidatesFor(discoverProviders(ctx.providersProbe), provider, ctx.modelOf, basis);
+        const authorization = providerAuthorizationOf(record);
+        const candidates = candidatesFor(discoverProviders(ctx.providersProbe), provider, ctx.modelOf, basis, authorization);
         const jevConfig = jevConfigOf(process.env);
         const jev = a.consult_jev ? (ctx.jevAdapter ?? (jevConfig ? jevAdapter(jevConfig, ctx.approval?.fetchImpl ?? fetch) : undefined)) : undefined;
         const configured = Boolean(jevConfig);
@@ -859,6 +922,7 @@ export function registerTools(server, ctx) {
             task: a.task_type,
             criticality: a.criticality,
             candidates,
+            ...(authorization ? { provider_authorization: authorizationOut(authorization) } : {}),
             ...(a.launch ? { launch: a.launch } : {}),
             ...(jev ? { adapter: jev } : { routerWhenAbsent: configured ? "not_requested" : "router_unconfigured" }),
         });
@@ -1064,6 +1128,17 @@ export function registerTools(server, ctx) {
         const video = videoIdOf(a.video);
         if (!video)
             throw new ToolRefusal("invalid_ref", "Give a YouTube URL or an 11-character video id.");
+        const prior = all().find(r => r.kind === "source_intent" && r.actor.person_id === person.id && r.idempotency_key === `${video}:${a.purpose}`);
+        if (prior && prior.body.readiness !== a.readiness) {
+            // Release/withdrawal is an explicit source-owner contribution, not processing authority.
+            const transition = {
+                id: newRecordId("source_intent"), kind: "source_intent", created_at: new Date().toISOString(), actor: actorOf(person, auth), supersedes: prior.id,
+                refs: prior.refs, evidence_refs: [], state: a.readiness === "released_for_review" ? "ready" : a.readiness === "withheld" ? "blocked" : "pending",
+                body: { ...prior.body, readiness: a.readiness, source_readiness_transition: true },
+            };
+            ledger.appendDurable(transition);
+            return all().find(r => r.id === prior.id);
+        }
         return append("source_intent", person, auth, {
             circle: "continuity",
             refs: [...a.refs, `https://youtu.be/${video}`],
@@ -1281,6 +1356,55 @@ export function registerTools(server, ctx) {
         };
     }));
     // ── requests: recorded, approved by a person on the approval page, then run ──
+    server.registerTool("request_screenwalk_reading", {
+        title: "Release a source for a bounded research reading",
+        description: "One approved run archives the released source transcript before generating V1, an academic survey and a labelled reflective reading. It stops at the exact candidate's editorial gate. No paid fallback, public release, Deep Diver or Chronicle is included. A host runtime adapter must be configured; unavailable providers are reported as blockers.",
+        inputSchema: { scope: readingScope, companion: suppliedDialogue.optional(), ...base },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        const scope = readingScope.parse(a.scope);
+        const source = all().find(r => r.id === scope.source_intent);
+        if (!source || source.kind !== "source_intent" || source.actor.person_id !== person.id || source.state !== "ready" || source.body.readiness !== "released_for_review")
+            throw new ToolRefusal("source_not_released", "The source owner must explicitly register this source as released_for_review before requesting processing.");
+        const video = canonicalVideo(String(source.body.video_id));
+        const id = workflowId(person.id, video, scope.revision_of);
+        if (scope.revision_of) {
+            const prior = ledger.all().find(r => r.kind === "observation" && r.body.reading?.workflow_id === scope.revision_of && r.body.reading?.stage === "registration");
+            const priorRequest = all().find(r => r.kind === "run_request" && r.body.workflow_id === scope.revision_of && r.actor.person_id === person.id && r.approval_state === "approved" && r.body.reading?.source_intent === scope.source_intent);
+            if ((!prior && !priorRequest) || (prior && (prior.actor.person_id !== person.id || prior.body.reading?.video_id !== video)))
+                throw new ToolRefusal("invalid_revision", "A revision must name your prior workflow for the same video.");
+        }
+        const existing = all().find(r => r.kind === "run_request" && r.actor.person_id === person.id && r.body.workflow_id === id);
+        if (existing)
+            return { ...redact(existing), workflow_id: id, approval_url: approvalUrl(existing.id), replayed: true, note: "This video's bounded request already exists; read or resume it. The new scope was not substituted." };
+        const resolution = resolveProvider(undefined, discoverProviders(ctx.providersProbe));
+        if (resolution.state !== "ok")
+            return { state: resolution.state, note: "No runtime provider was verified; nothing was queued." };
+        const r = append("run_request", person, auth, {
+            circle: "engineering", refs: [source.id, `https://youtu.be/${video}`], intention: a.intention,
+            idempotency_key: id, approval_state: "awaiting_approval", state: "pending",
+            body: { task: readingTask(scope), reading: scope, ...(a.companion ? { reading_companion: a.companion } : {}), session: `reading-${id.slice(8)}`, workflow_id: id, resolved_provider: resolution.provider.id },
+        });
+        return { ...r, workflow_id: id, approval_url: approvalUrl(r.id), gates: ["editorial_public_import", "deep_diver", "chronicle", "cultural_reuse"] };
+    }));
+    server.registerTool("request_reading_import", {
+        title: "Approve the exact staged reading for public import",
+        description: "Request a separate editorial decision for one candidate hash and its exact base. Import is a public release; it refuses legacy unconditional writes. Does not authorize Deep Diver, Chronicle or further reuse.",
+        inputSchema: { workflow_id: z.string().regex(/^reading:[a-f\d]{32}$/), sha256: z.string().regex(/^[a-f\d]{64}$/), expected_version: z.number().int().min(0), expected_sha256: z.string().regex(/^[a-f\d]{64}$/), public_release: z.literal(true), ...base },
+        annotations: WRITE,
+    }, wrap(async (a, extra) => {
+        const { person, auth } = who(extra);
+        requireContribute(auth);
+        // Read from the existing ledger, without constructing a second workflow store.
+        const candidates = ledger.all().filter(r => r.kind === "observation" && r.body.reading?.workflow_id === a.workflow_id && r.body.reading?.stage === "v3" && r.body.reading?.status === "completed");
+        const candidate = candidates[0]?.body.reading?.artifact;
+        if (!candidate || candidates[0].actor.person_id !== person.id || candidate.sha256 !== a.sha256 || candidate.expected_version !== a.expected_version || candidate.expected_sha256 !== a.expected_sha256)
+            throw new ToolRefusal("candidate_mismatch", "Read this person's staged candidate and request its exact hash and base.");
+        const r = append("run_request", person, auth, { circle: "story", refs: [a.workflow_id], intention: a.intention, idempotency_key: `${a.workflow_id}:import:${a.sha256}`, state: "pending", approval_state: "awaiting_approval", body: { task: "Run node packages/connector/scripts/reading.mjs import <this-run-request-id>. Only import the exact typed reading_import candidate after the service proves atomic CAS and durable idempotency; read it back exactly. Stop on any mismatch. No Deep Diver or Chronicle.", reading_import: { workflow_id: a.workflow_id, sha256: a.sha256, expected_version: a.expected_version, expected_sha256: a.expected_sha256, public_release: true }, reading_preview: { markdown: candidate.markdown, diffs: candidate.diffs, manifest: candidate.manifest } } });
+        return { ...r, approval_url: approvalUrl(r.id), candidate: { sha256: candidate.sha256, bytes: candidate.bytes, diff: candidate.diffs, manifest: candidate.manifest } };
+    }));
     server.registerTool("request_authorized_run", {
         title: "Request a bounded agent run",
         description: "Ask for an agent session to do one bounded task. The request waits for a person with Miadi's write tier to approve it on the returned approval_url; once approved, a brief is queued for the factory intake, which opens or reaches the session within minutes. Read it back with get_run_result. This is for a new mission only: to change a request that still awaits a decision, call revise_pending_request with its id, so the person keeps one card to decide.",
@@ -1294,7 +1418,7 @@ export function registerTools(server, ctx) {
             provider: z
                 .enum(["codex", "pi", "copilot", "claude"])
                 .optional()
-                .describe("The provider the run should launch with, verified installed on the connector host. Claude Code runs only when named explicitly. Unknown or unavailable leaves the mission unstarted."),
+                .describe("The provider the run should launch with, verified installed on the connector host. Name it only when the person asked for that provider for this mission. Claude Code runs only when named. Codex runs only when the person also chooses Codex for this mission on the approval page (or their own policy allows it): naming it here does not choose it for them (jgwill/Miadi#926). Unknown or unavailable leaves the mission unstarted, and nothing falls back to Codex."),
             steering: z
                 .object({
                 max_attempts: z.number().int().min(1).max(20).describe("How many authorized follow-up steers this approval covers."),
@@ -1334,10 +1458,25 @@ export function registerTools(server, ctx) {
                 ...(a.steering ? { steering: a.steering } : {}),
             },
         });
+        const authorization = providerAuthorizationOf(all().find((x) => x.id === r.id) ?? r);
         return {
             ...r,
-            provider: { requested: a.provider ?? null, resolved: resolution.provider.id, explicit: resolution.explicit, version: resolution.provider.version },
+            provider: {
+                requested: a.provider ?? null,
+                resolved: resolution.provider.id,
+                explicit: resolution.explicit,
+                version: resolution.provider.version,
+                authorization: authorizationOut(authorization),
+            },
             approval_url: approvalUrl(r.id),
+            ...(authorization.authorized
+                ? {}
+                : {
+                    // #926 review R4, RR5: a provider is revised to another one, never cleared; a service token cannot choose at all.
+                    next_action: isPersonId(person.id)
+                        ? `Tell ${person.name} that a Codex run needs their own choice on the approval page (${approvalUrl(r.id)}); approving alone, on the page or a card, will not run it. Do not choose for them. If they did not ask for Codex for this mission, revise the request with another provider (pi, copilot or claude).`
+                        : `A request made with a service token cannot run Codex: only a person chooses it, for a request of their own. Revise it with another provider (pi, copilot or claude).`,
+                }),
         };
     }));
     // ── one mission, many versions, one decision (jgwill/Miadi#919) ────────────
@@ -1435,10 +1574,13 @@ export function registerTools(server, ctx) {
             throw error;
         }
         ledger.append(record);
+        // A revision moves the version: a provider choice made for an earlier version no longer binds (jgwill/Miadi#926).
+        const revisedAuthorization = providerAuthorizationOf(all().find((x) => x.id === (record.supersedes ?? record.id)));
         return {
             ...revisionOut(record.supersedes ? { ...record, id: record.supersedes } : record),
             revised: record.revision,
             ...(provider ? { provider } : {}),
+            ...(revisedAuthorization ? { provider_authorization: authorizationOut(revisedAuthorization) } : {}),
             note: `One request, one approval: its page and card now show version ${record.revision.version}. Earlier versions stay readable with get_request_history.`,
         };
     }));
@@ -1878,8 +2020,9 @@ export function registerTools(server, ctx) {
                 created_at: r.created_at,
                 circle: r.circle,
                 intention: r.intention,
-                consequence: consequenceOf(r),
+                consequence: consequenceOf(r, providerAuthorizationOf(r)),
                 detail: detailOf(r),
+                ...(r.kind === "run_request" ? { provider_authorization: authorizationOut(providerAuthorizationOf(r)) } : {}),
                 approval_url: approvalUrl(r.id),
                 projection: requestProjection(r, { reviewBase: ctx.approval?.config.reviewUrl, factoryDir: ctx.factoryDir }),
             }));
@@ -1972,6 +2115,13 @@ export function registerTools(server, ctx) {
                 decided = settled;
             }
             catch (error) {
+                // No projection here: the card shows this message, and the request still awaits a decision (jgwill/Miadi#926).
+                if (error instanceof ProviderChoiceRequired) {
+                    throw new ToolRefusal("provider_choice_required", `${error.message} Open its approval page: ${approvalUrl(r.id)}`, {
+                        approval_url: approvalUrl(r.id),
+                        provider_authorization: authorizationOut(error.authorization),
+                    });
+                }
                 if (error instanceof StaleVersion)
                     throw new ToolRefusal("stale_version", error.message, { projection: projectionNow(), approval_url: approvalUrl(r.id) });
                 // A different decision recorded a moment earlier, by another click or client, is reported with where it stands.
@@ -2086,6 +2236,8 @@ export const TOOL_STATUS = {
     supersede_pending_requests: "live, contribute (retires named earlier requests still waiting and joins them as earlier versions of the one that stands)",
     request_session_steer: "live, contribute, write tier (runs inside an approved run's steering grant, else one scoped human decision; get_capabilities.steering says whether the transport works now)",
     request_review_operation: "live, contribute, needs_approval",
+    request_screenwalk_reading: "live, contribute, needs_approval (host provider adapter required; stops at editorial decision)",
+    request_reading_import: "live, contribute, needs_approval (exact public import; atomic service contract required)",
     request_deep_diver: "live, contribute, needs_approval",
     link_review_to_episode: "live, contribute, needs_approval",
     save_research: "live, contribute (the whole report, in parts when long; saved on the inquiry shelf with its issue, pushed; private by default)",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.19";
+export declare const VERSION = "0.1.20";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.1.19";
+export const VERSION = "0.1.20";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/connector",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "The Miadi connector: one remote MCP service through which a person signed in with their Miadi person token, from ChatGPT or any MCP client, reads sessions, reviews, episodes and circles and records observations, inquiries, handoffs and proposals with their name on each record.",
   "license": "MIT",
   "author": "Miadi",