{"record":{"id":"d127645b915994c3","repo":"earendil-works/pi","slug":"agentharness-create-restore-is-not-implemented-yet","errorCode":null,"errorMessage":"AgentHarness.create.restore is not implemented yet","messagePattern":"AgentHarness\\.create\\.restore is not implemented yet","errorType":"exception","errorClass":"HarnessNotImplemented","httpStatus":null,"severity":"error","filePath":"packages/agent/src/harness/agent-harness.ts","lineNumber":351,"sourceCode":"\t\t\tskills: options.resources?.skills ? [...options.resources.skills] : undefined,\n\t\t\tpromptTemplates: options.resources?.promptTemplates ? [...options.resources.promptTemplates] : undefined,\n\t\t};\n\t\tthis.streamOptions = { ...(options.streamOptions ?? {}) };\n\t\tthis.retryPolicy = options.retry ?? { enabled: false, maxRetries: 0, baseDelayMs: 1000 };\n\t\tthis.compactionSettings = options.compaction ?? {\n\t\t\tenabled: true,\n\t\t\treserveTokens: 16384,\n\t\t\tkeepRecentTokens: 20000,\n\t\t};\n\t\tthis.steeringMode = options.steeringMode ?? \"one-at-a-time\";\n\t\tthis.followUpMode = options.followUpMode ?? \"one-at-a-time\";\n\t}\n\n\tstatic async create(\n\t\toptions: AgentHarnessOptions,\n\t): Promise<{ harness: AgentHarness; suspended: SuspendedOperation[] }> {\n\t\tconst [record] = await options.session.findRecords({ limit: 1 });\n\t\tif (record !== undefined) throw new HarnessNotImplemented(\"create.restore\");\n\t\treturn { harness: new AgentHarness(options), suspended: [] };\n\t}\n\n\tprivate unavailable<T>(operation: string): Promise<T> {\n\t\treturn Promise.reject(this.closed ? new HarnessClosed() : new HarnessNotImplemented(operation));\n\t}\n\n\tasync getLeafId(): Promise<string | null> {\n\t\treturn this.durableSession.getLeafId();\n\t}\n\n\tasync prompt(_text: string, _images?: ImageContent[]): Promise<RunResult>;\n\tasync prompt(_message: AgentMessage | AgentMessage[]): Promise<RunResult>;\n\tasync prompt(_input: string | AgentMessage | AgentMessage[], _images?: ImageContent[]): Promise<RunResult> {\n\t\treturn this.unavailable(\"prompt\");\n\t}\n\tasync skill(_name: string, _additionalInstructions?: string): Promise<RunResult> {\n\t\treturn this.unavailable(\"skill\");","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/earendil-works/pi/blob/4af9d21d3b4d664e4a29fcabfec85171077248e3/packages/agent/src/harness/agent-harness.ts#L333-L369","documentation":"AgentHarness.create() builds a harness over a SessionTree, but restoring an existing session is not implemented yet: if options.session.findRecords({ limit: 1 }) returns any record, create rejects with HarnessNotImplemented('create.restore') instead of resuming. The harness is a work-in-progress surface where most operations similarly reject with HarnessNotImplemented, so create only succeeds on a fresh, empty session. The error class carries an `operation` field ('create.restore') for precise handling.","triggerScenarios":"Passing a durable Session that already contains records (a previously used or persisted session tree) to AgentHarness.create(); reopening a session store on app restart and expecting resume; pointing AgentHarnessOptions.session at a shared or populated store.","commonSituations":"Apps that persist sessions and call create() on every startup; test fixtures reusing a session directory; upgrading to a harness version where restore simply has not shipped yet.","solutions":["Pass a brand-new, empty Session/SessionTree so findRecords returns nothing.","Pre-check options.session.findRecords({ limit: 1 }) yourself and fail with your own error before calling create.","Until create.restore ships, use the Agent class directly for resumable conversations and treat the harness as experimental (its prompt/steer/watch/etc. also reject with HarnessNotImplemented)."],"exampleFix":"// before\nconst { harness } = await AgentHarness.create({ session: existingSession }); // has records -> HarnessNotImplemented\n\n// after\nconst [record] = await existingSession.findRecords({ limit: 1 });\nif (record !== undefined) throw new Error(\"session restore not supported by this harness version\");\nconst { harness } = await AgentHarness.create({ session: freshEmptySession });","handlingStrategy":"try-catch","validationCode":"const [record] = await options.session.findRecords({ limit: 1 });\nif (record !== undefined) {\n  // restore is unimplemented: use a fresh session instead\n  throw new Error(\"session has records; harness restore not implemented\");\n}\nconst { harness } = await AgentHarness.create(options);","typeGuard":"function isHarnessNotImplemented(err: unknown, operation?: string): err is HarnessNotImplemented {\n  return err instanceof HarnessNotImplemented && (operation === undefined || err.operation === operation);\n}","tryCatchPattern":"try {\n  const { harness, suspended } = await AgentHarness.create(options);\n} catch (err) {\n  if (err instanceof HarnessNotImplemented && err.operation === \"create.restore\") {\n    // fall back: create a fresh session, or use the Agent class directly\n  } else {\n    throw err;\n  }\n}","preventionTips":["Only pass freshly created, empty sessions to AgentHarness.create in this version.","Pre-check session.findRecords({ limit: 1 }) to fail with your own error message.","Expect other harness methods (prompt, steer, watch, ...) to reject with HarnessNotImplemented too - treat the harness as experimental."],"tags":["harness","not-implemented","session-restore","wip"],"backgroundTag":"not-implemented-feature","analyzedSha":"4af9d21d3b4d664e4a29fcabfec85171077248e3","analyzedAt":"2026-08-24T13:07:14.692Z","schemaVersion":2},"datasetVersion":"2026-08-24T17:17:21.512Z"}