@zq-silk/yui 2.10.0 → 2.12.0

package/dist/web/webJobs.js

@@ -5,8 +5,8 @@ import { requireKnownFields } from "../domain/validation.js";
 import { WebRequestRejected, webLocalMutation } from "./webMutation.js";
 /** Local-user ingress only, behind the Web token/origin boundary. Never use
  * this adapter for managed RPC callers. The route fixes scope; the server
- * resolves the current Operator binding on every request. No invented Session
- * or durable second authority: the public services revalidate the binding.
+ * uses public user authority for global controlled actions. Task shell access
+ * still resolves the current Operator binding; no invented Session.
  */
 export function createWebJobs(store, home) {
     function invoke(scope, family, value, write, now) {
@@ -14,21 +14,31 @@ export function createWebJobs(store, home) {
             if (!value || typeof value !== "object" || Array.isArray(value))
                 throw new Error("Expected an operation.");
             requireKnownFields(value, family === "jobs"
-                ? ["op", "id", "title", "configuration", "expectedRevision", "runId", "requestId"]
-                : ["op", "id", "jobId", "rule", "expectedRevision"], "Web Job/Schedule request");
+                ? ["op", "id", "title", "configuration", "expectedRevision", "runId", "requestId",
+                    "reference", "offset", "expectedSessionId"]
+                : ["op", "id", "jobId", "rule", "expectedRevision", "authorization", "target"], "Web Job/Schedule request");
             const input = value;
-            const reads = family === "jobs" ? ["list", "show", "runs", "run-get", "logs"] : ["list", "show"];
-            const writes = family === "jobs" ? ["define", "update", "run", "run-cancel"] : ["create", "update", "enable", "disable"];
+            const reads = family === "jobs" ? ["list", "show", "runs", "run-get", "run-result", "run-evidence",
+                "run-delegation", "logs", "artifact-list", "artifact-preview", "session-inspect"] : ["list", "show"];
+            const writes = family === "jobs" ? ["define", "update", "run", "run-cancel", "artifact-register",
+                "session-stop", "session-new"] : ["create", "update", "enable", "disable"];
             if (!(write ? writes : reads).includes(String(input.op)))
                 throw new Error("Operation is not available on this endpoint.");
             if (scope.kind === "task" && !tx.getTask(scope.taskId))
                 throw new Error("Task not found.");
-            const session = activeLiveRoleAgentSession(tx.getGlobalRoleSessionSet("operator"));
-            if (!session)
-                throw new Error("A current Operator Session is required for Job management.");
-            const caller = { scope: "global", role: "operator", nativeSessionId: session.nativeSessionId,
-                agentId: session.agentId, adapterId: session.adapterId };
+            const session = scope.kind === "task" ? activeLiveRoleAgentSession(tx.getGlobalRoleSessionSet("operator")) : null;
+            if (scope.kind === "task" && !session)
+                throw new Error("A current Operator Session is required for Task Job management.");
+            const caller = session ? { scope: "global", role: "operator", nativeSessionId: session.nativeSessionId,
+                agentId: session.agentId, adapterId: session.adapterId } : { scope: "user" };
             const { requestId, ...fields } = input;
+            if (typeof fields.reference === "string")
+                fields.reference = JSON.parse(fields.reference);
+            if (fields.offset !== undefined) {
+                if (!/^\d{1,9}$/u.test(String(fields.offset)))
+                    throw new Error("Invalid artifact offset.");
+                fields.offset = Number(fields.offset);
+            }
             if (input.op === "run" && (typeof requestId !== "string" || !requestId.trim() || requestId.length > 200)) {
                 throw new Error("Immediate execution requires a stable requestId.");
             }
@@ -36,6 +46,21 @@ export function createWebJobs(store, home) {
                 ...(input.op === "run" ? { trigger: { source: "manual", key: requestId } } : {}) };
             return (family === "jobs" ? createJobDefinitionControl(tx, home) : createScheduleControl(tx, home))(params, now);
         };
+        // Artifact Git I/O is asynchronous, with its own authorization recheck and
+        // short publication transaction. Never keep a SQLite transaction across it.
+        if (family === "jobs" && value && typeof value === "object"
+            && "op" in value && String(value.op).startsWith("artifact-")) {
+            try {
+                return Promise.resolve(apply(store)).catch(error => {
+                    if (!write)
+                        throw new WebRequestRejected(error instanceof Error ? error.message : String(error));
+                    throw error; // A Git/publication failure is not proof of non-submission.
+                });
+            }
+            catch (error) {
+                throw new WebRequestRejected(error instanceof Error ? error.message : String(error));
+            }
+        }
         if (write)
             return webLocalMutation(store, apply);
         try {

package/dist/web/webMaterials.js

@@ -30,24 +30,36 @@ async function fixedImage(home, taskId, input) {
 /** One selected immutable file, never a workspace path or a remote URL.
  * Markdown is bounded and whole so fences/tables are not split by pagination. */
 export async function readArtifactPreview(home, taskId, ref, offset = 0) {
-    if (/\.(svg|gif|avif|bmp|ico|tiff?)$/iu.test(ref.relativePath)) {
+    if (ref.taskId !== taskId)
+        throw new WebRequestRejected("Materials must belong to the same Task.");
+    const valid = validateGitArtifactRef(ref);
+    const file = await resolveGitArtifact(home, valid);
+    return { ...valid, ...previewArtifactContent(file, offset) };
+}
+/** Shared data-only preview for Task and Job evidence; no path lookup or authority. */
+export function previewArtifactContent(file, offset = 0) {
+    if (/\.(svg|gif|avif|bmp|ico|tiff?)$/iu.test(file.relativePath)) {
         throw new WebRequestRejected("Unsupported image format. Save a static PNG, JPEG or WebP instead.");
     }
-    if (isRasterArtifact(ref.relativePath)) {
+    if (file.relativePath.length > 512)
+        throw new WebRequestRejected("Artifact path is too long.");
+    if (isRasterArtifact(file.relativePath)) {
         if (offset !== 0)
             throw new WebRequestRejected("Images do not have text offsets.");
-        return fixedImage(home, taskId, ref);
+        return { digest: file.digest, kind: "image", byteSize: file.bytes.length,
+            ...rasterMetadata(file.bytes), base64: file.bytes.toString("base64") };
     }
-    if (/\.md$|\.markdown$/iu.test(ref.relativePath)) {
+    textPath(file.relativePath);
+    const text = decodeText(file.bytes);
+    if (/\.md$|\.markdown$/iu.test(file.relativePath)) {
         if (offset !== 0)
             throw new WebRequestRejected("Markdown previews start at offset zero.");
-        const file = await fixedText(home, taskId, ref);
-        if (file.bytes > MAX_MATERIAL_BYTES)
+        if (file.bytes.length > MAX_MATERIAL_BYTES)
             throw new WebRequestRejected("Markdown preview exceeds 256 KiB; split the document.");
-        return { ...file.ref, kind: "markdown", byteSize: file.bytes, content: file.text,
-            offset: 0, totalCharacters: file.text.length, nextOffset: null };
+        return { digest: file.digest, kind: "markdown", byteSize: file.bytes.length, content: text,
+            offset: 0, totalCharacters: text.length, nextOffset: null };
     }
-    return readTextArtifactPage(home, taskId, ref, offset);
+    return { digest: file.digest, byteSize: file.bytes.length, ...page(text, offset) };
 }
 function textPath(path) {
     const safe = safeRelativeArtifactPath(path);

package/dist/web/webServer.js

@@ -284,15 +284,16 @@ async function handleHttpRequest(request, response, store, dependencies, token,
             let value;
             if (method === "GET") {
                 const query = new URL(request.url, "http://localhost").searchParams;
-                if ([...query.keys()].some(key => !["op", "id", "runId"].includes(key)))
-                    throw new WebRequestRejected("Unknown Job query.");
-                value = dependencies.jobs.read(scope, family, Object.fromEntries(query), now());
+                if ([...query.keys()].some(key => !["op", "id", "runId", "reference", "offset"].includes(key)
+                    || query.getAll(key).length !== 1))
+                    throw new WebRequestRejected("Unknown or repeated Job query.");
+                value = await dependencies.jobs.read(scope, family, Object.fromEntries(query), now());
             }
             else if (method === "POST") {
                 if (headerValue(request, "origin") !== `http://${headerValue(request, "host")}`) {
                     throw new WebRequestRejected("Job changes require a same-origin request.");
                 }
-                value = dependencies.jobs.mutate(scope, family, await readMutationBody(request), now());
+                value = await dependencies.jobs.mutate(scope, family, await readMutationBody(request), now());
             }
             else
                 throw new WebRequestRejected("Method not allowed.");
@@ -631,7 +632,7 @@ async function handleHttpRequest(request, response, store, dependencies, token,
         try {
             const assetVersion = new URL(request.url, "http://localhost").searchParams.get("v");
             const asset = findWebAsset(pathname, assetVersion);
-            const managementPage = /^\/(?:models(?:\/(?:providers|catalog|quota))?|settings(?:\/(?:preferences|skills|server|connection))?)\/?$/.test(pathname);
+            const managementPage = /^\/(?:models(?:\/(?:providers|catalog|quota))?|settings(?:\/(?:preferences|skills|jobs|server|connection))?)\/?$/.test(pathname);
             if (pathname === "/" || pathname === "/index.html" || managementPage) {
                 sendText(response, 200, "text/html; charset=utf-8", prepareWebDocument(managementPage ? MODELS_HTML.replace("__YUI_WEB_TOKEN__", token) : dashboardHtml(token), managementPage ? "/assets/js/app/manage.js" : "/assets/app.js"), method === "HEAD");
             }

package/dist/web/webTaskSurface.js

@@ -53,6 +53,7 @@ export function createWebTaskSurface(store, options = {}, observations = [], hos
                 core: readTaskContext(tx, taskId, environment),
                 task: {
                     id: task.id, title: clip(task.title), status: task.status, updatedAt: task.updatedAt,
+                    source: task.source,
                     executionGate: task.executionGate, priority: task.priority, tags: task.tags?.slice(0, 16).map(value => clip(value)),
                     projectBindings: task.projectBindings.slice(0, 32),
                     description: clip(task.description), completionSummary: clip(task.completionSummary),

package/docs/authorization.md

@@ -0,0 +1,130 @@
+# Caller identity, discovery and authorization
+
+Yui is a single-user local control plane, not a security boundary against another
+process that can modify the same user's files. A provider thread ID is a location
+hint, not proof that Yui manages that thread. Ordinary unmanaged Agents share the
+existing public-user CLI surface; they do not need an Operator registration,
+Manifest or per-thread Grant. This changes classification, not the user's
+authorization for any external effect.
+
+## Responsibilities and sources
+
+| Question | Authoritative implementation | What it does not establish |
+| --- | --- | --- |
+| Which command templates should this audience see? | `cli/commandCatalog.ts`, projected by `commandDiscovery.ts` into help and completion | Current authentication, target authorization or a Grant |
+| Is this native identity ordinary, current or historical? | `runtime/sessionCaller.ts`, existing RoleSessionSet `sessions` and `history`; `storage/nativeSessionLookup.ts` | A new identity register or cross-Home authentication |
+| May this Session act now? | `runtime/managedCaller.ts`, current Role binding, revocation and captured effective launch | Active Run occupancy is not required for ordinary Leader management |
+| Which Task, Assignment, Project and records may it use? | `task/taskAuthority.ts`, context read authorization and command domain owners | A general “query is safe” rule |
+| Which capability template and exact target are available? | `kernel/builtinCapabilities.ts`, `CapabilityRegistry`, domain `AccessAssessment` | Provider availability or a reusable authorization token |
+| May a Controller operation execute? | `CallAuthority`, `jobControl` and the corresponding service | CLI help is not an access-control layer |
+| May it access an additional resource or irreversible effect? | `CapabilityGrant`, `grant/taskAuthorization.ts`, resource/plugin/release consumers | Task activation does not authorize arbitrary resources |
+
+The full command inventory is generated from the catalog, not maintained as a
+second per-command permissions table: use `yui --json help` and scoped
+`yui --json help task`, or traverse `describeCommandTree(discoveryCommandTree(env))`
+in offline tooling. Complete role hints retain an offline template even without
+a running Home; that is not authentication. Native-ID-only callers are resolved
+from read-only local storage for help/completion; if that read fails the CLI shows
+the restricted `unbound` template. No Controller or provider is started for that
+observation. Execution resolves the original caller again and performs the
+applicable domain checks.
+
+## Caller matrix
+
+| Caller | Default rights | Boundaries / escalation |
+| --- | --- | --- |
+| User terminal; unknown valid `CODEX_THREAD_ID` with no Yui hints | Existing public catalog: public Project/config/Task information, Draft creation, user participation and existing public maintenance entry points | No managed inbox, Job or Grant issuer identity; no automatic discussion/development. Only perform effects the user actually requested |
+| Current Operator (including native-ID-only Desktop) | Existing global management and Task supervision; explicit Grant issuance/revocation | Current native binding and operation-specific resource/effect checks |
+| Custom GlobalRole | Its visible read/self-context and configured scoped operations | Not an Operator merely because global; Home mutations and Task-management rights are not inherited from Operator |
+| Task Leader | Own Task management and readable context; delivery work within captured writable Projects | Planning Sessions do not gain delivery authority from Task activation. New resource/effect authority uses an original user/Operator source or InputRequest |
+| Worker / Reviewer, including native-ID-only | Current Assignment's selected context, workspace and operations | Frozen references, Assignment/Review identity and Project bounds; ask Leader via the existing Assignment Message for missing authority |
+| Partial, conflicting or unknown **Yui** identity; historical/replaced/stopped Session | No public fallback | Use original Home and current Session; preserve original input and receipts. Explicitly scoped historical self-diagnostics remain available through their existing entry |
+| Revoked Session | No revived mutation/inbox authority | Command-time revocation checks remain authoritative even if an offline template is visible |
+
+Public is not synonymous with read-only: terminal users already have maintenance
+and participation commands. This change intentionally gives ordinary Agents that
+same product surface, not all internal commands. Conversely, a read may expose
+private Assignment context, consume a resource Grant or acquire a provider:
+never derive permission from command spelling or the `query` effect alone.
+
+Draft creation copies the configured Leader Agent, model, permissions and profile
+through the existing role-copy path. It saves facts without creating a Run,
+Session or execution workspace. `discuss` and `develop` remain separate explicit
+submission/activation paths.
+
+## Discovery's three states
+
+| Observation | Meaning | Execution behavior |
+| --- | --- | --- |
+| `hidden` | Caller cannot discover/apply for that capability/target | Omitted/unavailable; cannot be enabled by typing a hidden help command |
+| `requestable` | Existing request route can supply the missing exact authority | Includes action, Task, parameter bounds and `leader-message`, `leader-input` or `operator` route; call is denied until authority exists |
+| `authorized` | Current caller and exact parameters satisfy the assessed boundary | Call rechecks current state; revocation, expiry, consumed uses or provider failure can still prevent execution |
+| No `access` field | Template or domain without an exact assessment | Not a fourth persisted state and not a claim of authorization; supply target input where supported and obey domain checks |
+
+Capability search/commands/panels reuse the same registry and assessments.
+Describe with exact input is an observation only: it does not acquire a provider
+or consume a Grant. Hidden/denied, invalid input and provider unavailability remain
+distinct. Static help/completion cannot promise any of these exact target states.
+
+## Grant and delegation matrix
+
+| Capability / effect | Default or reusable authority | Required exact checks |
+| --- | --- | --- |
+| Public information | Existing public command path, no Grant | Local Home/storage contract and domain visibility |
+| Task / Assignment reads and management | Current matching Role; permission categories such as `task:read`, `task:manage` are reused | Task/Assignment/Review identity, record readability, lifecycle, planning/delivery |
+| Job operations | Current managed caller, no repeated per-command approval inside authorized work | Controller reauthentication, owner, workspace, project, head and Assignment |
+| Local resource read/write | Existing resource registration plus exact Grant when required | Task, canonical resource path/id, read vs write, parameter bounds, expiry/use count |
+| Plugin management vs execution | Authorized management is separate from executing author code | Adopted environment, plugin/package digest, phase and exact `plugin.execute` Grant |
+| Release / other high-impact effects | Explicit user authority; existing Operator or source-authorized delivery-Leader Grant | Project/repository/commit, action, package/version/registry where applicable, irreversible ceiling and original operation receipts |
+
+Operator issuance uses its current managed Session. Delivery-Leader issuance must
+cite an original user/Operator Message and exact quoted purpose, stays inside the
+Task and selected Projects, requires finite uses/expiry and action-specific bounds.
+A Role report is not user authority. Worker/Reviewer requests go to Leader; a
+genuinely missing user decision uses InputRequest. A response is not itself a
+Grant. Consumption, revocation and idempotent retries remain with existing
+consumers; discovery does not replenish uses or turn unknown effects into retries.
+No extra approval is added for already-authorized normal role work.
+
+## Identity limits and recovery
+
+The canonical lookup includes both active and historical registrations, including
+inactive Agents in a Session set. The active runtime inventory remains optimized
+for scheduling; it is deliberately not used to prove absence of managed history.
+Unbinding moves a stopped Session into the existing history rather than deleting
+its identity. Role removal retains stopped Session sets while deleting the Role
+and active runtime projection; those records do not grant authority without a
+current Role binding. History erased by an earlier version cannot be reconstructed.
+Storage 1.13 → 1.14 removes only the global Session table's Role foreign key so
+that its existing identity evidence may outlive Role removal; payload bytes are
+preserved. Existing Homes require an explicit supported upgrade, never an
+implicit read-time migration. There is no new authorization state, global thread
+registry or cross-Home scan.
+
+An unknown provider ID in Home B contains no evidence that it was managed in Home
+A. Treating every such ID as invalid would again reject ordinary Agent sessions.
+Therefore retain the intended Home/Manifest/Yui hints for managed work; with those
+hints, a missing registration fails closed. Do not clear hints, forge a Role,
+borrow a parent's transport identity or change Home to obtain public authority.
+Ambiguous registration also fails closed. Native-ID-only help on broken storage
+remains a limited template, while execution reports the original storage/identity
+failure. Complete launch hints can still show a role's static help on a broken
+Home; they cannot authorize reads or effects.
+
+## Verification and maintenance
+
+`cli-authority.test.js` exercises isolated launcher-backed public reads, Draft
+creation/config inheritance, native-only managed callers, historical denial,
+maintenance and cross-Task fences. `agent-inbox.test.js` covers current/historical
+and ambiguous native lookup plus Assignment/Reviewer/revocation boundaries.
+`caller-discovery.test.js` covers projection and transient three-state behavior;
+`leader-authorization.test.js` covers real registry/resource/Grant issuance,
+consumption, revocation and surfaces. Controller Job checks are tested independently
+of CLI discovery. Run the required `npm test` gate; no real model or production
+Home is needed for these contracts.
+
+When adding a command, extend the catalog for presentation and the actual domain
+owner for authorization; do not invent a second CLI allowlist. When adding a
+capability, reuse the registry permission category and its resource owner's
+assessment/consumption checks. Extend a category only when the new operation
+really has the same data and effect boundary.