@agent-native/core 0.203.1 → 0.204.0-nightly-20261008011018

package/dist/audit/actions/export-audit-ocsf.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { auditEventToOcsf, OCSF_SCHEMA_VERSION } from "../ocsf.js";
+import { AuditAccessError, resolveAuditReadScope } from "../read-scope.js";
+import { MAX_LIMIT, queryAuditEventPage } from "../store.js";
+// Audit timestamps are assigned before inserts become visible. The settle delay
+// and replay window keep a delayed insert from falling permanently behind the cursor.
+const SETTLE_MS = 5000;
+const REPLAY_WINDOW_MS = 5 * 60 * 1000;
+const timeInput = z.union([z.number(), z.string()]);
+function badRequest(message) {
+    return Object.assign(new Error(message), { statusCode: 400 });
+}
+function parseTime(value, name) {
+    if (value === undefined)
+        return undefined;
+    const ms = typeof value === "number"
+        ? value
+        : /^\d+$/.test(value.trim())
+            ? Number(value)
+            : Date.parse(value);
+    if (!Number.isFinite(ms)) {
+        throw badRequest(`${name} must be an ISO 8601 timestamp or epoch ms.`);
+    }
+    return ms;
+}
+function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor)).toString("base64url");
+}
+function decodeCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (parsed && typeof parsed === "object") {
+            const value = parsed;
+            const latestSettledMs = Date.now() - SETTLE_MS;
+            if (value.version === 3 &&
+                (value.mode === "ready" || value.mode === "paging") &&
+                typeof value.orgId === "string" &&
+                value.orgId.length > 0 &&
+                Number.isFinite(value.watermarkMs) &&
+                Number(value.watermarkMs) <= latestSettledMs &&
+                (value.sinceMs === undefined || Number.isFinite(value.sinceMs)) &&
+                (value.untilMs === undefined || Number.isFinite(value.untilMs))) {
+                const bounds = {
+                    orgId: value.orgId,
+                    ...(typeof value.sinceMs === "number"
+                        ? { sinceMs: value.sinceMs }
+                        : {}),
+                    ...(typeof value.untilMs === "number"
+                        ? { untilMs: value.untilMs }
+                        : {}),
+                };
+                if (value.mode === "ready") {
+                    return {
+                        version: 3,
+                        mode: "ready",
+                        watermarkMs: value.watermarkMs,
+                        ...bounds,
+                    };
+                }
+                const after = value.after;
+                if (Number.isFinite(value.beforeMs) &&
+                    Number(value.beforeMs) <= latestSettledMs &&
+                    after !== null &&
+                    typeof after === "object" &&
+                    Number.isFinite(after.createdAt) &&
+                    typeof after.id === "string" &&
+                    after.id) {
+                    return {
+                        version: 3,
+                        mode: "paging",
+                        after: { createdAt: after.createdAt, id: after.id },
+                        beforeMs: value.beforeMs,
+                        watermarkMs: value.watermarkMs,
+                        ...bounds,
+                    };
+                }
+            }
+        }
+        // coercion-ok: malformed cursors fall through to the typed 400 below.
+    }
+    catch {
+        // Falls through to the 400 below.
+    }
+    throw badRequest("cursor is not a cursor returned by this action.");
+}
+function assertCursorBounds(cursor, bounds) {
+    if (cursor.orgId !== bounds.orgId ||
+        (bounds.sinceMs !== undefined && bounds.sinceMs !== cursor.sinceMs) ||
+        (bounds.untilMs !== undefined && bounds.untilMs !== cursor.untilMs)) {
+        throw badRequest("The organization, since, and until values must match the values used with this cursor.");
+    }
+}
+export default defineAction({
+    description: `Export the organization's audit trail as OCSF ${OCSF_SCHEMA_VERSION} API Activity events (class 6003) for a SIEM. Owners and admins only; returns the organization's shared trail (org and admins events), oldest first. Pull incrementally: pass the previous nextCursor as cursor and store every returned nextCursor, including when events is empty; empty pages advance the ready watermark. Cursors are bound to the organization that issued them; restart the export after switching organizations. A five-minute rolling overlap can replay recent events to catch late commits; deduplicate across polls by metadata.uid. Use list-audit-events instead to browse or answer 'what changed'.`,
+    schema: z.object({
+        since: timeInput
+            .optional()
+            .describe("Only events at or after this ISO 8601 timestamp or epoch ms."),
+        until: timeInput
+            .optional()
+            .describe("Only events before this ISO 8601 timestamp or epoch ms."),
+        cursor: z
+            .string()
+            .optional()
+            .describe("The nextCursor from the previous response; store every returned nextCursor, including for empty pages."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_LIMIT)
+            .optional()
+            .describe("Max events per page (default 100, max 500)."),
+    }),
+    http: { method: "GET" },
+    audit: {
+        onRead: true,
+        summary: () => "Exported audit events as OCSF",
+    },
+    run: async (args, ctx) => {
+        const scope = await resolveAuditReadScope(ctx, "organization");
+        if (!scope.orgId) {
+            throw new AuditAccessError("Select an organization to export the organization audit log.");
+        }
+        const requestedSinceMs = parseTime(args.since, "since");
+        const requestedUntilMs = parseTime(args.until, "until");
+        const cursor = args.cursor ? decodeCursor(args.cursor) : undefined;
+        if (cursor) {
+            assertCursorBounds(cursor, {
+                orgId: scope.orgId,
+                sinceMs: requestedSinceMs,
+                untilMs: requestedUntilMs,
+            });
+        }
+        const sinceMs = cursor?.sinceMs ?? requestedSinceMs;
+        const untilMs = cursor?.untilMs ?? requestedUntilMs;
+        const now = Date.now();
+        const beforeMs = cursor?.mode === "paging"
+            ? cursor.beforeMs
+            : Math.min(untilMs ?? Infinity, now - SETTLE_MS);
+        const after = cursor?.mode === "paging"
+            ? cursor.after
+            : cursor
+                ? {
+                    createdAt: Math.max(0, cursor.watermarkMs - REPLAY_WINDOW_MS),
+                    id: "",
+                }
+                : undefined;
+        const watermarkMs = cursor?.watermarkMs ?? 0;
+        const page = await queryAuditEventPage(scope, {
+            order: "asc",
+            limit: args.limit,
+            ...(sinceMs !== undefined ? { sinceMs } : {}),
+            beforeMs,
+            ...(after ? { after } : {}),
+        });
+        const last = page.events[page.events.length - 1];
+        const nextCursor = page.hasMore && last
+            ? encodeCursor({
+                version: 3,
+                mode: "paging",
+                orgId: scope.orgId,
+                after: { createdAt: last.createdAt, id: last.id },
+                beforeMs,
+                watermarkMs,
+                ...(sinceMs !== undefined ? { sinceMs } : {}),
+                ...(untilMs !== undefined ? { untilMs } : {}),
+            })
+            : encodeCursor({
+                version: 3,
+                mode: "ready",
+                orgId: scope.orgId,
+                watermarkMs: Math.max(watermarkMs, beforeMs),
+                ...(sinceMs !== undefined ? { sinceMs } : {}),
+                ...(untilMs !== undefined ? { untilMs } : {}),
+            });
+        return {
+            events: page.events.map(auditEventToOcsf),
+            hasMore: page.hasMore,
+            nextCursor,
+        };
+    },
+});

package/dist/audit/actions/list-audit-events.d.ts

@@ -2,7 +2,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     scope?: "accessible" | "organization";
     targetType?: string;
     targetId?: string;
-    actorKind?: "agent" | "human" | "system";
+    actorKind?: "agent" | "human" | "service" | "system";
     actorEmail?: string;
     status?: "denied" | "error" | "success";
     threadId?: string;

package/dist/audit/actions/list-audit-events.js

@@ -3,7 +3,7 @@ import { defineAction } from "../../action.js";
 import { resolveAuditReadScope } from "../read-scope.js";
 import { queryAuditApps, queryAuditEventPage } from "../store.js";
 export default defineAction({
-    description: "List audit-log events (who changed what, when, and whether it was you or the agent) for resources you can access. Supports filtering by target resource, actor (agent vs human), status, agent thread/turn, app, and time range, with offset paging. Use this to answer 'what did the agent change', 'who edited this record', or 'show recent changes'. Organization owners and admins pass scope 'organization' to read the organization's settings and admin trail (default model, member roles, Builder.io, and other org settings changes, including refused attempts), which is the Settings audit log.",
+    description: "List audit-log events (who changed what, when, and whether it was a human, agent, service principal, or system) for resources you can access. Supports filtering by target resource, actor, status, agent thread/turn, app, and time range, with offset paging. Use this to answer 'what did the agent change', 'who edited this record', or 'show recent changes'. Organization owners and admins pass scope 'organization' to read the organization's settings and admin trail (default model, member roles, Builder.io, and other org settings changes, including refused attempts), which is the Settings audit log.",
     schema: z.object({
         scope: z
             .enum(["accessible", "organization"])
@@ -18,9 +18,9 @@ export default defineAction({
             .optional()
             .describe("Filter to one resource id (pair with targetType)."),
         actorKind: z
-            .enum(["agent", "human", "system"])
+            .enum(["agent", "human", "service", "system"])
             .optional()
-            .describe("Filter to changes made by the agent, a human, or the system."),
+            .describe("Filter to changes made by an agent, human, service principal, or the system."),
         actorEmail: z.string().optional().describe("Filter to one actor's email."),
         status: z
             .enum(["success", "error", "denied"])

package/dist/audit/config.d.ts

@@ -2,6 +2,6 @@ import type { ActionAuditConfig, AuditActorKind, AuditStatus } from "./types.js"
 export declare function normalizeAuditConfig(raw: unknown): ActionAuditConfig | undefined;
 export declare function resolveAuditAttach(config: ActionAuditConfig | undefined, readOnly: boolean | undefined): boolean;
 export declare function shouldRecordAudit(config: ActionAuditConfig | undefined, actionName: string): boolean;
-export declare function deriveActorKind(caller: string | undefined, actorEmail: string | undefined | null): AuditActorKind;
+export declare function deriveActorKind(caller: string | undefined, actorEmail: string | undefined | null, orgId?: string | null): AuditActorKind;
 export declare function isAuditDisabled(): boolean;
 export type { AuditStatus };

package/dist/audit/config.js

@@ -1,3 +1,4 @@
+import { parseServiceIdentityEmail } from "../org/service-identity.js";
 const DEFAULT_SKIP_ACTIONS = new Set([
     "context-pin",
     "context-evict",
@@ -28,7 +29,10 @@ export function shouldRecordAudit(config, actionName) {
         return false;
     return true;
 }
-export function deriveActorKind(caller, actorEmail) {
+export function deriveActorKind(caller, actorEmail, orgId) {
+    const serviceIdentity = parseServiceIdentityEmail(actorEmail);
+    if (serviceIdentity && serviceIdentity.orgId === orgId)
+        return "service";
     if (caller === "tool")
         return "agent";
     return actorEmail ? "human" : "system";

package/dist/audit/index.d.ts

@@ -4,5 +4,6 @@ export { redactArgsToJson } from "./redact.js";
 export { ensureAuditTables, insertAuditEvent, queryAuditEvents, queryAuditEventPage, queryAuditApps, getAuditEventById, deleteOldAuditEvents, type AuditEventPage, type AuditReadScope, type AuditTrail, } from "./store.js";
 export { AuditAccessError, resolveAuditReadScope } from "./read-scope.js";
 export { orgAdminAudit, orgAdminAuditTarget, recordOrgAdminAuditEvent, type OrgAdminAuditEventInput, } from "./org-admin.js";
+export { auditEventToOcsf, OCSF_SCHEMA_VERSION, type OcsfApiActivity, } from "./ocsf.js";
 export { recordActionAudit } from "./record.js";
 export { runAuditCleanupOnce, startAuditCleanupJob, stopAuditCleanupJob, } from "./cleanup-job.js";

package/dist/audit/index.js

@@ -3,5 +3,6 @@ export { redactArgsToJson } from "./redact.js";
 export { ensureAuditTables, insertAuditEvent, queryAuditEvents, queryAuditEventPage, queryAuditApps, getAuditEventById, deleteOldAuditEvents, } from "./store.js";
 export { AuditAccessError, resolveAuditReadScope } from "./read-scope.js";
 export { orgAdminAudit, orgAdminAuditTarget, recordOrgAdminAuditEvent, } from "./org-admin.js";
+export { auditEventToOcsf, OCSF_SCHEMA_VERSION, } from "./ocsf.js";
 export { recordActionAudit } from "./record.js";
 export { runAuditCleanupOnce, startAuditCleanupJob, stopAuditCleanupJob, } from "./cleanup-job.js";

package/dist/audit/ocsf.d.ts

@@ -0,0 +1,70 @@
+import type { AuditEvent } from "./types.js";
+export declare const OCSF_SCHEMA_VERSION = "1.9.0";
+/** OCSF `activity_id`: 1 Create, 2 Read, 3 Update, 4 Delete, 99 Other. */
+type OcsfActivityId = 1 | 2 | 3 | 4 | 99;
+export interface OcsfApiActivity {
+    class_uid: 6003;
+    class_name: "API Activity";
+    category_uid: 6;
+    category_name: "Application Activity";
+    activity_id: OcsfActivityId;
+    activity_name: string;
+    type_uid: number;
+    type_name: string;
+    /** Epoch milliseconds. */
+    time: number;
+    severity_id: 1 | 2 | 3;
+    severity: "Informational" | "Low" | "Medium";
+    status_id: 1 | 2;
+    status: "Success" | "Failure";
+    status_code?: string;
+    status_detail?: string;
+    /** 1 Allowed, 2 Denied. */
+    action_id: 1 | 2;
+    action: "Allowed" | "Denied";
+    message: string;
+    metadata: {
+        version: string;
+        uid: string;
+        log_name: string;
+        tenant_uid?: string;
+        product: {
+            name: string;
+            vendor_name: string;
+            uid?: string;
+        };
+    };
+    actor: {
+        user: {
+            uid?: string;
+            name: string;
+            email_addr?: string;
+            /** 1 User, 3 System, 4 Service. */
+            type_id: 1 | 3 | 4;
+            type: "User" | "System" | "Service";
+        };
+        session?: {
+            uid: string;
+        };
+    };
+    api: {
+        operation: string;
+        service?: {
+            name: string;
+        };
+    };
+    src_endpoint: {
+        name: string;
+        uid?: string;
+    };
+    resources?: Array<{
+        type?: string;
+        uid?: string;
+        owner?: {
+            email_addr: string;
+        };
+    }>;
+    unmapped: Record<string, string>;
+}
+export declare function auditEventToOcsf(event: AuditEvent): OcsfApiActivity;
+export {};

package/dist/audit/ocsf.js

@@ -0,0 +1,228 @@
+/**
+ * Map an audit event to an OCSF API Activity event (class 6003, category 6
+ * Application Activity) so a SIEM can ingest the trail.
+ *
+ * Pure: no I/O, no clock. Field names and enum values follow OCSF
+ * {@link OCSF_SCHEMA_VERSION}. Anything OCSF has no field for (run, task,
+ * thread, turn, app, lineage) goes under `unmapped` instead of an invented
+ * field. The redacted `input` payload is never exported.
+ */
+import { parseServiceIdentityEmail } from "../org/service-identity.js";
+import { redactTextToSummary } from "./redact.js";
+export const OCSF_SCHEMA_VERSION = "1.9.0";
+const CLASS_UID = 6003;
+const CATEGORY_UID = 6;
+const ACTIVITY_NAMES = {
+    1: "Create",
+    2: "Read",
+    3: "Update",
+    4: "Delete",
+    99: "Other",
+};
+// Action names are verb-first kebab-case (`delete-recording`). A verb we do
+// not recognise is `Other`, never a guess.
+const ACTIVITY_VERBS = [
+    [1, /^(create|add|new|invite|upload|import|register|mint|connect)(-|$)/],
+    [2, /^(get|list|read|search|view|export|query|find|fetch)(-|$)/],
+    [4, /^(delete|remove|revoke|archive|disconnect|retire|purge)(-|$)/],
+    [
+        3,
+        /^(update|set|change|edit|rename|move|save|enable|disable|suspend|resume|toggle)(-|$)/,
+    ],
+];
+function activityId(action) {
+    const name = action.toLowerCase();
+    return ACTIVITY_VERBS.find(([, verb]) => verb.test(name))?.[0] ?? 99;
+}
+// A refused attempt is the signal a SIEM alerts on, so it ranks above an
+// internal error; both outrank a normal success.
+const SEVERITY = {
+    success: 1,
+    error: 2,
+    denied: 3,
+};
+function sanitizeLineageUrl(value) {
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value.trim());
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            return undefined;
+        }
+        if (/%(?:2f|5c)/i.test(url.pathname))
+            return undefined;
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        let redactNextPathSegment = false;
+        const safePath = url.pathname
+            .split("/")
+            .map((segment) => {
+            if (redactNextPathSegment) {
+                redactNextPathSegment = false;
+                return "redacted";
+            }
+            let decoded = segment;
+            try {
+                decoded = decodeURIComponent(segment);
+            }
+            catch {
+                return "redacted";
+            }
+            const pathKey = decoded.toLowerCase().replace(/[-_]/g, "");
+            if (/^(?:apikey|accesstoken|refreshtoken|token|secret|password|credential|signature|sig|authorization|auth|session)$/.test(pathKey)) {
+                redactNextPathSegment = true;
+                return segment;
+            }
+            const redacted = redactTextToSummary(decoded);
+            if (!redacted || redacted === decoded)
+                return segment;
+            return encodeURIComponent(redacted === "[redacted]" ? "redacted" : redacted);
+        })
+            .join("/");
+        const safeUrl = `${url.origin}${safePath === "/" ? "" : safePath}`;
+        return redactTextToSummary(safeUrl) ?? undefined;
+        // coercion-ok: malformed lineage URLs are omitted from the SIEM export.
+    }
+    catch {
+        return undefined;
+    }
+}
+function sanitizeNetworkPeer(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    const url = sanitizeLineageUrl(trimmed);
+    if (url)
+        return url;
+    if (/^(?:[a-z][a-z\d+.-]*:)?\/\//i.test(trimmed))
+        return undefined;
+    return redactTextToSummary(trimmed) ?? undefined;
+}
+function actorFor(event) {
+    const email = event.actorEmail;
+    const service = parseServiceIdentityEmail(email);
+    // A human can register a `@service.<orgId>` address, so the email alone is
+    // not proof of a service principal: it must name this event's org.
+    const session = event.threadId ? { session: { uid: event.threadId } } : {};
+    if (service && email && event.orgId && service.orgId === event.orgId) {
+        return {
+            user: {
+                uid: email,
+                name: `svc-${service.serviceName}`,
+                type_id: 4,
+                type: "Service",
+            },
+            ...session,
+        };
+    }
+    if (email) {
+        return {
+            user: {
+                uid: email,
+                name: email,
+                email_addr: email,
+                type_id: 1,
+                type: "User",
+            },
+            ...session,
+        };
+    }
+    return {
+        user: { name: "system", type_id: 3, type: "System" },
+        ...session,
+    };
+}
+function statusDetail(event) {
+    if (event.status === "denied") {
+        return event.errorCode
+            ? `Refused: ${event.errorCode}`
+            : "Refused: the caller was not permitted to perform this action";
+    }
+    if (event.status === "error") {
+        return event.errorCode ? `Failed: ${event.errorCode}` : "Failed";
+    }
+    return undefined;
+}
+export function auditEventToOcsf(event) {
+    const id = activityId(event.action);
+    const failed = event.status !== "success";
+    const detail = statusDetail(event);
+    const unmapped = {};
+    const keep = (key, value) => {
+        if (value)
+            unmapped[key] = value;
+    };
+    keep("actor_kind", event.actorKind);
+    keep("caller", event.caller);
+    keep("app", event.app);
+    keep("visibility", event.visibility);
+    keep("thread_id", event.threadId);
+    keep("turn_id", event.turnId);
+    keep("run_id", event.runId);
+    keep("task_id", event.taskId);
+    keep("parent_task_id", event.parentTaskId);
+    keep("source_kind", event.sourceKind);
+    keep("source_platform", event.sourcePlatform);
+    keep("source_id", event.sourceId);
+    keep("source_url", sanitizeLineageUrl(event.sourceUrl));
+    keep("network_protocol", event.networkProtocol);
+    keep("network_id", event.networkId);
+    const networkPeer = sanitizeNetworkPeer(event.networkPeer);
+    keep("network_peer", networkPeer);
+    const resource = event.targetType || event.targetId
+        ? [
+            {
+                ...(event.targetType ? { type: event.targetType } : {}),
+                ...(event.targetId ? { uid: event.targetId } : {}),
+                ...(event.ownerEmail
+                    ? { owner: { email_addr: event.ownerEmail } }
+                    : {}),
+            },
+        ]
+        : undefined;
+    return {
+        class_uid: CLASS_UID,
+        class_name: "API Activity",
+        category_uid: CATEGORY_UID,
+        category_name: "Application Activity",
+        activity_id: id,
+        activity_name: ACTIVITY_NAMES[id],
+        type_uid: CLASS_UID * 100 + id,
+        type_name: `API Activity: ${ACTIVITY_NAMES[id]}`,
+        time: event.createdAt,
+        severity_id: SEVERITY[event.status],
+        severity: ["Informational", "Low", "Medium"][SEVERITY[event.status] - 1],
+        status_id: failed ? 2 : 1,
+        status: failed ? "Failure" : "Success",
+        ...(event.errorCode ? { status_code: event.errorCode } : {}),
+        ...(detail ? { status_detail: detail } : {}),
+        action_id: event.status === "denied" ? 2 : 1,
+        action: event.status === "denied" ? "Denied" : "Allowed",
+        message: redactTextToSummary(event.summary ?? "") ||
+            `${event.action} (${event.status})`,
+        metadata: {
+            version: OCSF_SCHEMA_VERSION,
+            uid: event.id,
+            log_name: "agent_audit_log",
+            ...(event.orgId ? { tenant_uid: event.orgId } : {}),
+            product: {
+                name: "Agent-Native",
+                vendor_name: "Builder.io",
+                ...(event.app ? { uid: event.app } : {}),
+            },
+        },
+        actor: actorFor(event),
+        api: {
+            operation: event.action,
+            ...(event.app ? { service: { name: event.app } } : {}),
+        },
+        src_endpoint: {
+            name: networkPeer || event.caller,
+            ...(event.networkId ? { uid: event.networkId } : {}),
+        },
+        ...(resource ? { resources: resource } : {}),
+        unmapped,
+    };
+}

package/dist/audit/record.js

@@ -117,7 +117,7 @@ export async function recordActionAudit(input) {
             createdAt: Date.now(),
             action: actionName,
             caller,
-            actorKind: deriveActorKind(caller, actorEmail),
+            actorKind: deriveActorKind(caller, actorEmail, ctx?.orgId),
             actorEmail,
             orgId: ctx?.orgId ?? null,
             threadId: ctx?.threadId ?? null,

package/dist/audit/store.js

@@ -191,7 +191,9 @@ export const MAX_LIMIT = 500;
 const DEFAULT_LIMIT = 100;
 const LIST_COLUMNS = "id, created_at, action, caller, actor_kind, actor_email, org_id, " +
     "thread_id, turn_id, target_type, target_id, status, summary, " +
-    "error_code, owner_email, visibility, app";
+    "error_code, owner_email, visibility, app, run_id, task_id, " +
+    "parent_task_id, source_kind, source_platform, source_id, source_url, " +
+    "network_protocol, network_id, network_peer";
 function clampLimit(limit) {
     return Math.min(Math.max(1, Math.floor(limit ?? DEFAULT_LIMIT)), MAX_LIMIT);
 }
@@ -254,12 +256,17 @@ async function selectAuditRows(scope, filters, limit) {
     if (typeof filters.beforeMs === "number") {
         push("created_at < ?", Math.floor(filters.beforeMs));
     }
+    if (filters.after) {
+        where.push("(created_at > ? OR (created_at = ? AND id > ?))");
+        args.push(Math.floor(filters.after.createdAt), Math.floor(filters.after.createdAt), filters.after.id);
+    }
     const offset = Math.max(0, Math.floor(filters.offset ?? 0));
+    const direction = filters.order === "asc" ? "ASC" : "DESC";
     // `id` breaks created_at ties so offset pages neither repeat nor skip rows.
     const result = await client.execute({
         sql: `SELECT ${LIST_COLUMNS} FROM agent_audit_log
           WHERE ${where.join(" AND ")}
-          ORDER BY created_at DESC, id DESC
+          ORDER BY created_at ${direction}, id ${direction}
           LIMIT ? OFFSET ?`,
         args: [...args, limit, offset],
     });

package/dist/audit/types.d.ts

@@ -1,5 +1,5 @@
 export type AuditStatus = "success" | "error" | "denied";
-export type AuditActorKind = "agent" | "human" | "system";
+export type AuditActorKind = "agent" | "human" | "service" | "system";
 /**
  * Who can read an event besides its owner.
  * - `private` — the owner only (the default; personal content stays here).
@@ -81,4 +81,15 @@ export interface AuditQueryFilters {
     beforeMs?: number;
     limit?: number;
     offset?: number;
+    /** Sort direction on (createdAt, id). Defaults to newest first. */
+    order?: "asc" | "desc";
+    /**
+     * Keyset position for an incremental pull: only rows strictly after this
+     * (createdAt, id) in `asc` order. Stable under concurrent inserts, which
+     * `offset` is not.
+     */
+    after?: {
+        createdAt: number;
+        id: string;
+    };
 }

package/dist/cli/connect.js

@@ -1695,7 +1695,7 @@ export async function runServiceTokenMint(parsed, deps = {}) {
     const serviceName = parsed.serviceToken?.trim() ?? "";
     if (!parsed.url) {
         logErr("  --service-token requires the app URL.");
-        logErr("  Usage: npx @agent-native/core@latest connect <url> --service-token <name> [--ttl-days <1-365>]");
+        logErr("  Usage: npx @agent-native/core@latest connect <url> --service-token <name> [--ttl-days <1-3650>]");
         return false;
     }
     if (!serviceName) {
@@ -1790,7 +1790,7 @@ Usage:
       No-browser fallback. Skip the device flow and write the entry with
       the supplied token (get it from the app's Connect page).
 
-  npx @agent-native/core@latest connect <url> --service-token <name> [--ttl-days <1-365>]
+  npx @agent-native/core@latest connect <url> --service-token <name> [--ttl-days <1-3650>]
       Mint an ORG service token for CI (e.g. the PLAN_RECAP_TOKEN secret for
       PR Visual Recap). Authenticates you via the browser device flow, then
       mints a token owned by your ORGANIZATION — it keeps working if you
@@ -1831,6 +1831,11 @@ export async function runConnect(args, deps = {}) {
             return;
         }
         const parsed = parseConnectArgs(args);
+        if (parsed.ttlDays !== undefined && parsed.serviceToken === undefined) {
+            logErr("  --ttl-days is only supported with --service-token. Set a personal token lifetime on the app's Connect page.");
+            process.exitCode = 1;
+            return;
+        }
         if (parsed.mode) {
             let ok;
             if (parsed.mode === "reconnect" || parsed.mode === "reauth") {