openclaw-engram 3.7.5 → 3.9.0

package/README.md

@@ -68,6 +68,7 @@ All fields are set under `plugins.entries.engram.config`:
 | `url` | string | `http://localhost:37777` | Engram server base URL |
 | `token` | string | *(required)* | Bearer token for API authentication |
 | `project` | string | *(auto-detected)* | Project scope override; defaults to workspace identity |
+| `clientInstanceId` | string | *(optional)* | Opaque non-secret installation reference that enables V3 identity |
 | `contextLimit` | number | `10` | Maximum observations injected per prompt turn |
 | `sessionContextLimit` | number | `20` | Maximum observations injected at session start |
 | `tokenBudget` | number | `2000` | Token budget for context injection (~4 chars/token) |

package/dist/client.d.ts

@@ -6,6 +6,8 @@
  */
 import { AvailabilityTracker } from './availability.js';
 import type { PluginConfig } from './config.js';
+import { type ProjectIdentity, type ProjectIdentityV2 } from './identity.js';
+import { type ProjectIdentityV3 } from './project-identity-v3.js';
 export interface Observation {
     id: number;
     title: string;
@@ -91,6 +93,42 @@ export interface BulkImportResponse {
 export interface BulkDeleteResponse {
     deleted: number;
 }
+export interface ProjectRegistrationSuccess {
+    ok: true;
+    canonicalProject: string;
+}
+export interface ResolvedProjectRegistrationSuccess extends ProjectRegistrationSuccess {
+    projectSelector: string;
+    projectIdentityV2?: ProjectIdentityV2;
+    projectIdentityV3?: ProjectIdentityV3;
+}
+export interface ProjectRegistrationFailure {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        upgradeAction: string;
+        httpStatus: number;
+    };
+}
+export type ProjectRegistrationResult = ProjectRegistrationSuccess | ProjectRegistrationFailure;
+export type ResolvedProjectRegistrationResult = ResolvedProjectRegistrationSuccess | ProjectRegistrationFailure;
+export interface OutcomeRetirement {
+    contract_version: 'engram.outcome-retirement.v1';
+    code: 'OUTCOME_CALLBACK_RETIRED';
+    action: 'upgrade_outcome_adapter';
+}
+export type OutcomeRecordingResult = boolean | OutcomeRetirement;
+export declare function isOutcomeRetirement(result: OutcomeRecordingResult): result is OutcomeRetirement;
+export interface ProjectRegistrationClient {
+    registerAndResolveProject(identity: ProjectIdentity, selector: string): Promise<ProjectRegistrationResult>;
+    readonly clientInstanceId?: string;
+}
+/**
+ * Register an explicit project override as a selector-only shared scope.
+ * Without an override, resolve and register the workspace's full identity.
+ */
+export declare function resolveAndRegisterProject(client: ProjectRegistrationClient, agentId: string, workspaceDir: string | undefined, configuredProject?: string): Promise<ResolvedProjectRegistrationResult>;
 /** A single observation returned by the decisions search endpoint. */
 export interface DecisionSearchObservation {
     title?: string;
@@ -157,13 +195,28 @@ export declare class EngramRestClient {
     private readonly baseUrl;
     private readonly token;
     private readonly defaultTimeoutMs;
+    private readonly completedProjectRegistrations;
+    private readonly inFlightProjectRegistrations;
+    private readonly v3ContextDescriptors;
     readonly availability: AvailabilityTracker;
+    readonly clientInstanceId?: string;
     constructor(config: PluginConfig);
+    /**
+     * Registration barrier for every project-scoped OpenClaw access.
+     *
+     * The full identity and outer compatibility selector are resolved before a
+     * caller sends its first data request. Concurrent and late calls reuse the
+     * same result. Project metadata routes a namespace; the bearer header remains
+     * the independent authorization gate.
+     */
+    registerAndResolveProject(identity: ProjectIdentity, selector: string): Promise<ProjectRegistrationResult>;
+    private performProjectRegistration;
+    private scopedProjectRequest;
     /**
      * Fetch session context for injection (static session-level context).
      * POST /api/context/inject
      */
-    getContextInject(agentId: string, cwd?: string): Promise<ContextInjectResponse | null>;
+    getContextInject(agentId: string, cwd?: string, project?: string, projectIdentityV2?: ProjectIdentityV2): Promise<ContextInjectResponse | null>;
     /**
      * Per-turn context search.
      * POST /api/context/search
@@ -275,7 +328,7 @@ export declare class EngramRestClient {
      * POST /api/sessions/{sessionId}/outcome { outcome, reason }
      * sessionId is the Claude session ID string (not numeric DB ID).
      */
-    setSessionOutcome(sessionId: string, outcome: string, reason?: string): Promise<boolean>;
+    setSessionOutcome(sessionId: string, outcome: string, reason?: string): Promise<OutcomeRecordingResult>;
     /**
      * Get file-context observations for a specific file.
      * GET /api/context/by-file?path={file}&project={project}&limit={limit}

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,WAAW,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,yBAAyB,EAAE,CAAC;CAC3C;AAMD,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;gBAE/B,MAAM,EAAE,YAAY;IAYhC;;;OAGG;IACG,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IASxC;;;OAGG;IACG,aAAa,CAAC,IAAI,EAAE;QACxB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,4EAA4E;QAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,uDAAuD;QACvD,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAKzC;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAI1C;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjB;;;OAGG;IACG,WAAW,CAAC,IAAI,EAAE;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,4EAA4E;QAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjB;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjB;;;OAGG;IACG,WAAW,CAAC,IAAI,EAAE;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAIvC;;;OAGG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrE;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAI9C;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAIpD;;;;;;;;;OASG;IACG,UAAU,CACd,YAAY,EAAE,oBAAoB,EAAE,EACpC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAqBrC;;;;;;OAMG;IACH;;;OAGG;IACG,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAYnE;;;OAGG;IACG,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAyCpF;;;;OAIG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC;IASnB;;;OAGG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,SAAI,EACT,SAAS,SAAO,GACf,OAAO,CAAC,WAAW,EAAE,CAAC;IASzB;;;OAGG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,EACnC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9D,OAAO,CAAC,WAAW,EAAE,CAAC;IASzB;;;OAGG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC;IAUnB;;;OAGG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAQ5E,UAAU,CAAC,MAAM,EAAE;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAW/B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAIzD,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAI1E,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAI5F,oEAAoE;IACpE,WAAW,IAAI,OAAO;YAQR,GAAG;YAOH,IAAI;YAQJ,OAAO;CAsDtB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -7,7 +7,64 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EngramRestClient = void 0;
+exports.isOutcomeRetirement = isOutcomeRetirement;
+exports.resolveAndRegisterProject = resolveAndRegisterProject;
+const node_crypto_1 = require("node:crypto");
 const availability_js_1 = require("./availability.js");
+const identity_js_1 = require("./identity.js");
+const project_identity_v3_js_1 = require("./project-identity-v3.js");
+function isOutcomeRetirement(result) {
+    return typeof result !== 'boolean';
+}
+function parseOutcomeRetirement(payload) {
+    if (payload === null || typeof payload !== 'object')
+        return null;
+    const { contract_version, code, action } = payload;
+    if (contract_version !== 'engram.outcome-retirement.v1' ||
+        code !== 'OUTCOME_CALLBACK_RETIRED' ||
+        action !== 'upgrade_outcome_adapter')
+        return null;
+    return { contract_version, code, action };
+}
+function parseOutcomeRetirementPayload(text) {
+    try {
+        return parseOutcomeRetirement(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Register an explicit project override as a selector-only shared scope.
+ * Without an override, resolve and register the workspace's full identity.
+ */
+async function resolveAndRegisterProject(client, agentId, workspaceDir, configuredProject) {
+    try {
+        const clientInstanceId = client.clientInstanceId;
+        const identity = clientInstanceId !== undefined
+            ? (0, identity_js_1.resolveIdentity)(agentId, workspaceDir, clientInstanceId)
+            : configuredProject !== undefined
+                ? { projectId: configuredProject, agentId }
+                : (0, identity_js_1.resolveIdentity)(agentId, workspaceDir);
+        const selector = clientInstanceId !== undefined ? identity.projectId : configuredProject ?? identity.projectId;
+        const registration = await client.registerAndResolveProject(identity, selector);
+        if (!registration.ok)
+            return registration;
+        return {
+            ...registration,
+            projectSelector: selector,
+            ...(identity.projectIdentityV3 ? { projectIdentityV3: identity.projectIdentityV3 } : {}),
+            ...(identity.projectIdentityV2 ? { projectIdentityV2: identity.projectIdentityV2 } : {}),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === 'PROJECT_DESCRIPTOR_INVALID')
+            return projectDescriptorFailure();
+        const invalid = message.startsWith('PROJECT_IDENTITY_INVALID:');
+        return projectRegistrationFailure(invalid ? 'PROJECT_IDENTITY_INVALID' : 'PROJECT_IDENTITY_UNAVAILABLE', message, invalid ? 'regenerate_project_identity_v2' : 'retry_project_identity_registration', invalid ? 400 : 503);
+    }
+}
 // ---------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------
@@ -15,28 +72,172 @@ class EngramRestClient {
     baseUrl;
     token;
     defaultTimeoutMs;
+    completedProjectRegistrations = new Map();
+    inFlightProjectRegistrations = new Map();
+    v3ContextDescriptors = new Map();
     availability;
+    clientInstanceId;
     constructor(config) {
         // Extract origin from potentially path-bearing URL
         this.baseUrl = extractOrigin(config.url);
         this.token = config.token;
         this.defaultTimeoutMs = config.timeoutMs;
         this.availability = new availability_js_1.AvailabilityTracker();
+        this.clientInstanceId = config.clientInstanceId;
     }
     // ---------------------------------------------------------------------------
     // Endpoints
     // ---------------------------------------------------------------------------
+    /**
+     * Registration barrier for every project-scoped OpenClaw access.
+     *
+     * The full identity and outer compatibility selector are resolved before a
+     * caller sends its first data request. Concurrent and late calls reuse the
+     * same result. Project metadata routes a namespace; the bearer header remains
+     * the independent authorization gate.
+     */
+    async registerAndResolveProject(identity, selector) {
+        const requestedDescriptor = identity.projectIdentityV3;
+        let descriptor;
+        let validatedIdentity = identity;
+        if (requestedDescriptor !== undefined) {
+            const validatedDescriptor = validateProjectDescriptorV3(requestedDescriptor);
+            if (!validatedDescriptor)
+                return projectDescriptorFailure();
+            descriptor = validatedDescriptor;
+            validatedIdentity = { ...identity, projectIdentityV3: descriptor };
+        }
+        let validatedSelector = selector;
+        if (!descriptor) {
+            try {
+                validatedSelector = (0, identity_js_1.validateProjectSelectorV2)(selector);
+            }
+            catch {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'PROJECT_IDENTITY_INVALID',
+                        message: 'project selector is empty or malformed',
+                        upgradeAction: 'regenerate_project_identity_v2',
+                        httpStatus: 400,
+                    },
+                };
+            }
+        }
+        const key = JSON.stringify(descriptor ?? [validatedSelector, identity.projectIdentityV2 ?? null]);
+        const completed = this.completedProjectRegistrations.get(key);
+        if (completed)
+            return completed;
+        const inFlight = this.inFlightProjectRegistrations.get(key);
+        if (inFlight)
+            return inFlight;
+        const registration = this.performProjectRegistration(validatedIdentity, validatedSelector);
+        this.inFlightProjectRegistrations.set(key, registration);
+        try {
+            const result = await registration;
+            if (result.ok && descriptor) {
+                this.v3ContextDescriptors.set(selector, descriptor);
+                this.v3ContextDescriptors.set(result.canonicalProject, descriptor);
+            }
+            if (result.ok || result.error.httpStatus === 400 || result.error.httpStatus === 409) {
+                this.completedProjectRegistrations.set(key, result);
+            }
+            return result;
+        }
+        finally {
+            this.inFlightProjectRegistrations.delete(key);
+        }
+    }
+    async performProjectRegistration(identity, selector) {
+        if (!this.availability.isAvailable()) {
+            return projectRegistrationFailure('PROJECT_IDENTITY_UNAVAILABLE', 'engram is temporarily unavailable', 'retry_project_identity_registration', 503);
+        }
+        const path = '/api/context/inject';
+        const url = this.baseUrl + path;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.defaultTimeoutMs);
+        const body = identity.projectIdentityV3
+            ? {
+                project_descriptor: identity.projectIdentityV3,
+                identity_only: true,
+            }
+            : {
+                project: selector,
+                ...(identity.projectIdentityV2 ? { project_identity: identity.projectIdentityV2 } : {}),
+                identity_only: true,
+            };
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.token}`,
+                    'Content-Type': 'application/json',
+                    'X-Engram-Project-Identity-Adapter': 'openclaw',
+                    'X-Request-ID': (0, node_crypto_1.randomUUID)(),
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            let payload = {};
+            if (text) {
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch {
+                    payload = {};
+                }
+            }
+            if (!response.ok) {
+                if (response.status >= 500 || response.status === 401 || response.status === 403) {
+                    this.availability.recordFailure();
+                }
+                const parsed = parseProjectRegistrationError(payload, response.status);
+                return projectRegistrationFailure(parsed.code, parsed.message, parsed.upgradeAction, response.status);
+            }
+            const canonical = readCanonicalProject(payload, identity.projectIdentityV3);
+            if (!canonical) {
+                this.availability.recordFailure();
+                return projectRegistrationFailure('PROJECT_IDENTITY_UNAVAILABLE', 'project identity registration response is malformed', 'retry_project_identity_registration', 503);
+            }
+            this.availability.recordSuccess();
+            return { ok: true, canonicalProject: canonical };
+        }
+        catch (err) {
+            this.availability.recordFailure();
+            const message = err instanceof Error ? err.message : String(err);
+            return projectRegistrationFailure('PROJECT_IDENTITY_UNAVAILABLE', message, 'retry_project_identity_registration', 503);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    scopedProjectRequest(body) {
+        if (this.clientInstanceId === undefined)
+            return body;
+        const descriptor = this.v3ContextDescriptors.get(body.project);
+        if (!descriptor)
+            return null;
+        const { project: _, agent_id: _agentID, ...request } = body;
+        return { ...request, project_descriptor: descriptor };
+    }
     /**
      * Fetch session context for injection (static session-level context).
      * POST /api/context/inject
      */
-    async getContextInject(agentId, cwd) {
-        // Inject returns large payloads (80KB+) with vector search — needs more than default 5s.
-        // Timeout failures here trigger availability cooldown, blocking ALL engram tools for 60s.
-        return this.post('/api/context/inject', {
-            agent_id: agentId,
-            ...(cwd ? { cwd } : {}),
-        }, 15_000);
+    async getContextInject(agentId, cwd, project, projectIdentityV2) {
+        // A V3 context request only reuses the descriptor carried through successful registration.
+        const projectDescriptor = project ? this.v3ContextDescriptors.get(project) : undefined;
+        if (this.clientInstanceId !== undefined && !projectDescriptor)
+            return null;
+        return this.post('/api/context/inject', projectDescriptor
+            ? { project_descriptor: projectDescriptor }
+            : {
+                agent_id: agentId,
+                ...(cwd ? { cwd } : {}),
+                ...(project ? { project } : {}),
+                ...(projectIdentityV2 ? { project_identity: projectIdentityV2 } : {}),
+            }, 15_000);
     }
     /**
      * Per-turn context search.
@@ -44,7 +245,8 @@ class EngramRestClient {
      */
     async searchContext(body) {
         // Context search does vector query (embedding + pgvector) — needs more than default 5s.
-        return this.post('/api/context/search', body, 15_000);
+        const request = this.scopedProjectRequest(body);
+        return request ? this.post('/api/context/search', request, 15_000) : null;
     }
     /**
      * Search for relevant decisions.
@@ -113,6 +315,8 @@ class EngramRestClient {
      * synthetic one per call, preventing phantom session proliferation.
      */
     async bulkImport(observations, sessionId) {
+        if (this.clientInstanceId !== undefined)
+            return null;
         if (observations.length === 0)
             return { imported: 0, skipped_duplicates: 0 };
         // All observations in a batch must share the same project.
@@ -197,8 +401,49 @@ class EngramRestClient {
      * sessionId is the Claude session ID string (not numeric DB ID).
      */
     async setSessionOutcome(sessionId, outcome, reason) {
-        const resp = await this.post(`/api/sessions/${encodeURIComponent(sessionId)}/outcome`, { outcome, reason: reason ?? '' }, 3000);
-        return resp != null;
+        if (!this.availability.isAvailable())
+            return false;
+        const path = `/api/sessions/${encodeURIComponent(sessionId)}/outcome`;
+        const timeout = 3000;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        const startMs = Date.now();
+        try {
+            const response = await fetch(this.baseUrl + path, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    'Content-Type': 'application/json',
+                    'X-Engram-Project-Identity-Adapter': 'openclaw',
+                    'X-Request-ID': (0, node_crypto_1.randomUUID)(),
+                },
+                body: JSON.stringify({ outcome, reason: reason ?? '' }),
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            if (response.status === 410) {
+                const retirement = parseOutcomeRetirementPayload(text);
+                if (retirement)
+                    return retirement;
+            }
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status} ${response.statusText} (${Date.now() - startMs}ms): ${text.slice(0, 200)}`);
+            }
+            this.availability.recordSuccess();
+            return text ? JSON.parse(text) !== null : false;
+        }
+        catch (err) {
+            const elapsedMs = Date.now() - startMs;
+            this.availability.recordFailure();
+            const msg = err instanceof Error ? err.message : String(err);
+            const isAbort = err instanceof Error && err.name === 'AbortError';
+            console.error(`[engram] POST ${path} failed after ${elapsedMs}ms` +
+                `${isAbort ? ` (timeout=${timeout}ms)` : ''}: ${msg}`);
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     /**
      * Get file-context observations for a specific file.
@@ -221,7 +466,8 @@ class EngramRestClient {
             body.anchor_id = params.anchor_id;
         if (params?.limit)
             body.limit = params.limit;
-        const resp = await this.post('/api/context/search', body, 15_000);
+        const request = this.scopedProjectRequest(body);
+        const resp = request ? await this.post('/api/context/search', request, 15_000) : null;
         return resp?.observations ?? [];
     }
     /**
@@ -295,6 +541,8 @@ class EngramRestClient {
         try {
             const headers = {
                 'Authorization': `Bearer ${this.token}`,
+                'X-Engram-Project-Identity-Adapter': 'openclaw',
+                'X-Request-ID': (0, node_crypto_1.randomUUID)(),
             };
             if (body !== undefined) {
                 headers['Content-Type'] = 'application/json';
@@ -347,4 +595,125 @@ function extractOrigin(rawUrl) {
         return trimmed.replace(/\/$/, '');
     }
 }
+function projectRegistrationFailure(code, message, upgradeAction, httpStatus) {
+    return { ok: false, error: { code, message, upgradeAction, httpStatus } };
+}
+function projectDescriptorFailure() {
+    return projectRegistrationFailure('PROJECT_DESCRIPTOR_INVALID', 'project descriptor is invalid', 'repair_project_descriptor', 400);
+}
+const V3_DESCRIPTOR_FIELDS = {
+    version: true,
+    anchor_project_id: true,
+    name: true,
+    scope: true,
+    normalized_git_remotes: true,
+    legacy_identifiers: true,
+    client_instance_id: true,
+};
+const V3_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const V3_PROJECT_RESOLUTION_FIELDS = {
+    outcome: true,
+    project_key: true,
+    resolved_scope: true,
+    correlation: true,
+    redirect_reference: true,
+};
+function isValidOpaqueReferenceV3(value) {
+    return typeof value === 'string' &&
+        value.length > 0 &&
+        Array.from(value).length <= 256 &&
+        !/[\p{White_Space}\p{Cc}\/\\@]/u.test(value);
+}
+function validateProjectDescriptorV3(descriptor) {
+    try {
+        if (typeof descriptor !== 'object' || descriptor === null || Array.isArray(descriptor))
+            return null;
+        const keys = Object.keys(descriptor);
+        if (keys.length !== 7 || keys.some((key) => !Object.hasOwn(V3_DESCRIPTOR_FIELDS, key)))
+            return null;
+        if (!('version' in descriptor) ||
+            !('anchor_project_id' in descriptor) ||
+            !('name' in descriptor) ||
+            !('scope' in descriptor) ||
+            !('normalized_git_remotes' in descriptor) ||
+            !('legacy_identifiers' in descriptor) ||
+            !('client_instance_id' in descriptor))
+            return null;
+        return (0, project_identity_v3_js_1.buildProjectIdentityV3)({
+            anchor: {
+                version: descriptor.version,
+                project_id: descriptor.anchor_project_id,
+                name: descriptor.name,
+                scope: descriptor.scope,
+            },
+            version: descriptor.version,
+            anchor_project_id: descriptor.anchor_project_id,
+            name: descriptor.name,
+            scope: descriptor.scope,
+            normalized_git_remotes: descriptor.normalized_git_remotes,
+            legacy_identifiers: descriptor.legacy_identifiers,
+            client_instance_id: descriptor.client_instance_id,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function readCanonicalProject(payload, descriptor) {
+    if (!payload || typeof payload !== 'object')
+        return '';
+    if (descriptor) {
+        if (!Object.hasOwn(payload, 'project_resolution_v3') || !('project_resolution_v3' in payload))
+            return '';
+        const resolution = payload.project_resolution_v3;
+        if (!resolution || typeof resolution !== 'object' || Array.isArray(resolution))
+            return '';
+        const typedResolution = resolution;
+        const keys = Object.keys(typedResolution);
+        if (keys.some((key) => !Object.hasOwn(V3_PROJECT_RESOLUTION_FIELDS, key)) ||
+            !Object.hasOwn(typedResolution, 'outcome') ||
+            !Object.hasOwn(typedResolution, 'project_key') ||
+            !Object.hasOwn(typedResolution, 'resolved_scope') ||
+            !Object.hasOwn(typedResolution, 'correlation'))
+            return '';
+        const { outcome, project_key, resolved_scope, correlation, redirect_reference: redirectReference } = typedResolution;
+        if ((outcome !== 'PROJECT_RESOLVED' && outcome !== 'PROJECT_REDIRECTED') ||
+            keys.length !== (outcome === 'PROJECT_REDIRECTED' ? 5 : 4) ||
+            typeof project_key !== 'string' ||
+            !V3_UUID.test(project_key) ||
+            resolved_scope !== descriptor.scope ||
+            !isValidOpaqueReferenceV3(correlation) ||
+            (outcome === 'PROJECT_REDIRECTED' && !isValidOpaqueReferenceV3(redirectReference)))
+            return '';
+        return project_key;
+    }
+    if (!('canonical_project' in payload))
+        return '';
+    try {
+        return (0, identity_js_1.validateCanonicalProjectV2)(payload.canonical_project);
+    }
+    catch {
+        return '';
+    }
+}
+function parseProjectRegistrationError(payload, status) {
+    const fallback = status === 400
+        ? { code: 'PROJECT_IDENTITY_INVALID', upgradeAction: 'regenerate_project_identity_v2' }
+        : status === 409
+            ? { code: 'PROJECT_IDENTITY_AMBIGUOUS', upgradeAction: 'send_project_identity_v2' }
+            : { code: 'PROJECT_IDENTITY_UNAVAILABLE', upgradeAction: 'retry_project_identity_registration' };
+    if (!payload || typeof payload !== 'object') {
+        return { ...fallback, message: `HTTP ${status} project identity registration failed` };
+    }
+    const error = payload.error;
+    if (!error || typeof error !== 'object') {
+        return { ...fallback, message: `HTTP ${status} project identity registration failed` };
+    }
+    const typed = error;
+    return {
+        code: typeof typed.code === 'string' ? typed.code : fallback.code,
+        message: typeof typed.message === 'string' ? typed.message : `HTTP ${status} project identity registration failed`,
+        upgradeAction: typeof typed.upgrade_action === 'string' ? typed.upgrade_action : fallback.upgradeAction,
+    };
+}
 //# sourceMappingURL=client.js.map