@undefineds.co/linx 0.2.14 → 0.2.16

package/dist/lib/watch/pod-approval.js

@@ -2,11 +2,18 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { getDefaultPodDataSession } from '../pod-data-session.js';
 import { AS, ODRL, UDFS } from '@undefineds.co/models/namespaces';
 import { ApprovalVocab, AuditVocab, GrantVocab, InboxNotificationVocab } from '@undefineds.co/models/vocab/sidecar';
+import { resolveWatchGrantCoverage } from './secretary.js';
 import { buildApprovalDocumentUrl, RDF_TYPE, buildApprovalResourceUrl, buildAuditDocumentUrl, buildAuditResourceUrl, buildGrantResourceUrl, buildInboxResourceUrl, firstIri, firstLiteral, iri, listTurtleResources, listTurtleResourcesRecursive, literal, parseManagedTurtleBlocks, readTurtleResource, subjectIdFromResourceUrl, upsertManagedTurtleBlock, } from '../pi-adapter/pod-native.js';
-const WATCH_CHAT_ID = 'linx-watch';
+const WATCH_CHAT_ID_PREFIX = 'linx-watch';
 const WATCH_AGENT_ID = 'linx-watch-assistant';
 const REMOTE_APPROVAL_POLICY_VERSION = 'linx-watch-remote-approval/v1';
 const DEFAULT_REMOTE_APPROVAL_POLL_MS = 1000;
+const DEFAULT_WARN_ONLY_TIMEOUT_MS = 5000;
+const DEFAULT_APPROVAL_LIST_DAYS = 7;
+const MAX_GRANT_POLICY_LENGTH = 1200;
+const MAX_APPROVAL_CONTEXT_LENGTH = 1400;
+const MIN_GRANT_COVERAGE_CONFIDENCE = 0.75;
+const MAX_GRANT_COVERAGE_CANDIDATES = 5;
 const remoteApprovalClientCache = new WeakMap();
 function createAbortError() {
     const error = new Error('The operation was aborted.');
@@ -38,8 +45,11 @@ function getPodBaseUrl(webIdOrUri) {
     }
     return webIdOrUri.replace(/\/$/, '');
 }
-function buildThreadUri(webId, threadId) {
-    return `${getPodBaseUrl(webId)}/.data/chat/${WATCH_CHAT_ID}/index.ttl#${threadId}`;
+function buildWatchChatId(record) {
+    return `${WATCH_CHAT_ID_PREFIX}-${record.backend}`;
+}
+function buildThreadUri(webId, record) {
+    return `${getPodBaseUrl(webId)}/.data/chat/${buildWatchChatId(record)}/index.ttl#${record.id}`;
 }
 function buildApprovalUri(webIdOrUri, approvalId) {
     return buildApprovalResourceUrl(webIdOrUri, approvalId);
@@ -47,11 +57,14 @@ function buildApprovalUri(webIdOrUri, approvalId) {
 function buildApprovalUriForDate(webIdOrUri, approvalId, createdAt) {
     return buildApprovalResourceUrl(webIdOrUri, approvalId, createdAt);
 }
+function documentUrlFromResourceUri(resourceUri) {
+    return resourceUri.split('#', 1)[0] ?? resourceUri;
+}
 function buildGrantUri(webIdOrUri, grantId) {
     return buildGrantResourceUrl(webIdOrUri, grantId);
 }
-function buildGrantDocumentUrl(webIdOrUri) {
-    return `${getPodBaseUrl(webIdOrUri)}/settings/autonomy/grants.ttl`;
+function buildGrantSchemaUri(webIdOrUri) {
+    return `${getPodBaseUrl(webIdOrUri)}/settings/autonomy/schema/grant.ttl#GrantWikiPage`;
 }
 function buildAgentUri(webId) {
     return `${getPodBaseUrl(webId)}/.data/agents/${WATCH_AGENT_ID}.ttl`;
@@ -150,7 +163,12 @@ function parseDecisionReason(value) {
 }
 async function warnOnly(runtime, task) {
     try {
-        await task();
+        await Promise.race([
+            task(),
+            runtime.sleep(DEFAULT_WARN_ONLY_TIMEOUT_MS).then(() => {
+                throw new Error(`Pod side-effect sync timed out after ${DEFAULT_WARN_ONLY_TIMEOUT_MS}ms`);
+            }),
+        ]);
     }
     catch (error) {
         if (runtime.onWarning) {
@@ -169,6 +187,168 @@ function safeJsonStringify(value) {
         return JSON.stringify({ error: 'unserializable_context' });
     }
 }
+function truncatePodLiteral(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxLength - 15))}...[truncated]`;
+}
+function safeCompactJson(value, maxLength) {
+    return truncatePodLiteral(safeJsonStringify(value), maxLength);
+}
+function compactApprovalContext(request) {
+    return safeCompactJson({
+        kind: request.kind,
+        message: request.message,
+        toolName: request.toolName,
+        action: request.action,
+        risk: request.risk,
+        ...(request.command ? { command: request.command } : {}),
+        ...(request.cwd ? { cwd: request.cwd } : {}),
+        ...(request.approvalOptions ? { approvalOptions: request.approvalOptions } : {}),
+        ...(request.expiresAt ? { expiresAt: normalizeDateLike(request.expiresAt) } : {}),
+        ...(request.context ? { sourceContext: truncatePodLiteral(request.context, 500) } : {}),
+    }, MAX_APPROVAL_CONTEXT_LENGTH);
+}
+function grantWikiTitleFromApproval(row, explicitTitle) {
+    const explicit = normalizeString(explicitTitle);
+    if (explicit) {
+        return truncatePodLiteral(explicit, 160);
+    }
+    return truncatePodLiteral(`${row.toolName} grant wiki for ${extractSessionId(row.session)}`, 160);
+}
+function grantWikiSummaryFromApproval(row, explicitSummary) {
+    const explicit = normalizeString(explicitSummary);
+    if (explicit) {
+        return truncatePodLiteral(explicit, 500);
+    }
+    return truncatePodLiteral(`Authorization wiki page for ${row.toolName}. AI Secretary must read the page body before reusing this grant.`, 500);
+}
+function grantWikiBodyFromApproval(row, explicitBody) {
+    const explicit = normalizeString(explicitBody);
+    if (explicit) {
+        return truncatePodLiteral(explicit, MAX_GRANT_POLICY_LENGTH);
+    }
+    return truncatePodLiteral([
+        '# Grant Semantics',
+        '',
+        'This page follows the LLM Wiki pattern: it is the maintained wiki view AI Secretary reads before reusing an authorization.',
+        '',
+        '## Covers',
+        `- Requests semantically inside target ${row.target}.`,
+        `- Action family ${row.action}.`,
+        `- Risk no higher than ${row.risk}.`,
+        '',
+        '## Does Not Cover',
+        '- Requests that are materially broader than the source approval.',
+        '- Requests that change from read-oriented to write/destructive behavior.',
+        '- Requests that touch credentials, secrets, package installation, new network side effects, or workspace boundaries unless explicitly documented here.',
+        '',
+        '## Source Context',
+        row.context ?? safeJsonStringify({ toolName: row.toolName, action: row.action, risk: row.risk }),
+    ].join('\n'), MAX_GRANT_POLICY_LENGTH);
+}
+function grantIndexTextFromWikiBody(body) {
+    return truncatePodLiteral(body, MAX_GRANT_POLICY_LENGTH);
+}
+function grantWikiTagsFromApproval(row, explicitTags) {
+    const tags = [
+        'autonomy',
+        'grant',
+        row.toolName,
+        row.risk,
+        ...(explicitTags ?? []),
+    ]
+        .map((tag) => tag.trim())
+        .filter(Boolean);
+    return safeJsonStringify([...new Set(tags)]);
+}
+function grantContextFromApproval(row) {
+    return safeCompactJson({
+        sourceApproval: buildApprovalUriForDate(row.session, row.id, new Date(toIsoString(row.createdAt, new Date().toISOString()))),
+        session: row.session,
+        toolCallId: row.toolCallId,
+        toolName: row.toolName,
+        target: row.target,
+        action: row.action,
+        risk: row.risk,
+        approvalContext: row.context,
+    }, MAX_APPROVAL_CONTEXT_LENGTH);
+}
+function literalValues(predicates, predicate) {
+    return (predicates.get(predicate) ?? [])
+        .map((object) => isRecord(object) && object.type === 'literal' && typeof object.value === 'string' ? object.value : '')
+        .filter(Boolean);
+}
+function iriValues(predicates, predicate) {
+    return (predicates.get(predicate) ?? [])
+        .map((object) => isRecord(object) && object.type === 'iri' && typeof object.value === 'string' ? object.value : '')
+        .filter(Boolean);
+}
+function grantSourceHash(row) {
+    return `approval:${row.id}:${row.toolCallId}:${row.risk}`;
+}
+function encodeApprovalOptions(options) {
+    if (!options || options.length === 0) {
+        return undefined;
+    }
+    return safeJsonStringify(options);
+}
+function parseApprovalOptions(value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed)) {
+            return undefined;
+        }
+        const options = parsed
+            .map((option) => {
+            if (!isRecord(option)) {
+                return null;
+            }
+            const optionId = normalizeString(option.optionId);
+            const label = normalizeString(option.label);
+            if (!optionId || !label) {
+                return null;
+            }
+            const kind = normalizeString(option.kind);
+            const description = normalizeString(option.description);
+            return {
+                optionId,
+                label,
+                ...(kind ? { kind } : {}),
+                ...(description ? { description } : {}),
+            };
+        })
+            .filter((option) => option !== null);
+        return options.length > 0 ? options : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeDateLike(value) {
+    if (value instanceof Date) {
+        return Number.isFinite(value.getTime()) ? value.toISOString() : undefined;
+    }
+    if (typeof value !== 'string' || !value.trim()) {
+        return undefined;
+    }
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) ? parsed.toISOString() : undefined;
+}
+function resolveApprovalExpiresAt(request, now) {
+    const explicit = normalizeDateLike(request.expiresAt);
+    if (explicit) {
+        return explicit;
+    }
+    if (typeof request.timeoutMs === 'number' && Number.isFinite(request.timeoutMs) && request.timeoutMs > 0) {
+        return new Date(now.getTime() + request.timeoutMs);
+    }
+    return undefined;
+}
 function extractSessionId(sessionUri) {
     if (sessionUri.includes('#')) {
         return sessionUri.split('#').pop() || sessionUri;
@@ -193,8 +373,10 @@ function normalizeApprovalSummary(row) {
     const createdAt = toIsoString(row.createdAt, new Date(0).toISOString());
     const sessionUri = row.session;
     const decision = decisionFromApprovalRow(row);
+    const approvalOptions = parseApprovalOptions(row.approvalOptions);
     return {
         id: row.id,
+        ...(normalizeString(row.approvalUri) ? { approvalUri: normalizeString(row.approvalUri) } : {}),
         sessionId: extractSessionId(sessionUri),
         sessionUri,
         toolCallId: row.toolCallId,
@@ -205,7 +387,9 @@ function normalizeApprovalSummary(row) {
         ...(normalizeString(row.assignedTo) ? { assignedTo: normalizeString(row.assignedTo) } : {}),
         ...(normalizeString(row.decisionBy) ? { decisionBy: normalizeString(row.decisionBy) } : {}),
         ...(decision ? { decision } : {}),
+        ...(approvalOptions ? { approvalOptions } : {}),
         createdAt,
+        ...(row.expiresAt ? { expiresAt: toIsoString(row.expiresAt, createdAt) } : {}),
         ...(row.resolvedAt ? { resolvedAt: toIsoString(row.resolvedAt, createdAt) } : {}),
     };
 }
@@ -251,6 +435,7 @@ async function createDefaultRuntime() {
         now() {
             return new Date();
         },
+        resolveGrantCoverage: resolveWatchGrantCoverage,
     };
 }
 async function withRemoteApprovalStore(runtime, fn) {
@@ -295,6 +480,7 @@ async function createRemoteApprovalClient(runtime) {
 function createNativeRemoteApprovalStore(webId, fetcher) {
     return {
         listApprovals: () => listApprovalRows(webId, fetcher),
+        findApproval: (id, options) => findApprovalRow(webId, fetcher, id, options),
         insertApproval: (row) => writeApprovalRow(webId, fetcher, row),
         async updateApproval(id, patch) {
             const existing = (await listApprovalRows(webId, fetcher)).find((row) => row.id === id);
@@ -310,14 +496,39 @@ function createNativeRemoteApprovalStore(webId, fetcher) {
         insertInboxNotification: (row) => writeInboxNotificationRow(webId, fetcher, row),
     };
 }
+async function findApprovalRow(webId, fetcher, id, options = {}) {
+    if (options.resourceUri) {
+        return readApprovalRowFromResource(fetcher, options.resourceUri);
+    }
+    if (options.createdAt) {
+        const createdAt = new Date(toIsoString(options.createdAt, new Date().toISOString()));
+        return readApprovalRowFromResource(fetcher, buildApprovalResourceUrl(webId, id, createdAt));
+    }
+    return (await listApprovalRows(webId, fetcher)).find((row) => row.id === id) ?? null;
+}
+async function readApprovalRowFromResource(fetcher, resourceUri) {
+    const turtle = await readTurtleResource(fetcher, documentUrlFromResourceUri(resourceUri));
+    if (!turtle) {
+        return null;
+    }
+    for (const [subject, predicates] of parseManagedTurtleBlocks(turtle, documentUrlFromResourceUri(resourceUri))) {
+        if (subject !== resourceUri) {
+            continue;
+        }
+        const row = approvalRowFromPredicates(subject, predicates);
+        if (row) {
+            return row;
+        }
+    }
+    return null;
+}
 async function listApprovalRows(webId, fetcher) {
-    const [currentUrls, legacyUrls] = await Promise.all([
-        listTurtleResourcesRecursive(fetcher, `${getPodBaseUrl(webId)}/.data/approvals/`).catch(() => []),
-        listTurtleResources(fetcher, `${getPodBaseUrl(webId)}/.data/approvals/`).catch(() => []),
-    ]);
-    const urls = [...new Set([...currentUrls, ...legacyUrls])];
+    const urls = [
+        ...recentApprovalDocumentUrls(webId),
+        ...await listTurtleResources(fetcher, `${getPodBaseUrl(webId)}/.data/approvals/`).catch(() => []),
+    ];
     const rows = [];
-    for (const url of urls.filter((entry) => entry.endsWith('.ttl'))) {
+    for (const url of [...new Set(urls)].filter((entry) => entry.endsWith('.ttl'))) {
         const turtle = await readTurtleResource(fetcher, url).catch(() => null);
         if (!turtle)
             continue;
@@ -329,6 +540,15 @@ async function listApprovalRows(webId, fetcher) {
     }
     return rows;
 }
+function recentApprovalDocumentUrls(webId, days = DEFAULT_APPROVAL_LIST_DAYS) {
+    const urls = [];
+    const base = Date.now();
+    for (let offset = 0; offset < days; offset += 1) {
+        const date = new Date(base - offset * 24 * 60 * 60 * 1000);
+        urls.push(buildApprovalDocumentUrl(webId, date));
+    }
+    return urls;
+}
 async function writeApprovalRow(webId, fetcher, row) {
     const createdAt = new Date(toIsoString(row.createdAt, new Date().toISOString()));
     const documentUrl = buildApprovalDocumentUrl(webId, createdAt);
@@ -349,8 +569,11 @@ async function writeApprovalRow(webId, fetcher, row) {
             ...(row.decisionRole ? [{ predicate: ApprovalVocab.decisionRole, object: literal(row.decisionRole) }] : []),
             ...(row.onBehalfOf ? [{ predicate: ApprovalVocab.onBehalfOf, object: iri(row.onBehalfOf) }] : []),
             ...(row.reason ? [{ predicate: ApprovalVocab.reason, object: literal(row.reason) }] : []),
+            ...(row.context ? [{ predicate: ApprovalVocab.context, object: literal(row.context) }] : []),
+            ...(row.approvalOptions ? [{ predicate: ApprovalVocab.approvalOptions, object: literal(row.approvalOptions) }] : []),
             ...(row.policyVersion ? [{ predicate: ApprovalVocab.policyVersion, object: literal(row.policyVersion) }] : []),
             { predicate: ApprovalVocab.createdAt, object: literal(toIsoString(row.createdAt, new Date().toISOString())) },
+            ...(row.expiresAt ? [{ predicate: ApprovalVocab.expiresAt, object: literal(toIsoString(row.expiresAt, new Date().toISOString())) }] : []),
             ...(row.resolvedAt ? [{ predicate: ApprovalVocab.resolvedAt, object: literal(toIsoString(row.resolvedAt, new Date().toISOString())) }] : []),
         ],
     });
@@ -394,7 +617,6 @@ async function writeAuditRow(webId, fetcher, row) {
 }
 async function listGrantRows(webId, fetcher) {
     const urls = [
-        `${getPodBaseUrl(webId)}/settings/autonomy/grants.ttl`,
         ...await listTurtleResources(fetcher, `${getPodBaseUrl(webId)}/settings/autonomy/grants/`).catch(() => []),
     ];
     const rows = [];
@@ -412,8 +634,8 @@ async function listGrantRows(webId, fetcher) {
 }
 async function writeGrantRow(webId, fetcher, row) {
     const id = normalizeString(row.id) ?? crypto.randomUUID();
-    const documentUrl = buildGrantDocumentUrl(webId);
     const subjectUrl = buildGrantResourceUrl(webId, id);
+    const documentUrl = subjectUrl;
     const target = normalizeString(row.target);
     const action = normalizeString(row.action);
     const effect = normalizeString(row.effect);
@@ -429,8 +651,22 @@ async function writeGrantRow(webId, fetcher, row) {
             { predicate: RDF_TYPE, object: iri(UDFS.AutonomyGrant) },
             { predicate: GrantVocab.target, object: iri(target) },
             { predicate: GrantVocab.action, object: iri(action) },
+            ...(normalizeString(row.title) ? [{ predicate: GrantVocab.title, object: literal(truncatePodLiteral(normalizeString(row.title), 160)) }] : []),
+            ...(normalizeString(row.summary) ? [{ predicate: GrantVocab.summary, object: literal(truncatePodLiteral(normalizeString(row.summary), 500)) }] : []),
+            ...(normalizeString(row.body) ? [{ predicate: GrantVocab.body, object: literal(truncatePodLiteral(normalizeString(row.body), MAX_GRANT_POLICY_LENGTH)) }] : []),
+            ...(normalizeString(row.schema) ? [{ predicate: GrantVocab.schema, object: iri(normalizeString(row.schema)) }] : []),
+            ...(normalizeString(row.pageKind) ? [{ predicate: GrantVocab.pageKind, object: literal(normalizeString(row.pageKind)) }] : []),
+            ...(normalizeString(row.wikiStatus) ? [{ predicate: GrantVocab.wikiStatus, object: literal(normalizeString(row.wikiStatus)) }] : []),
+            ...(normalizeString(row.tags) ? [{ predicate: GrantVocab.tags, object: literal(truncatePodLiteral(normalizeString(row.tags), 500)) }] : []),
+            ...(normalizeString(row.source) ? [{ predicate: GrantVocab.source, object: literal(normalizeString(row.source)) }] : []),
+            ...(normalizeString(row.sourceHash) ? [{ predicate: GrantVocab.sourceHash, object: literal(normalizeString(row.sourceHash)) }] : []),
+            ...(row.compiledAt ? [{ predicate: GrantVocab.compiledAt, object: literal(toIsoString(row.compiledAt, new Date().toISOString())) }] : []),
+            ...(row.compiledFrom ?? []).map((value) => ({ predicate: GrantVocab.compiledFrom, object: iri(value) })),
+            ...(row.related ?? []).map((value) => ({ predicate: GrantVocab.related, object: iri(value) })),
             { predicate: GrantVocab.effect, object: literal(effect) },
             ...(normalizeString(row.riskCeiling) ? [{ predicate: GrantVocab.riskCeiling, object: literal(normalizeString(row.riskCeiling)) }] : []),
+            ...(normalizeString(row.policy) ? [{ predicate: GrantVocab.policy, object: literal(truncatePodLiteral(normalizeString(row.policy), MAX_GRANT_POLICY_LENGTH)) }] : []),
+            ...(normalizeString(row.context) ? [{ predicate: GrantVocab.context, object: literal(truncatePodLiteral(normalizeString(row.context), MAX_APPROVAL_CONTEXT_LENGTH)) }] : []),
             { predicate: GrantVocab.decisionBy, object: iri(decisionBy) },
             { predicate: GrantVocab.decisionRole, object: literal(decisionRole) },
             ...(normalizeString(row.onBehalfOf) ? [{ predicate: GrantVocab.onBehalfOf, object: iri(normalizeString(row.onBehalfOf)) }] : []),
@@ -477,8 +713,11 @@ function approvalRowFromPredicates(url, predicates) {
         decisionRole: firstLiteral(predicates, ApprovalVocab.decisionRole),
         onBehalfOf: firstIri(predicates, ApprovalVocab.onBehalfOf),
         reason: firstLiteral(predicates, ApprovalVocab.reason),
+        context: firstLiteral(predicates, ApprovalVocab.context),
+        approvalOptions: firstLiteral(predicates, ApprovalVocab.approvalOptions),
         policyVersion: firstLiteral(predicates, ApprovalVocab.policyVersion),
         createdAt,
+        expiresAt: firstLiteral(predicates, ApprovalVocab.expiresAt),
         resolvedAt: firstLiteral(predicates, ApprovalVocab.resolvedAt),
     };
 }
@@ -519,8 +758,22 @@ function grantRowFromPredicates(url, predicates) {
         id: subjectIdFromResourceUrl(url),
         target,
         action,
+        title: firstLiteral(predicates, GrantVocab.title),
+        summary: firstLiteral(predicates, GrantVocab.summary),
+        body: firstLiteral(predicates, GrantVocab.body),
+        schema: firstIri(predicates, GrantVocab.schema),
+        pageKind: firstLiteral(predicates, GrantVocab.pageKind),
+        wikiStatus: firstLiteral(predicates, GrantVocab.wikiStatus),
+        tags: firstLiteral(predicates, GrantVocab.tags),
+        source: firstLiteral(predicates, GrantVocab.source),
+        sourceHash: firstLiteral(predicates, GrantVocab.sourceHash),
+        compiledAt: firstLiteral(predicates, GrantVocab.compiledAt),
+        compiledFrom: iriValues(predicates, GrantVocab.compiledFrom),
+        related: iriValues(predicates, GrantVocab.related),
         effect,
         riskCeiling: firstLiteral(predicates, GrantVocab.riskCeiling),
+        policy: firstLiteral(predicates, GrantVocab.policy),
+        context: firstLiteral(predicates, GrantVocab.context),
         decisionBy,
         decisionRole,
         onBehalfOf: firstIri(predicates, GrantVocab.onBehalfOf),
@@ -528,11 +781,88 @@ function grantRowFromPredicates(url, predicates) {
         revokedAt: firstLiteral(predicates, GrantVocab.revokedAt),
     };
 }
+function isActiveAllowGrant(grant) {
+    return grant.effect === 'allow' && !grant.revokedAt && !!(normalizeString(grant.body) || normalizeString(grant.policy));
+}
+function isGrantRiskCandidate(grant, requestRisk) {
+    const ceiling = riskScore(typeof grant.riskCeiling === 'string' ? grant.riskCeiling : undefined);
+    return ceiling === 0 || ceiling >= riskScore(requestRisk);
+}
+function rankGrantCandidate(grant, requestContext) {
+    let score = 0;
+    if (grant.target === requestContext.target) {
+        score += 4;
+    }
+    if (grant.action === requestContext.action) {
+        score += 3;
+    }
+    if (grant.schema) {
+        score += 2;
+    }
+    if (grant.pageKind === 'autonomy-grant') {
+        score += 1;
+    }
+    return score;
+}
+function selectSemanticGrantCandidates(grants, requestContext) {
+    const risk = normalizeString(requestContext.risk) ?? 'medium';
+    return grants
+        .filter((grant) => isActiveAllowGrant(grant) && isGrantRiskCandidate(grant, risk))
+        .sort((left, right) => rankGrantCandidate(right, requestContext) - rankGrantCandidate(left, requestContext))
+        .slice(0, MAX_GRANT_COVERAGE_CANDIDATES);
+}
+function acceptsGrantCoverage(decision) {
+    return decision?.covers === true
+        && typeof decision.confidence === 'number'
+        && decision.confidence >= MIN_GRANT_COVERAGE_CONFIDENCE;
+}
+async function resolveSemanticGrantDecision(options) {
+    const candidates = selectSemanticGrantCandidates(options.grants, options.requestContext);
+    if (candidates.length === 0) {
+        return null;
+    }
+    const resolver = options.runtime.resolveGrantCoverage ?? resolveWatchGrantCoverage;
+    for (const grant of candidates) {
+        const coverage = await resolver({
+            record: options.record,
+            request: options.request,
+            requestContext: options.requestContext,
+            grant,
+        }).catch(() => null);
+        if (acceptsGrantCoverage(coverage)) {
+            return 'accept_for_session';
+        }
+    }
+    return null;
+}
+function buildWatchGrantRequestContext(input) {
+    return {
+        session: buildThreadUri(input.webId, input.record),
+        target: buildThreadUri(input.webId, input.record),
+        action: buildActionUri(input.request),
+        risk: buildRisk(input.request),
+        toolName: buildToolName(input.request),
+        cwd: input.record.cwd,
+        backend: input.record.backend,
+        mode: input.record.mode,
+    };
+}
+function buildGenericGrantRequestContext(input) {
+    return {
+        session: input.subject.sessionUri,
+        target: input.subject.targetUri ?? input.subject.sessionUri,
+        action: input.request.action,
+        risk: input.request.risk,
+        toolName: input.request.toolName,
+        cwd: input.request.cwd,
+        kind: input.request.kind,
+    };
+}
 export async function createRemoteWatchApproval(options) {
     const activeRuntime = options.runtime ?? await createDefaultRuntime();
     return createRemoteApproval({
         subject: ({ webId }) => ({
-            sessionUri: buildThreadUri(webId, options.record.id),
+            sessionUri: buildThreadUri(webId, options.record),
             actorUri: buildAgentUri(webId),
             policyVersion: REMOTE_APPROVAL_POLICY_VERSION,
         }),
@@ -545,6 +875,9 @@ export async function createRemoteWatchApproval(options) {
             risk: buildRisk(options.request),
             ...(options.request.kind === 'command-approval' && options.request.command ? { command: options.request.command } : {}),
             ...(options.request.kind === 'command-approval' && options.request.cwd ? { cwd: options.request.cwd } : {}),
+            ...(options.request.approvalOptions ? { approvalOptions: options.request.approvalOptions } : {}),
+            ...(options.request.timeoutMs ? { timeoutMs: options.request.timeoutMs } : {}),
+            ...(options.request.expiresAt ? { expiresAt: options.request.expiresAt } : {}),
             entry: sessionUri,
         }),
         runtime: activeRuntime,
@@ -568,6 +901,9 @@ export async function createRemoteApproval(options) {
         const onBehalfOf = subject.onBehalfOf ?? webId;
         const policyVersion = subject.policyVersion ?? REMOTE_APPROVAL_POLICY_VERSION;
         const requestEntry = request.entry ?? approvalUri;
+        const expiresAt = resolveApprovalExpiresAt(request, now);
+        const approvalOptions = encodeApprovalOptions(request.approvalOptions);
+        const context = compactApprovalContext(request);
         await store.insertApproval({
             id: approvalId,
             session: sessionUri,
@@ -578,8 +914,11 @@ export async function createRemoteApproval(options) {
             risk: request.risk,
             status: 'pending',
             assignedTo,
+            context,
+            ...(approvalOptions ? { approvalOptions } : {}),
             policyVersion,
             createdAt: now,
+            ...(expiresAt ? { expiresAt } : {}),
         });
         const requestAudit = {
             id: crypto.randomUUID(),
@@ -604,6 +943,7 @@ export async function createRemoteApproval(options) {
         }));
         return normalizeApprovalSummary({
             id: approvalId,
+            approvalUri,
             session: sessionUri,
             toolCallId: request.toolCallId,
             toolName: request.toolName,
@@ -612,8 +952,11 @@ export async function createRemoteApproval(options) {
             risk: request.risk,
             status: 'pending',
             assignedTo,
+            context,
+            ...(approvalOptions ? { approvalOptions } : {}),
             policyVersion,
             createdAt: now,
+            ...(expiresAt ? { expiresAt } : {}),
         });
     });
 }
@@ -624,10 +967,13 @@ export async function waitForRemoteWatchApproval(options) {
             if (options.signal?.aborted) {
                 throw createAbortError();
             }
-            const approvals = await store.listApprovals();
-            const row = approvals.find((entry) => entry.id === options.approvalId);
+            const row = await readRemoteApprovalRow(store, {
+                approvalId: options.approvalId,
+                approvalUri: options.approvalUri,
+            });
             if (!row) {
-                throw new Error(`Remote approval disappeared before resolution: ${options.approvalId}`);
+                await activeRuntime.sleep(options.pollMs ?? DEFAULT_REMOTE_APPROVAL_POLL_MS);
+                continue;
             }
             const decision = decisionFromApprovalRow(row);
             if (decision) {
@@ -641,17 +987,20 @@ export async function requestRemoteWatchApproval(options) {
     const activeRuntime = options.runtime ?? await createDefaultRuntime();
     const delegated = await withRemoteApprovalStore(activeRuntime, async ({ store, webId }) => {
         const grants = await store.listGrants();
-        const requestAction = buildActionUri(options.request);
-        const requestTarget = buildThreadUri(webId, options.record.id);
-        const requestRisk = buildRisk(options.request);
-        return grants.some((grant) => (grant.effect === 'allow'
-            && grant.action === requestAction
-            && grant.target === requestTarget
-            && riskScore(typeof grant.riskCeiling === 'string' ? grant.riskCeiling : undefined) >= riskScore(requestRisk)
-            && !grant.revokedAt));
+        return resolveSemanticGrantDecision({
+            runtime: activeRuntime,
+            grants,
+            record: options.record,
+            request: options.request,
+            requestContext: buildWatchGrantRequestContext({
+                webId,
+                record: options.record,
+                request: options.request,
+            }),
+        });
     });
     if (delegated) {
-        return 'accept_for_session';
+        return delegated;
     }
     const summary = await createRemoteWatchApproval({
         record: options.record,
@@ -660,11 +1009,29 @@ export async function requestRemoteWatchApproval(options) {
     });
     return waitForRemoteWatchApproval({
         approvalId: summary.id,
+        approvalUri: summary.approvalUri,
         pollMs: options.pollMs,
         signal: options.signal,
         runtime: activeRuntime,
     });
 }
+export async function resolveExistingRemoteWatchGrant(options) {
+    const activeRuntime = options.runtime ?? await createDefaultRuntime();
+    return withRemoteApprovalStore(activeRuntime, async ({ store, webId }) => {
+        const grants = await store.listGrants();
+        return resolveSemanticGrantDecision({
+            runtime: activeRuntime,
+            grants,
+            record: options.record,
+            request: options.request,
+            requestContext: buildWatchGrantRequestContext({
+                webId,
+                record: options.record,
+                request: options.request,
+            }),
+        });
+    });
+}
 export async function requestRemoteApproval(options) {
     const activeRuntime = options.runtime ?? await createDefaultRuntime();
     const delegated = await withRemoteApprovalStore(activeRuntime, async ({ store, webId, stored }) => {
@@ -675,15 +1042,20 @@ export async function requestRemoteApproval(options) {
             ? options.request({ webId, stored, sessionUri: subject.sessionUri })
             : options.request;
         const grants = await store.listGrants();
-        const requestTarget = subject.targetUri ?? subject.sessionUri;
-        return grants.some((grant) => (grant.effect === 'allow'
-            && grant.action === request.action
-            && grant.target === requestTarget
-            && riskScore(typeof grant.riskCeiling === 'string' ? grant.riskCeiling : undefined) >= riskScore(request.risk)
-            && !grant.revokedAt));
+        const requestContext = buildGenericGrantRequestContext({ subject, request });
+        return resolveSemanticGrantDecision({
+            runtime: activeRuntime,
+            grants,
+            request: {
+                ...request,
+                session: subject.sessionUri,
+                target: requestContext.target,
+            },
+            requestContext,
+        });
     });
     if (delegated) {
-        return 'accept_for_session';
+        return delegated;
     }
     const summary = await createRemoteApproval({
         subject: options.subject,
@@ -692,6 +1064,7 @@ export async function requestRemoteApproval(options) {
     });
     return waitForRemoteWatchApproval({
         approvalId: summary.id,
+        approvalUri: summary.approvalUri,
         pollMs: options.pollMs,
         signal: options.signal,
         runtime: activeRuntime,
@@ -712,8 +1085,10 @@ export async function listRemoteWatchApprovals(options = {}) {
 export async function resolveRemoteWatchApproval(options) {
     const activeRuntime = options.runtime ?? await createDefaultRuntime();
     return withRemoteApprovalStore(activeRuntime, async ({ store, webId }) => {
-        const approvals = await store.listApprovals();
-        const row = approvals.find((entry) => entry.id === options.approvalId);
+        const row = await readRemoteApprovalRow(store, {
+            approvalId: options.approvalId,
+            approvalUri: options.approvalUri,
+        });
         if (!row) {
             throw new Error(`Remote approval not found: ${options.approvalId}`);
         }
@@ -726,10 +1101,11 @@ export async function resolveRemoteWatchApproval(options) {
         const nextStatus = options.decision === 'accept' || options.decision === 'accept_for_session'
             ? 'approved'
             : 'rejected';
+        const decisionRole = options.decisionRole ?? 'human';
         await store.updateApproval(row.id, {
             status: nextStatus,
             decisionBy: webId,
-            decisionRole: 'human',
+            decisionRole,
             onBehalfOf: webId,
             reason: encodeDecisionReason(options.decision, options.note),
             resolvedAt: now,
@@ -738,7 +1114,7 @@ export async function resolveRemoteWatchApproval(options) {
             id: crypto.randomUUID(),
             action: nextStatus === 'approved' ? 'approval_approved' : 'approval_rejected',
             actor: webId,
-            actorRole: 'human',
+            actorRole: decisionRole,
             onBehalfOf: webId,
             session: row.session,
             entry: approvalUri,
@@ -750,14 +1126,29 @@ export async function resolveRemoteWatchApproval(options) {
         }));
         if (options.decision === 'accept_for_session') {
             const grantId = crypto.randomUUID();
+            const body = grantWikiBodyFromApproval(row, options.grantWikiBody);
             await store.insertGrant({
                 id: grantId,
                 target: row.target,
                 action: row.action,
+                title: grantWikiTitleFromApproval(row, options.grantWikiTitle),
+                summary: grantWikiSummaryFromApproval(row, options.grantWikiSummary),
+                body,
+                schema: buildGrantSchemaUri(webId),
+                pageKind: 'autonomy-grant',
+                wikiStatus: 'active',
+                tags: grantWikiTagsFromApproval(row, options.grantWikiTags),
+                source: 'approval',
+                sourceHash: grantSourceHash(row),
+                compiledAt: now,
+                compiledFrom: [approvalUri],
+                related: [row.session],
                 effect: 'allow',
                 riskCeiling: row.risk,
+                policy: grantIndexTextFromWikiBody(body),
+                context: grantContextFromApproval(row),
                 decisionBy: webId,
-                decisionRole: 'human',
+                decisionRole,
                 onBehalfOf: webId,
                 createdAt: now,
             });
@@ -778,7 +1169,7 @@ export async function resolveRemoteWatchApproval(options) {
             ...row,
             status: nextStatus,
             decisionBy: webId,
-            decisionRole: 'human',
+            decisionRole,
             onBehalfOf: webId,
             reason: encodeDecisionReason(options.decision, options.note),
             resolvedAt: now,
@@ -786,6 +1177,18 @@ export async function resolveRemoteWatchApproval(options) {
         return normalizeApprovalSummary(nextRow);
     });
 }
+async function readRemoteApprovalRow(store, options) {
+    if (store.findApproval) {
+        const row = await store.findApproval(options.approvalId, {
+            resourceUri: options.approvalUri,
+        });
+        if (row || options.approvalUri) {
+            return row;
+        }
+    }
+    const approvals = await store.listApprovals();
+    return approvals.find((entry) => entry.id === options.approvalId) ?? null;
+}
 export const __podApprovalInternal = {
     createAbortError,
     createDefaultRuntime,
@@ -797,6 +1200,7 @@ export const __podApprovalInternal = {
     decisionFromApprovalRow,
     encodeDecisionReason,
     formatSummaryHeadline,
+    readRemoteApprovalRow,
     isRemoteApprovalAbortError,
     normalizeApprovalSummary,
     parseDecisionReason,