@agimon-ai/po-artifact 0.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# Po Artifacts
+
+Always-loaded session artifact storage and web/native views.
+
+Each session owns a durable folder under the configured Po agent directory:
+`doom-artifacts/<session-id>/`. The agent's system prompt names that folder for
+user-designated artifacts and important deliverable documents. Ordinary source
+edits stay in the project.
+
+The Artifacts activity section shows the three most recently modified files.
+Its heading opens every artifact in the current session as a grid. Files open
+read-only, using artifact-scoped authenticated reads. Nested regular files are
+included; symlinks are not followed. Artifacts are not deleted on session disposal.
+
+Text previews are limited to 1 MiB, raw downloads to 25 MiB, and native in-memory
+media/downloads to 5 MiB. Secure filesystem reads use macOS no-follow-all semantics
+or Linux descriptor-relative traversal through `/proc/self/fd`. Other server
+platforms fail closed rather than permit ancestor-symlink races.

package/dist/apiContracts.cjs

@@ -0,0 +1,112 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let _agimon_ai_po_core_apiContracts = require("@agimon-ai/po-core/apiContracts");
+let typebox = require("typebox");
+//#region src/schemas/apiContracts.ts
+const S = typebox.Type.String();
+const N = typebox.Type.Number();
+const ArtifactsPayloadSchema = typebox.Type.Object({
+	items: typebox.Type.Array(typebox.Type.Object({
+		path: S,
+		name: S,
+		size: N,
+		modifiedAt: N
+	})),
+	error: typebox.Type.Optional(S)
+});
+const query = [{
+	name: "path",
+	in: "query",
+	required: true,
+	schema: typebox.Type.String({ minLength: 1 })
+}];
+const apiContracts = (0, _agimon_ai_po_core_apiContracts.defineApiContract)({
+	version: 1,
+	dynamic: [],
+	http: [
+		{
+			id: "artifacts.list",
+			scope: "session",
+			basePath: "artifacts",
+			path: "/",
+			method: "GET",
+			authentication: "owner",
+			description: "List regular artifacts in the current session folder by modification time.",
+			responses: (0, _agimon_ai_po_core_apiContracts.jsonApiResponses)(ArtifactsPayloadSchema)
+		},
+		{
+			id: "artifacts.preview",
+			scope: "session",
+			basePath: "artifacts",
+			path: "/preview",
+			method: "GET",
+			authentication: "owner",
+			description: "Read bounded text preview from the current session artifact folder.",
+			parameters: query,
+			responses: (0, _agimon_ai_po_core_apiContracts.jsonApiResponses)(typebox.Type.Object({
+				path: S,
+				content: S,
+				mimeType: S,
+				unavailable: typebox.Type.Optional(typebox.Type.Boolean()),
+				reason: typebox.Type.Optional(S)
+			}))
+		},
+		{
+			id: "artifacts.content",
+			scope: "session",
+			basePath: "artifacts",
+			path: "/content",
+			method: "GET",
+			authentication: "owner",
+			description: "Read bounded artifact bytes, with range and version checks.",
+			parameters: [
+				...query,
+				{
+					name: "Range",
+					in: "header",
+					required: false,
+					schema: S
+				},
+				{
+					name: "If-Match",
+					in: "header",
+					required: false,
+					schema: S
+				}
+			],
+			responses: {
+				"200": {
+					description: "Artifact bytes.",
+					contentType: "application/octet-stream"
+				},
+				"206": {
+					description: "Artifact byte range.",
+					contentType: "application/octet-stream"
+				},
+				"400": { description: "Invalid artifact path." },
+				"403": { description: "Artifact access rejected." },
+				"404": { description: "Artifact missing." },
+				"412": { description: "Artifact changed." },
+				"413": { description: "Artifact too large." },
+				"416": { description: "Invalid byte range." }
+			}
+		}
+	],
+	sockets: ["global", "workspace"].map((scope) => ({
+		id: "artifacts.channel",
+		scope,
+		service: "po.hub.v1",
+		member: "artifacts",
+		kind: "channel",
+		direction: "server-to-client",
+		description: "Current-session artifact metadata in the hub frame payload.",
+		input: ArtifactsPayloadSchema
+	}))
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["Type","defineApiContract","jsonApiResponses"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract, jsonApiResponses } from '@agimon-ai/po-core/apiContracts';\nimport { Type } from 'typebox';\n\nconst S = Type.String();\nconst N = Type.Number();\nexport const ArtifactsPayloadSchema = Type.Object({\n  items: Type.Array(Type.Object({ path: S, name: S, size: N, modifiedAt: N })),\n  error: Type.Optional(S),\n});\nconst query = [{ name: 'path', in: 'query' as const, required: true, schema: Type.String({ minLength: 1 }) }];\nexport const apiContracts = defineApiContract({\n  version: 1,\n  dynamic: [],\n  http: [\n    {\n      id: 'artifacts.list',\n      scope: 'session',\n      basePath: 'artifacts',\n      path: '/',\n      method: 'GET',\n      authentication: 'owner',\n      description: 'List regular artifacts in the current session folder by modification time.',\n      responses: jsonApiResponses(ArtifactsPayloadSchema),\n    },\n    {\n      id: 'artifacts.preview',\n      scope: 'session',\n      basePath: 'artifacts',\n      path: '/preview',\n      method: 'GET',\n      authentication: 'owner',\n      description: 'Read bounded text preview from the current session artifact folder.',\n      parameters: query,\n      responses: jsonApiResponses(\n        Type.Object({\n          path: S,\n          content: S,\n          mimeType: S,\n          unavailable: Type.Optional(Type.Boolean()),\n          reason: Type.Optional(S),\n        }),\n      ),\n    },\n    {\n      id: 'artifacts.content',\n      scope: 'session',\n      basePath: 'artifacts',\n      path: '/content',\n      method: 'GET',\n      authentication: 'owner',\n      description: 'Read bounded artifact bytes, with range and version checks.',\n      parameters: [\n        ...query,\n        { name: 'Range', in: 'header', required: false, schema: S },\n        { name: 'If-Match', in: 'header', required: false, schema: S },\n      ],\n      responses: {\n        '200': { description: 'Artifact bytes.', contentType: 'application/octet-stream' },\n        '206': { description: 'Artifact byte range.', contentType: 'application/octet-stream' },\n        '400': { description: 'Invalid artifact path.' },\n        '403': { description: 'Artifact access rejected.' },\n        '404': { description: 'Artifact missing.' },\n        '412': { description: 'Artifact changed.' },\n        '413': { description: 'Artifact too large.' },\n        '416': { description: 'Invalid byte range.' },\n      },\n    },\n  ],\n  sockets: (['global', 'workspace'] as const).map((scope) => ({\n    id: 'artifacts.channel',\n    scope,\n    service: 'po.hub.v1',\n    member: 'artifacts',\n    kind: 'channel',\n    direction: 'server-to-client',\n    description: 'Current-session artifact metadata in the hub frame payload.',\n    input: ArtifactsPayloadSchema,\n  })),\n});\nexport default apiContracts;\n"],"mappings":";;;;;;;AAGA,MAAM,IAAIA,QAAAA,KAAK,OAAO;AACtB,MAAM,IAAIA,QAAAA,KAAK,OAAO;AACtB,MAAa,yBAAyBA,QAAAA,KAAK,OAAO;CAChD,OAAOA,QAAAA,KAAK,MAAMA,QAAAA,KAAK,OAAO;EAAE,MAAM;EAAG,MAAM;EAAG,MAAM;EAAG,YAAY;CAAE,CAAC,CAAC;CAC3E,OAAOA,QAAAA,KAAK,SAAS,CAAC;AACxB,CAAC;AACD,MAAM,QAAQ,CAAC;CAAE,MAAM;CAAQ,IAAI;CAAkB,UAAU;CAAM,QAAQA,QAAAA,KAAK,OAAO,EAAE,WAAW,EAAE,CAAC;AAAE,CAAC;AAC5G,MAAa,gBAAA,GAAeC,gCAAAA,kBAAAA,CAAkB;CAC5C,SAAS;CACT,SAAS,CAAC;CACV,MAAM;EACJ;GACE,IAAI;GACJ,OAAO;GACP,UAAU;GACV,MAAM;GACN,QAAQ;GACR,gBAAgB;GAChB,aAAa;GACb,YAAA,GAAWC,gCAAAA,iBAAAA,CAAiB,sBAAsB;EACpD;EACA;GACE,IAAI;GACJ,OAAO;GACP,UAAU;GACV,MAAM;GACN,QAAQ;GACR,gBAAgB;GAChB,aAAa;GACb,YAAY;GACZ,YAAA,GAAWA,gCAAAA,iBAAAA,CACTF,QAAAA,KAAK,OAAO;IACV,MAAM;IACN,SAAS;IACT,UAAU;IACV,aAAaA,QAAAA,KAAK,SAASA,QAAAA,KAAK,QAAQ,CAAC;IACzC,QAAQA,QAAAA,KAAK,SAAS,CAAC;GACzB,CAAC,CACH;EACF;EACA;GACE,IAAI;GACJ,OAAO;GACP,UAAU;GACV,MAAM;GACN,QAAQ;GACR,gBAAgB;GAChB,aAAa;GACb,YAAY;IACV,GAAG;IACH;KAAE,MAAM;KAAS,IAAI;KAAU,UAAU;KAAO,QAAQ;IAAE;IAC1D;KAAE,MAAM;KAAY,IAAI;KAAU,UAAU;KAAO,QAAQ;IAAE;GAC/D;GACA,WAAW;IACT,OAAO;KAAE,aAAa;KAAmB,aAAa;IAA2B;IACjF,OAAO;KAAE,aAAa;KAAwB,aAAa;IAA2B;IACtF,OAAO,EAAE,aAAa,yBAAyB;IAC/C,OAAO,EAAE,aAAa,4BAA4B;IAClD,OAAO,EAAE,aAAa,oBAAoB;IAC1C,OAAO,EAAE,aAAa,oBAAoB;IAC1C,OAAO,EAAE,aAAa,sBAAsB;IAC5C,OAAO,EAAE,aAAa,sBAAsB;GAC9C;EACF;CACF;CACA,SAAU,CAAC,UAAU,WAAW,CAAC,CAAW,KAAK,WAAW;EAC1D,IAAI;EACJ;EACA,SAAS;EACT,QAAQ;EACR,MAAM;EACN,WAAW;EACX,aAAa;EACb,OAAO;CACT,EAAE;AACJ,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+import { Type } from "typebox";
+//#region src/schemas/apiContracts.d.ts
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAUa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,107 @@
+import { defineApiContract, jsonApiResponses } from "@agimon-ai/po-core/apiContracts";
+import { Type } from "typebox";
+//#region src/schemas/apiContracts.ts
+const S = Type.String();
+const N = Type.Number();
+const ArtifactsPayloadSchema = Type.Object({
+	items: Type.Array(Type.Object({
+		path: S,
+		name: S,
+		size: N,
+		modifiedAt: N
+	})),
+	error: Type.Optional(S)
+});
+const query = [{
+	name: "path",
+	in: "query",
+	required: true,
+	schema: Type.String({ minLength: 1 })
+}];
+const apiContracts = defineApiContract({
+	version: 1,
+	dynamic: [],
+	http: [
+		{
+			id: "artifacts.list",
+			scope: "session",
+			basePath: "artifacts",
+			path: "/",
+			method: "GET",
+			authentication: "owner",
+			description: "List regular artifacts in the current session folder by modification time.",
+			responses: jsonApiResponses(ArtifactsPayloadSchema)
+		},
+		{
+			id: "artifacts.preview",
+			scope: "session",
+			basePath: "artifacts",
+			path: "/preview",
+			method: "GET",
+			authentication: "owner",
+			description: "Read bounded text preview from the current session artifact folder.",
+			parameters: query,
+			responses: jsonApiResponses(Type.Object({
+				path: S,
+				content: S,
+				mimeType: S,
+				unavailable: Type.Optional(Type.Boolean()),
+				reason: Type.Optional(S)
+			}))
+		},
+		{
+			id: "artifacts.content",
+			scope: "session",
+			basePath: "artifacts",
+			path: "/content",
+			method: "GET",
+			authentication: "owner",
+			description: "Read bounded artifact bytes, with range and version checks.",
+			parameters: [
+				...query,
+				{
+					name: "Range",
+					in: "header",
+					required: false,
+					schema: S
+				},
+				{
+					name: "If-Match",
+					in: "header",
+					required: false,
+					schema: S
+				}
+			],
+			responses: {
+				"200": {
+					description: "Artifact bytes.",
+					contentType: "application/octet-stream"
+				},
+				"206": {
+					description: "Artifact byte range.",
+					contentType: "application/octet-stream"
+				},
+				"400": { description: "Invalid artifact path." },
+				"403": { description: "Artifact access rejected." },
+				"404": { description: "Artifact missing." },
+				"412": { description: "Artifact changed." },
+				"413": { description: "Artifact too large." },
+				"416": { description: "Invalid byte range." }
+			}
+		}
+	],
+	sockets: ["global", "workspace"].map((scope) => ({
+		id: "artifacts.channel",
+		scope,
+		service: "po.hub.v1",
+		member: "artifacts",
+		kind: "channel",
+		direction: "server-to-client",
+		description: "Current-session artifact metadata in the hub frame payload.",
+		input: ArtifactsPayloadSchema
+	}))
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract, jsonApiResponses } from '@agimon-ai/po-core/apiContracts';\nimport { Type } from 'typebox';\n\nconst S = Type.String();\nconst N = Type.Number();\nexport const ArtifactsPayloadSchema = Type.Object({\n  items: Type.Array(Type.Object({ path: S, name: S, size: N, modifiedAt: N })),\n  error: Type.Optional(S),\n});\nconst query = [{ name: 'path', in: 'query' as const, required: true, schema: Type.String({ minLength: 1 }) }];\nexport const apiContracts = defineApiContract({\n  version: 1,\n  dynamic: [],\n  http: [\n    {\n      id: 'artifacts.list',\n      scope: 'session',\n      basePath: 'artifacts',\n      path: '/',\n      method: 'GET',\n      authentication: 'owner',\n      description: 'List regular artifacts in the current session folder by modification time.',\n      responses: jsonApiResponses(ArtifactsPayloadSchema),\n    },\n    {\n      id: 'artifacts.preview',\n      scope: 'session',\n      basePath: 'artifacts',\n      path: '/preview',\n      method: 'GET',\n      authentication: 'owner',\n      description: 'Read bounded text preview from the current session artifact folder.',\n      parameters: query,\n      responses: jsonApiResponses(\n        Type.Object({\n          path: S,\n          content: S,\n          mimeType: S,\n          unavailable: Type.Optional(Type.Boolean()),\n          reason: Type.Optional(S),\n        }),\n      ),\n    },\n    {\n      id: 'artifacts.content',\n      scope: 'session',\n      basePath: 'artifacts',\n      path: '/content',\n      method: 'GET',\n      authentication: 'owner',\n      description: 'Read bounded artifact bytes, with range and version checks.',\n      parameters: [\n        ...query,\n        { name: 'Range', in: 'header', required: false, schema: S },\n        { name: 'If-Match', in: 'header', required: false, schema: S },\n      ],\n      responses: {\n        '200': { description: 'Artifact bytes.', contentType: 'application/octet-stream' },\n        '206': { description: 'Artifact byte range.', contentType: 'application/octet-stream' },\n        '400': { description: 'Invalid artifact path.' },\n        '403': { description: 'Artifact access rejected.' },\n        '404': { description: 'Artifact missing.' },\n        '412': { description: 'Artifact changed.' },\n        '413': { description: 'Artifact too large.' },\n        '416': { description: 'Invalid byte range.' },\n      },\n    },\n  ],\n  sockets: (['global', 'workspace'] as const).map((scope) => ({\n    id: 'artifacts.channel',\n    scope,\n    service: 'po.hub.v1',\n    member: 'artifacts',\n    kind: 'channel',\n    direction: 'server-to-client',\n    description: 'Current-session artifact metadata in the hub frame payload.',\n    input: ArtifactsPayloadSchema,\n  })),\n});\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAM,IAAI,KAAK,OAAO;AACtB,MAAM,IAAI,KAAK,OAAO;AACtB,MAAa,yBAAyB,KAAK,OAAO;CAChD,OAAO,KAAK,MAAM,KAAK,OAAO;EAAE,MAAM;EAAG,MAAM;EAAG,MAAM;EAAG,YAAY;CAAE,CAAC,CAAC;CAC3E,OAAO,KAAK,SAAS,CAAC;AACxB,CAAC;AACD,MAAM,QAAQ,CAAC;CAAE,MAAM;CAAQ,IAAI;CAAkB,UAAU;CAAM,QAAQ,KAAK,OAAO,EAAE,WAAW,EAAE,CAAC;AAAE,CAAC;AAC5G,MAAa,eAAe,kBAAkB;CAC5C,SAAS;CACT,SAAS,CAAC;CACV,MAAM;EACJ;GACE,IAAI;GACJ,OAAO;GACP,UAAU;GACV,MAAM;GACN,QAAQ;GACR,gBAAgB;GAChB,aAAa;GACb,WAAW,iBAAiB,sBAAsB;EACpD;EACA;GACE,IAAI;GACJ,OAAO;GACP,UAAU;GACV,MAAM;GACN,QAAQ;GACR,gBAAgB;GAChB,aAAa;GACb,YAAY;GACZ,WAAW,iBACT,KAAK,OAAO;IACV,MAAM;IACN,SAAS;IACT,UAAU;IACV,aAAa,KAAK,SAAS,KAAK,QAAQ,CAAC;IACzC,QAAQ,KAAK,SAAS,CAAC;GACzB,CAAC,CACH;EACF;EACA;GACE,IAAI;GACJ,OAAO;GACP,UAAU;GACV,MAAM;GACN,QAAQ;GACR,gBAAgB;GAChB,aAAa;GACb,YAAY;IACV,GAAG;IACH;KAAE,MAAM;KAAS,IAAI;KAAU,UAAU;KAAO,QAAQ;IAAE;IAC1D;KAAE,MAAM;KAAY,IAAI;KAAU,UAAU;KAAO,QAAQ;IAAE;GAC/D;GACA,WAAW;IACT,OAAO;KAAE,aAAa;KAAmB,aAAa;IAA2B;IACjF,OAAO;KAAE,aAAa;KAAwB,aAAa;IAA2B;IACtF,OAAO,EAAE,aAAa,yBAAyB;IAC/C,OAAO,EAAE,aAAa,4BAA4B;IAClD,OAAO,EAAE,aAAa,oBAAoB;IAC1C,OAAO,EAAE,aAAa,oBAAoB;IAC1C,OAAO,EAAE,aAAa,sBAAsB;IAC5C,OAAO,EAAE,aAAa,sBAAsB;GAC9C;EACF;CACF;CACA,SAAU,CAAC,UAAU,WAAW,CAAC,CAAW,KAAK,WAAW;EAC1D,IAAI;EACJ;EACA,SAAS;EACT,QAAQ;EACR,MAAM;EACN,WAAW;EACX,aAAa;EACb,OAAO;CACT,EAAE;AACJ,CAAC"}