ad2app-lib 1.38.0 → 1.39.0

package/dist/types/agent/I_AgentGrant.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent domain — delegated authority DTOs (spec 163).
+ *
+ * The contract behind "an assistant acting for a creator". An agent client
+ * (today: ad2app-mcp) never holds a creator-equivalent credential. It holds a
+ * GRANT REFERENCE, and exchanges that reference — plus its own client
+ * credential — for a short-lived, scope-limited access token.
+ *
+ * The two halves are deliberately useless alone:
+ *   - the grant id is not a secret (it authenticates nobody by itself)
+ *   - the client credential proves WHICH CLIENT is asking, never WHOSE
+ *     ACCOUNT may be acted on
+ *
+ * That property is spec FR-029, and it is what makes this a security
+ * improvement rather than a regression. See specs/speckit/
+ * 163-mcp-delegated-auth-direct-upload/contracts/agent-grant.md.
+ */
+/**
+ * The complete set of capabilities an agent grant may carry.
+ *
+ * This list is a CEILING, not a starting point: it is exactly what the
+ * connector's existing tools already do. Widening it is a spec change, never a
+ * config change (spec Assumptions, "Granted capabilities").
+ */
+export declare const AGENT_SCOPES: readonly ["social:post", "social:read", "social:analytics", "social:accounts", "media:upload", "social:billing"];
+export type T_AgentScope = (typeof AGENT_SCOPES)[number];
+/** Narrowing guard — an unrecognised scope must fail closed at issue time. */
+export declare const isAgentScope: (value: string) => value is T_AgentScope;
+/** Why a grant stopped being usable. Recorded for audit; the row survives. */
+export type T_AgentGrantRevokedReason = 'creator' | 'admin' | 'credential_invalid' | 'superseded';
+/**
+ * One creator's standing permission for one agent client.
+ *
+ * Lives until revoked — months. Not to be confused with the access token
+ * derived from it, which lives for minutes (see AgentAccessTokenDTO).
+ *
+ * Returned by GET /auth/agent-grants so a creator can answer "what has access
+ * to my account?". Never carries a token.
+ */
+export declare class AgentGrantDTO {
+    /** The grant reference. Not a secret — useless without the client credential. */
+    id: string;
+    /** The acting client, e.g. "ad2app-mcp". */
+    clientId: string;
+    /** Granted capabilities. Never widened after issue; a wider grant is a new grant. */
+    scopes: T_AgentScope[];
+    createdAt: string;
+    /** Updated when an access token is issued, not on every request. */
+    lastUsedAt?: string | null;
+    revokedAt?: string | null;
+    revokedReason?: T_AgentGrantRevokedReason | null;
+    constructor(data: AgentGrantDTO);
+}
+/**
+ * The ONLY accepted way to ask for agent authority (spec FR-027).
+ *
+ * A creator's identity — user id, email, Firebase uid — is deliberately NOT a
+ * field here and must be REJECTED rather than ignored if one arrives. An
+ * earlier draft allowed issuing against a creator identity; that would have
+ * made the client credential a master key over every account in the database,
+ * including accounts that never connected an assistant (review 2026-09-12,
+ * finding F1).
+ */
+export declare class AgentAccessTokenRequestDTO {
+    /** The grant reference, and nothing else. */
+    grantId: string;
+    /**
+     * Optional narrowing: request FEWER scopes than the grant carries. Must be a
+     * subset — a request for more than was granted fails closed.
+     */
+    scopes?: T_AgentScope[];
+    constructor(data: AgentAccessTokenRequestDTO);
+}
+/**
+ * A short-lived pass. Minutes, not months.
+ *
+ * The lifetime is the revocation window: renewal re-checks the grant, so a
+ * revoked grant stops producing tokens within one lifetime. That re-check is
+ * the entire point of keeping this short (spec FR-006, research R3).
+ */
+export declare class AgentAccessTokenDTO {
+    accessToken: string;
+    /** Seconds. Also the documented worst-case revocation latency. */
+    expiresIn: number;
+    grantId: string;
+    scopes: T_AgentScope[];
+    constructor(data: AgentAccessTokenDTO);
+}
+/**
+ * The `act` claim: present ⇒ an agent is acting for the creator named by `sub`;
+ * absent ⇒ the creator is acting directly.
+ *
+ * This distinction is what the backend cannot currently make, and what lets
+ * agent-specific policy exist at all (spec FR-001).
+ */
+export interface I_AgentActorClaim {
+    client_id: string;
+    grant_id: string;
+}

package/dist/types/agent/I_AgentGrant.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Agent domain — delegated authority DTOs (spec 163).
+ *
+ * The contract behind "an assistant acting for a creator". An agent client
+ * (today: ad2app-mcp) never holds a creator-equivalent credential. It holds a
+ * GRANT REFERENCE, and exchanges that reference — plus its own client
+ * credential — for a short-lived, scope-limited access token.
+ *
+ * The two halves are deliberately useless alone:
+ *   - the grant id is not a secret (it authenticates nobody by itself)
+ *   - the client credential proves WHICH CLIENT is asking, never WHOSE
+ *     ACCOUNT may be acted on
+ *
+ * That property is spec FR-029, and it is what makes this a security
+ * improvement rather than a regression. See specs/speckit/
+ * 163-mcp-delegated-auth-direct-upload/contracts/agent-grant.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentAccessTokenDTO = exports.AgentAccessTokenRequestDTO = exports.AgentGrantDTO = exports.isAgentScope = exports.AGENT_SCOPES = void 0;
+// ── Scopes ───────────────────────────────────────────────────────────────────
+/**
+ * The complete set of capabilities an agent grant may carry.
+ *
+ * This list is a CEILING, not a starting point: it is exactly what the
+ * connector's existing tools already do. Widening it is a spec change, never a
+ * config change (spec Assumptions, "Granted capabilities").
+ */
+exports.AGENT_SCOPES = [
+    /** create, update, cancel and retry posts */
+    'social:post',
+    /** list posts, accounts and subscription status */
+    'social:read',
+    /** read account and post analytics */
+    'social:analytics',
+    /** connect and disconnect social accounts */
+    'social:accounts',
+    /** request upload authority for the creator's own media */
+    'media:upload',
+    /**
+     * Read subscription status and obtain an upgrade checkout URL.
+     *
+     * Deliberately separate from `social:read` (review L3): the checkout route is
+     * a POST that creates a Stripe session. It moves no money — the creator still
+     * pays on Stripe's own page — but a scope named "read" guarding it is the
+     * kind of mismatch that gets copied to somewhere it does matter.
+     */
+    'social:billing',
+];
+/** Narrowing guard — an unrecognised scope must fail closed at issue time. */
+const isAgentScope = (value) => exports.AGENT_SCOPES.includes(value);
+exports.isAgentScope = isAgentScope;
+// ── AgentGrantDTO ────────────────────────────────────────────────────────────
+/**
+ * One creator's standing permission for one agent client.
+ *
+ * Lives until revoked — months. Not to be confused with the access token
+ * derived from it, which lives for minutes (see AgentAccessTokenDTO).
+ *
+ * Returned by GET /auth/agent-grants so a creator can answer "what has access
+ * to my account?". Never carries a token.
+ */
+class AgentGrantDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.clientId = data.clientId;
+        this.scopes = data.scopes;
+        this.createdAt = data.createdAt;
+        this.lastUsedAt = data.lastUsedAt ?? null;
+        this.revokedAt = data.revokedAt ?? null;
+        this.revokedReason = data.revokedReason ?? null;
+    }
+}
+exports.AgentGrantDTO = AgentGrantDTO;
+// ── AgentAccessTokenRequestDTO ───────────────────────────────────────────────
+/**
+ * The ONLY accepted way to ask for agent authority (spec FR-027).
+ *
+ * A creator's identity — user id, email, Firebase uid — is deliberately NOT a
+ * field here and must be REJECTED rather than ignored if one arrives. An
+ * earlier draft allowed issuing against a creator identity; that would have
+ * made the client credential a master key over every account in the database,
+ * including accounts that never connected an assistant (review 2026-09-12,
+ * finding F1).
+ */
+class AgentAccessTokenRequestDTO {
+    constructor(data) {
+        this.grantId = data.grantId;
+        this.scopes = data.scopes;
+    }
+}
+exports.AgentAccessTokenRequestDTO = AgentAccessTokenRequestDTO;
+// ── AgentAccessTokenDTO ──────────────────────────────────────────────────────
+/**
+ * A short-lived pass. Minutes, not months.
+ *
+ * The lifetime is the revocation window: renewal re-checks the grant, so a
+ * revoked grant stops producing tokens within one lifetime. That re-check is
+ * the entire point of keeping this short (spec FR-006, research R3).
+ */
+class AgentAccessTokenDTO {
+    constructor(data) {
+        this.accessToken = data.accessToken;
+        this.expiresIn = data.expiresIn;
+        this.grantId = data.grantId;
+        this.scopes = data.scopes;
+    }
+}
+exports.AgentAccessTokenDTO = AgentAccessTokenDTO;

package/dist/types/agent/I_AgentMediaUpload.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Agent domain — media upload DTOs (spec 163).
+ *
+ * Replaces the browser hand-off as the DEFAULT way an agent adds a creator's
+ * media. The bytes travel from wherever the file already is — the agent
+ * client's own machine — straight to storage. They do not pass through a
+ * browser, and the creator is never asked to confirm an upload finished.
+ *
+ * See specs/speckit/163-mcp-delegated-auth-direct-upload/contracts/
+ * media-upload.md for how a path is chosen (attempt-then-fallback; there is no
+ * capability check, because MCP exposes none).
+ */
+/** One file's metadata. Bytes are NOT part of this — see the direct path. */
+export declare class AgentUploadFileRequestDTO {
+    fileName: string;
+    /** Must be on the backend's MIME allowlist; checked per file, not per batch. */
+    fileType: string;
+    fileSize: number;
+    constructor(data: AgentUploadFileRequestDTO);
+}
+/**
+ * A batch. Deliberately unbounded by any fixed ceiling (spec FR-013).
+ *
+ * The old browser path capped a session at ten files with one upload in flight;
+ * a 77-file batch therefore cost eight browser round-trips. That ceiling bounded
+ * a web page, not a creator, and does not apply here.
+ *
+ * NOTE: what may be PUBLISHED together is a separate limit — a carousel is at
+ * most ten anywhere. This governs uploading only.
+ */
+export declare class AgentUploadBatchRequestDTO {
+    files: AgentUploadFileRequestDTO[];
+    constructor(data: AgentUploadBatchRequestDTO);
+}
+/** Why one file was refused. The rest of the batch is unaffected (FR-015). */
+export type T_AgentUploadRejectionReason = 'file_too_large' | 'unsupported_type' | 'invalid_name' | 'invalid_size';
+/** One accepted file: where to put the bytes, and how to refer to it afterwards. */
+export declare class AgentUploadTargetDTO {
+    fileName: string;
+    /**
+     * The opaque handle used when composing a post, as `media:<id>`.
+     * Neither the creator nor the model ever handles a raw storage location.
+     */
+    mediaRef: string;
+    /**
+     * Single-purpose, short-lived write authority for THIS file only.
+     * Not general storage access, not account access.
+     */
+    uploadUrl: string;
+    /** Seconds. */
+    expiresIn: number;
+    constructor(data: AgentUploadTargetDTO);
+}
+/** One refused file, named so the creator knows which (FR-015). */
+export declare class AgentUploadRejectionDTO {
+    fileName: string;
+    reason: T_AgentUploadRejectionReason;
+    /** Plain language, for the creator. No status codes, no internal rule names. */
+    message: string;
+    constructor(data: AgentUploadRejectionDTO);
+}
+/**
+ * A batch result. Per-file outcomes, never a single aggregate verdict.
+ *
+ * `nextCursor` exists because a large batch's response has to fit in one tool
+ * result. The 77-file case is measured rather than assumed (spec FR-030,
+ * review finding F4); when a flat list does not fit, entries are paged.
+ */
+export declare class AgentUploadBatchResponseDTO {
+    targets: AgentUploadTargetDTO[];
+    rejections: AgentUploadRejectionDTO[];
+    /** Present when more entries remain; pass back to fetch the next page. */
+    nextCursor?: string | null;
+    constructor(data: AgentUploadBatchResponseDTO);
+}
+/**
+ * Per-ref confirmation that the bytes actually landed.
+ *
+ * `ready` means VERIFIED PRESENT IN STORAGE, server-side — never "the host said
+ * so" (spec FR-012). Media that is not ready cannot be attached to a post
+ * (FR-017), which is what keeps a failed upload from becoming a published post
+ * with missing images.
+ */
+export declare class AgentUploadConfirmationDTO {
+    mediaRef: string;
+    ready: boolean;
+    /** Set when not ready, in plain language the creator can act on. */
+    message?: string;
+    constructor(data: AgentUploadConfirmationDTO);
+}

package/dist/types/agent/I_AgentMediaUpload.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Agent domain — media upload DTOs (spec 163).
+ *
+ * Replaces the browser hand-off as the DEFAULT way an agent adds a creator's
+ * media. The bytes travel from wherever the file already is — the agent
+ * client's own machine — straight to storage. They do not pass through a
+ * browser, and the creator is never asked to confirm an upload finished.
+ *
+ * See specs/speckit/163-mcp-delegated-auth-direct-upload/contracts/
+ * media-upload.md for how a path is chosen (attempt-then-fallback; there is no
+ * capability check, because MCP exposes none).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentUploadConfirmationDTO = exports.AgentUploadBatchResponseDTO = exports.AgentUploadRejectionDTO = exports.AgentUploadTargetDTO = exports.AgentUploadBatchRequestDTO = exports.AgentUploadFileRequestDTO = void 0;
+// ── Requests ─────────────────────────────────────────────────────────────────
+/** One file's metadata. Bytes are NOT part of this — see the direct path. */
+class AgentUploadFileRequestDTO {
+    constructor(data) {
+        this.fileName = data.fileName;
+        this.fileType = data.fileType;
+        this.fileSize = data.fileSize;
+    }
+}
+exports.AgentUploadFileRequestDTO = AgentUploadFileRequestDTO;
+/**
+ * A batch. Deliberately unbounded by any fixed ceiling (spec FR-013).
+ *
+ * The old browser path capped a session at ten files with one upload in flight;
+ * a 77-file batch therefore cost eight browser round-trips. That ceiling bounded
+ * a web page, not a creator, and does not apply here.
+ *
+ * NOTE: what may be PUBLISHED together is a separate limit — a carousel is at
+ * most ten anywhere. This governs uploading only.
+ */
+class AgentUploadBatchRequestDTO {
+    constructor(data) {
+        this.files = data.files;
+    }
+}
+exports.AgentUploadBatchRequestDTO = AgentUploadBatchRequestDTO;
+/** One accepted file: where to put the bytes, and how to refer to it afterwards. */
+class AgentUploadTargetDTO {
+    constructor(data) {
+        this.fileName = data.fileName;
+        this.mediaRef = data.mediaRef;
+        this.uploadUrl = data.uploadUrl;
+        this.expiresIn = data.expiresIn;
+    }
+}
+exports.AgentUploadTargetDTO = AgentUploadTargetDTO;
+/** One refused file, named so the creator knows which (FR-015). */
+class AgentUploadRejectionDTO {
+    constructor(data) {
+        this.fileName = data.fileName;
+        this.reason = data.reason;
+        this.message = data.message;
+    }
+}
+exports.AgentUploadRejectionDTO = AgentUploadRejectionDTO;
+/**
+ * A batch result. Per-file outcomes, never a single aggregate verdict.
+ *
+ * `nextCursor` exists because a large batch's response has to fit in one tool
+ * result. The 77-file case is measured rather than assumed (spec FR-030,
+ * review finding F4); when a flat list does not fit, entries are paged.
+ */
+class AgentUploadBatchResponseDTO {
+    constructor(data) {
+        this.targets = data.targets;
+        this.rejections = data.rejections;
+        this.nextCursor = data.nextCursor ?? null;
+    }
+}
+exports.AgentUploadBatchResponseDTO = AgentUploadBatchResponseDTO;
+// ── Confirmation ─────────────────────────────────────────────────────────────
+/**
+ * Per-ref confirmation that the bytes actually landed.
+ *
+ * `ready` means VERIFIED PRESENT IN STORAGE, server-side — never "the host said
+ * so" (spec FR-012). Media that is not ready cannot be attached to a post
+ * (FR-017), which is what keeps a failed upload from becoming a published post
+ * with missing images.
+ */
+class AgentUploadConfirmationDTO {
+    constructor(data) {
+        this.mediaRef = data.mediaRef;
+        this.ready = data.ready;
+        this.message = data.message;
+    }
+}
+exports.AgentUploadConfirmationDTO = AgentUploadConfirmationDTO;

package/dist/types/agent/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Agent domain — barrel export (spec 163).
+ *
+ * Available from 'ad2app-lib/types' via:
+ *   import { AgentGrantDTO, AGENT_SCOPES, ... } from 'ad2app-lib/types';
+ */
+export * from './I_AgentGrant';
+export * from './I_AgentMediaUpload';

package/dist/types/agent/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Agent domain — barrel export (spec 163).
+ *
+ * Available from 'ad2app-lib/types' via:
+ *   import { AgentGrantDTO, AGENT_SCOPES, ... } from 'ad2app-lib/types';
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./I_AgentGrant"), exports);
+__exportStar(require("./I_AgentMediaUpload"), exports);

package/dist/types/index.d.ts

@@ -35,4 +35,5 @@ export * from "./I_Collaboration";
 export * from "./I_Publish";
 export * from "./I_SM_Platform";
 export * from "./scheduling";
+export * from "./agent";
 export * from "./I_AccessDenial";

package/dist/types/index.js

@@ -52,5 +52,7 @@ __exportStar(require("./I_Publish"), exports);
 __exportStar(require("./I_SM_Platform"), exports);
 // ── Scheduling domain ─────────────────────────────────────────────────────────
 __exportStar(require("./scheduling"), exports);
+// ── Agent domain (delegated authority + direct media upload, spec 163) ───────
+__exportStar(require("./agent"), exports);
 // ── Access control ────────────────────────────────────────────────────────────
 __exportStar(require("./I_AccessDenial"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/types/agent/I_AgentGrant.ts

@@ -0,0 +1,161 @@
+/**
+ * Agent domain — delegated authority DTOs (spec 163).
+ *
+ * The contract behind "an assistant acting for a creator". An agent client
+ * (today: ad2app-mcp) never holds a creator-equivalent credential. It holds a
+ * GRANT REFERENCE, and exchanges that reference — plus its own client
+ * credential — for a short-lived, scope-limited access token.
+ *
+ * The two halves are deliberately useless alone:
+ *   - the grant id is not a secret (it authenticates nobody by itself)
+ *   - the client credential proves WHICH CLIENT is asking, never WHOSE
+ *     ACCOUNT may be acted on
+ *
+ * That property is spec FR-029, and it is what makes this a security
+ * improvement rather than a regression. See specs/speckit/
+ * 163-mcp-delegated-auth-direct-upload/contracts/agent-grant.md.
+ */
+
+// ── Scopes ───────────────────────────────────────────────────────────────────
+
+/**
+ * The complete set of capabilities an agent grant may carry.
+ *
+ * This list is a CEILING, not a starting point: it is exactly what the
+ * connector's existing tools already do. Widening it is a spec change, never a
+ * config change (spec Assumptions, "Granted capabilities").
+ */
+export const AGENT_SCOPES = [
+  /** create, update, cancel and retry posts */
+  'social:post',
+  /** list posts, accounts and subscription status */
+  'social:read',
+  /** read account and post analytics */
+  'social:analytics',
+  /** connect and disconnect social accounts */
+  'social:accounts',
+  /** request upload authority for the creator's own media */
+  'media:upload',
+  /**
+   * Read subscription status and obtain an upgrade checkout URL.
+   *
+   * Deliberately separate from `social:read` (review L3): the checkout route is
+   * a POST that creates a Stripe session. It moves no money — the creator still
+   * pays on Stripe's own page — but a scope named "read" guarding it is the
+   * kind of mismatch that gets copied to somewhere it does matter.
+   */
+  'social:billing',
+] as const;
+
+export type T_AgentScope = (typeof AGENT_SCOPES)[number];
+
+/** Narrowing guard — an unrecognised scope must fail closed at issue time. */
+export const isAgentScope = (value: string): value is T_AgentScope =>
+  (AGENT_SCOPES as readonly string[]).includes(value);
+
+/** Why a grant stopped being usable. Recorded for audit; the row survives. */
+export type T_AgentGrantRevokedReason =
+  | 'creator'
+  | 'admin'
+  | 'credential_invalid'
+  | 'superseded';
+
+// ── AgentGrantDTO ────────────────────────────────────────────────────────────
+
+/**
+ * One creator's standing permission for one agent client.
+ *
+ * Lives until revoked — months. Not to be confused with the access token
+ * derived from it, which lives for minutes (see AgentAccessTokenDTO).
+ *
+ * Returned by GET /auth/agent-grants so a creator can answer "what has access
+ * to my account?". Never carries a token.
+ */
+export class AgentGrantDTO {
+  /** The grant reference. Not a secret — useless without the client credential. */
+  id: string;
+  /** The acting client, e.g. "ad2app-mcp". */
+  clientId: string;
+  /** Granted capabilities. Never widened after issue; a wider grant is a new grant. */
+  scopes: T_AgentScope[];
+  createdAt: string;
+  /** Updated when an access token is issued, not on every request. */
+  lastUsedAt?: string | null;
+  revokedAt?: string | null;
+  revokedReason?: T_AgentGrantRevokedReason | null;
+
+  constructor(data: AgentGrantDTO) {
+    this.id = data.id;
+    this.clientId = data.clientId;
+    this.scopes = data.scopes;
+    this.createdAt = data.createdAt;
+    this.lastUsedAt = data.lastUsedAt ?? null;
+    this.revokedAt = data.revokedAt ?? null;
+    this.revokedReason = data.revokedReason ?? null;
+  }
+}
+
+// ── AgentAccessTokenRequestDTO ───────────────────────────────────────────────
+
+/**
+ * The ONLY accepted way to ask for agent authority (spec FR-027).
+ *
+ * A creator's identity — user id, email, Firebase uid — is deliberately NOT a
+ * field here and must be REJECTED rather than ignored if one arrives. An
+ * earlier draft allowed issuing against a creator identity; that would have
+ * made the client credential a master key over every account in the database,
+ * including accounts that never connected an assistant (review 2026-09-12,
+ * finding F1).
+ */
+export class AgentAccessTokenRequestDTO {
+  /** The grant reference, and nothing else. */
+  grantId: string;
+  /**
+   * Optional narrowing: request FEWER scopes than the grant carries. Must be a
+   * subset — a request for more than was granted fails closed.
+   */
+  scopes?: T_AgentScope[];
+
+  constructor(data: AgentAccessTokenRequestDTO) {
+    this.grantId = data.grantId;
+    this.scopes = data.scopes;
+  }
+}
+
+// ── AgentAccessTokenDTO ──────────────────────────────────────────────────────
+
+/**
+ * A short-lived pass. Minutes, not months.
+ *
+ * The lifetime is the revocation window: renewal re-checks the grant, so a
+ * revoked grant stops producing tokens within one lifetime. That re-check is
+ * the entire point of keeping this short (spec FR-006, research R3).
+ */
+export class AgentAccessTokenDTO {
+  accessToken: string;
+  /** Seconds. Also the documented worst-case revocation latency. */
+  expiresIn: number;
+  grantId: string;
+  scopes: T_AgentScope[];
+
+  constructor(data: AgentAccessTokenDTO) {
+    this.accessToken = data.accessToken;
+    this.expiresIn = data.expiresIn;
+    this.grantId = data.grantId;
+    this.scopes = data.scopes;
+  }
+}
+
+// ── Token claim shape ────────────────────────────────────────────────────────
+
+/**
+ * The `act` claim: present ⇒ an agent is acting for the creator named by `sub`;
+ * absent ⇒ the creator is acting directly.
+ *
+ * This distinction is what the backend cannot currently make, and what lets
+ * agent-specific policy exist at all (spec FR-001).
+ */
+export interface I_AgentActorClaim {
+  client_id: string;
+  grant_id: string;
+}

package/src/types/agent/I_AgentMediaUpload.ts

@@ -0,0 +1,136 @@
+/**
+ * Agent domain — media upload DTOs (spec 163).
+ *
+ * Replaces the browser hand-off as the DEFAULT way an agent adds a creator's
+ * media. The bytes travel from wherever the file already is — the agent
+ * client's own machine — straight to storage. They do not pass through a
+ * browser, and the creator is never asked to confirm an upload finished.
+ *
+ * See specs/speckit/163-mcp-delegated-auth-direct-upload/contracts/
+ * media-upload.md for how a path is chosen (attempt-then-fallback; there is no
+ * capability check, because MCP exposes none).
+ */
+
+// ── Requests ─────────────────────────────────────────────────────────────────
+
+/** One file's metadata. Bytes are NOT part of this — see the direct path. */
+export class AgentUploadFileRequestDTO {
+  fileName: string;
+  /** Must be on the backend's MIME allowlist; checked per file, not per batch. */
+  fileType: string;
+  fileSize: number;
+
+  constructor(data: AgentUploadFileRequestDTO) {
+    this.fileName = data.fileName;
+    this.fileType = data.fileType;
+    this.fileSize = data.fileSize;
+  }
+}
+
+/**
+ * A batch. Deliberately unbounded by any fixed ceiling (spec FR-013).
+ *
+ * The old browser path capped a session at ten files with one upload in flight;
+ * a 77-file batch therefore cost eight browser round-trips. That ceiling bounded
+ * a web page, not a creator, and does not apply here.
+ *
+ * NOTE: what may be PUBLISHED together is a separate limit — a carousel is at
+ * most ten anywhere. This governs uploading only.
+ */
+export class AgentUploadBatchRequestDTO {
+  files: AgentUploadFileRequestDTO[];
+
+  constructor(data: AgentUploadBatchRequestDTO) {
+    this.files = data.files;
+  }
+}
+
+// ── Responses ────────────────────────────────────────────────────────────────
+
+/** Why one file was refused. The rest of the batch is unaffected (FR-015). */
+export type T_AgentUploadRejectionReason =
+  | 'file_too_large'
+  | 'unsupported_type'
+  | 'invalid_name'
+  | 'invalid_size';
+
+/** One accepted file: where to put the bytes, and how to refer to it afterwards. */
+export class AgentUploadTargetDTO {
+  fileName: string;
+  /**
+   * The opaque handle used when composing a post, as `media:<id>`.
+   * Neither the creator nor the model ever handles a raw storage location.
+   */
+  mediaRef: string;
+  /**
+   * Single-purpose, short-lived write authority for THIS file only.
+   * Not general storage access, not account access.
+   */
+  uploadUrl: string;
+  /** Seconds. */
+  expiresIn: number;
+
+  constructor(data: AgentUploadTargetDTO) {
+    this.fileName = data.fileName;
+    this.mediaRef = data.mediaRef;
+    this.uploadUrl = data.uploadUrl;
+    this.expiresIn = data.expiresIn;
+  }
+}
+
+/** One refused file, named so the creator knows which (FR-015). */
+export class AgentUploadRejectionDTO {
+  fileName: string;
+  reason: T_AgentUploadRejectionReason;
+  /** Plain language, for the creator. No status codes, no internal rule names. */
+  message: string;
+
+  constructor(data: AgentUploadRejectionDTO) {
+    this.fileName = data.fileName;
+    this.reason = data.reason;
+    this.message = data.message;
+  }
+}
+
+/**
+ * A batch result. Per-file outcomes, never a single aggregate verdict.
+ *
+ * `nextCursor` exists because a large batch's response has to fit in one tool
+ * result. The 77-file case is measured rather than assumed (spec FR-030,
+ * review finding F4); when a flat list does not fit, entries are paged.
+ */
+export class AgentUploadBatchResponseDTO {
+  targets: AgentUploadTargetDTO[];
+  rejections: AgentUploadRejectionDTO[];
+  /** Present when more entries remain; pass back to fetch the next page. */
+  nextCursor?: string | null;
+
+  constructor(data: AgentUploadBatchResponseDTO) {
+    this.targets = data.targets;
+    this.rejections = data.rejections;
+    this.nextCursor = data.nextCursor ?? null;
+  }
+}
+
+// ── Confirmation ─────────────────────────────────────────────────────────────
+
+/**
+ * Per-ref confirmation that the bytes actually landed.
+ *
+ * `ready` means VERIFIED PRESENT IN STORAGE, server-side — never "the host said
+ * so" (spec FR-012). Media that is not ready cannot be attached to a post
+ * (FR-017), which is what keeps a failed upload from becoming a published post
+ * with missing images.
+ */
+export class AgentUploadConfirmationDTO {
+  mediaRef: string;
+  ready: boolean;
+  /** Set when not ready, in plain language the creator can act on. */
+  message?: string;
+
+  constructor(data: AgentUploadConfirmationDTO) {
+    this.mediaRef = data.mediaRef;
+    this.ready = data.ready;
+    this.message = data.message;
+  }
+}

package/src/types/agent/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent domain — barrel export (spec 163).
+ *
+ * Available from 'ad2app-lib/types' via:
+ *   import { AgentGrantDTO, AGENT_SCOPES, ... } from 'ad2app-lib/types';
+ */
+
+export * from './I_AgentGrant';
+export * from './I_AgentMediaUpload';

package/src/types/index.ts

@@ -37,5 +37,8 @@ export * from "./I_SM_Platform";
 // ── Scheduling domain ─────────────────────────────────────────────────────────
 export * from "./scheduling";
 
+// ── Agent domain (delegated authority + direct media upload, spec 163) ───────
+export * from "./agent";
+
 // ── Access control ────────────────────────────────────────────────────────────
 export * from "./I_AccessDenial";