@asc-agent/runtime 0.1.0 → 0.2.1

package/dist/core/resolver/profile-source.d.ts

@@ -0,0 +1,29 @@
+export type ProfileOrigin = 'built-in' | 'external';
+export type ProfileLocation = {
+    id: string;
+    origin: ProfileOrigin;
+    /** `profile.json` 의 절대 경로. 파일이 아직 없을 수도 있다 — 읽는 쪽이 그 사실을 만난다. */
+    path: string;
+};
+export type ProfileRoots = {
+    /** 설치된 배포본의 뿌리. `profiles/` 가 그 아래 있다. */
+    installRoot: string;
+    /** 사용자 소유 Profile 디렉터리. 보통 `ASC_HOME/profiles`. 없으면 external은 없는 것이다. */
+    externalRoot?: string;
+};
+/** 왜 Profile을 고르지 못했는가. 문장이 아니라 코드로 든다 — Surface가 다르게 말해야 한다. */
+export type ProfileSourceCode = 'INVALID_PROFILE_ID' | 'PROFILE_COLLISION' | 'PROFILE_ESCAPES_ROOT' | 'PROFILE_ID_MISMATCH';
+export declare class ProfileSourceError extends Error {
+    code: ProfileSourceCode;
+    constructor(code: ProfileSourceCode, message: string);
+}
+export declare function assertProfileId(id: string): void;
+/** 이 뿌리들 아래에 실제로 있는 Profile 전부. external이 먼저 온다. */
+export declare function listProfileLocations(roots: ProfileRoots): Promise<ProfileLocation[]>;
+/**
+ * 이 id의 Profile은 어디 있는가.
+ *
+ * 아무 데도 없으면 **built-in 자리를 돌려준다** — 파일이 없다는 사실은 읽는 쪽에서
+ * 그대로 드러나야 하고, 그 오류 모양은 v0.1과 같아야 한다.
+ */
+export declare function resolveProfileLocation(id: string, roots: ProfileRoots): Promise<ProfileLocation>;

package/dist/core/resolver/profile-source.js

@@ -0,0 +1,139 @@
+// Profile이 어디서 오는가 — 설치된 배포본 안, 그리고 사용자 소유 공간.
+//
+// v0.1까지 Profile은 **설치 경로 안에만** 있었다. 그래서 공개 패키지를 설치한 사람은
+// 자기 프로젝트의 Profile을 쓸 방법이 없었다 — 팀에 배포할 수 없다는 뜻이다.
+// 여기서 여는 것은 그 한 갈래다: `ASC_HOME/profiles/<id>/profile.json`.
+//
+// 자리를 고르는 규칙이 이 파일의 전부다:
+//   1. 사람이 명시한 것            Surface가 이미 id로 넘긴다
+//   2. 사용자 소유 external        ASC_HOME — 팀이 나눠 갖는 실 Profile이 여기 온다
+//   3. 배포본 내장 built-in        예시·fixture. 아무것도 없을 때의 바닥
+//
+// **같은 id가 양쪽에 있으면 멈춘다.** 조용히 하나를 고르면 "무엇을 읽었는가"를 사람이
+// 알 수 없고, 그 답이 정책이 되므로 틀린 쪽으로 조용히 도는 것보다 서는 편이 낫다.
+//
+// Profile은 코드가 아니라 데이터다. 여기서 하는 일은 **경로를 고르는 것뿐**이고,
+// 읽기·검증·digest는 기존 resolver 계약(load.ts)이 그대로 한다.
+import { constants } from 'node:fs';
+import { access, readdir, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+export class ProfileSourceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ProfileSourceError';
+        this.code = code;
+    }
+}
+/**
+ * Profile id는 **디렉터리 이름 한 칸**이다.
+ *
+ * 경로 조각을 허용하면 id 하나로 `profiles/` 밖의 파일을 읽게 된다 — `../../secrets`
+ * 같은 것. 그래서 여기서 문법으로 막고, 아래에서 실제 경로가 뿌리 안에 있는지 한 번 더 본다
+ * (문법만 믿지 않는다 — symlink는 문법을 통과한다).
+ */
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function assertProfileId(id) {
+    if (!SAFE_ID.test(id) || id === '.' || id === '..') {
+        throw new ProfileSourceError('INVALID_PROFILE_ID', `'${id}' is not a profile id — use a single name made of letters, digits, '.', '_' or '-'`);
+    }
+}
+/** 글자만 보고 판단한다. 첫 번째 자물쇠 — symlink·junction은 여기를 그냥 통과한다. */
+function withinLexically(root, target) {
+    const rel = relative(resolve(root), resolve(target));
+    return rel !== '' && !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel);
+}
+/**
+ * **실제로** 그 뿌리 안인가. 두 번째 자물쇠다.
+ *
+ * 글자 검사만으로는 부족하다는 것을 독립 검증이 실물로 보였다 — Windows junction
+ * (`mklink /J`)이나 symlink를 `profiles/` 안에 만들면 이름은 한 칸이고 경로도 뿌리 안처럼
+ * 보이는데, 실제 파일은 바깥에 있다. 그 파일이 프로젝트의 정책이 되면 lock에 적히는
+ * 출처마저 link 경로라 사람이 진짜 자리를 알 수 없다.
+ *
+ * 그래서 존재하는 것은 realpath로 한 번 더 본다. 없는 경로는 판정 대상이 아니다.
+ */
+async function withinReally(root, target) {
+    try {
+        const [realRoot, realTarget] = await Promise.all([realpath(root), realpath(target)]);
+        return withinLexically(realRoot, realTarget);
+    }
+    catch {
+        // 아직 없는 파일이면 글자 판단만으로 충분하다 — 읽는 쪽에서 없다는 사실을 만난다.
+        return withinLexically(root, target);
+    }
+}
+const profilePath = (root, id) => join(root, id, 'profile.json');
+const exists = async (path) => {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** 이 뿌리들 아래에 실제로 있는 Profile 전부. external이 먼저 온다. */
+export async function listProfileLocations(roots) {
+    const found = [];
+    const dirs = [
+        ['external', roots.externalRoot],
+        ['built-in', join(roots.installRoot, 'profiles')],
+    ];
+    for (const [origin, dir] of dirs) {
+        if (!dir)
+            continue;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // 없는 디렉터리는 "Profile 0개"다. 오류가 아니다.
+        }
+        for (const entry of entries) {
+            // junction·symlink는 Windows에서 `isDirectory()` 가 아니다. 목록에서만 빼면
+            // "후보에는 없는데 --profile 로는 붙는" 상태가 되므로 여기서도 같이 본다 —
+            // 발견과 해석이 다른 답을 하면 사람은 둘 다 못 믿는다.
+            if (!entry.isDirectory() && !entry.isSymbolicLink())
+                continue;
+            if (!SAFE_ID.test(entry.name))
+                continue; // 이름이 문법 밖이면 고를 수 없는 것이다
+            const path = profilePath(dir, entry.name);
+            if (!(await withinReally(dir, path)))
+                continue;
+            if (await exists(path))
+                found.push({ id: entry.name, origin, path });
+        }
+    }
+    return found;
+}
+/**
+ * 이 id의 Profile은 어디 있는가.
+ *
+ * 아무 데도 없으면 **built-in 자리를 돌려준다** — 파일이 없다는 사실은 읽는 쪽에서
+ * 그대로 드러나야 하고, 그 오류 모양은 v0.1과 같아야 한다.
+ */
+export async function resolveProfileLocation(id, roots) {
+    assertProfileId(id);
+    const builtInDir = join(roots.installRoot, 'profiles');
+    const builtIn = profilePath(builtInDir, id);
+    const externalDir = roots.externalRoot;
+    const external = externalDir ? profilePath(externalDir, id) : undefined;
+    if (external && !withinLexically(externalDir, external)) {
+        throw new ProfileSourceError('INVALID_PROFILE_ID', `'${id}' escapes the profile directory`);
+    }
+    const hasExternal = external ? await exists(external) : false;
+    if (external && hasExternal && !(await withinReally(externalDir, external))) {
+        throw new ProfileSourceError('PROFILE_ESCAPES_ROOT', `'${id}' points outside ${externalDir} — a link leads to another place on disk. ` +
+            'Put the profile itself in the directory: policy must not come from somewhere the ' +
+            'recorded source does not name.');
+    }
+    const hasBuiltIn = await exists(builtIn);
+    if (hasExternal && hasBuiltIn) {
+        throw new ProfileSourceError('PROFILE_COLLISION', `two profiles claim the id '${id}' — ${external} and ${builtIn}. ` +
+            'Rename one of them: which policy applies must not depend on lookup order.');
+    }
+    if (hasExternal)
+        return { id, origin: 'external', path: external };
+    return { id, origin: 'built-in', path: builtIn };
+}

package/dist/core/workspace/identity.d.ts

@@ -32,15 +32,15 @@ export declare const Workspace: z.ZodObject<{
     createdAt: z.ZodString;
     lastSeenAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    lastSeenAt: string;
     workspaceId: string;
     aliases: string[];
     adoptionScope: "local" | "project";
     createdAt: string;
-}, {
     lastSeenAt: string;
+}, {
     workspaceId: string;
     createdAt: string;
+    lastSeenAt: string;
     aliases?: string[] | undefined;
     adoptionScope?: "local" | "project" | undefined;
 }>;

package/dist/core/workspace/index-store.d.ts

@@ -10,15 +10,15 @@ declare const LocatorEntry: z.ZodObject<{
     observedAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     observedAt: string;
-    root: string;
     platform: string;
     workspaceId: string;
+    root: string;
     kind?: "checkout" | "worktree" | undefined;
 }, {
     observedAt: string;
-    root: string;
     platform: string;
     workspaceId: string;
+    root: string;
     kind?: "checkout" | "worktree" | undefined;
 }>;
 export type LocatorEntry = z.infer<typeof LocatorEntry>;
@@ -31,15 +31,15 @@ export declare const WorkspaceIndex: z.ZodObject<{
         createdAt: z.ZodString;
         lastSeenAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        lastSeenAt: string;
         workspaceId: string;
         aliases: string[];
         adoptionScope: "local" | "project";
         createdAt: string;
-    }, {
         lastSeenAt: string;
+    }, {
         workspaceId: string;
         createdAt: string;
+        lastSeenAt: string;
         aliases?: string[] | undefined;
         adoptionScope?: "local" | "project" | undefined;
     }>>>;
@@ -53,47 +53,47 @@ export declare const WorkspaceIndex: z.ZodObject<{
         observedAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         observedAt: string;
-        root: string;
         platform: string;
         workspaceId: string;
+        root: string;
         kind?: "checkout" | "worktree" | undefined;
     }, {
         observedAt: string;
-        root: string;
         platform: string;
         workspaceId: string;
+        root: string;
         kind?: "checkout" | "worktree" | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
     version: 1;
     workspaces: Record<string, {
-        lastSeenAt: string;
         workspaceId: string;
         aliases: string[];
         adoptionScope: "local" | "project";
         createdAt: string;
+        lastSeenAt: string;
     }>;
     locators: Record<string, {
         observedAt: string;
-        root: string;
         platform: string;
         workspaceId: string;
+        root: string;
         kind?: "checkout" | "worktree" | undefined;
     }>;
 }, {
     version: 1;
     workspaces?: Record<string, {
-        lastSeenAt: string;
         workspaceId: string;
         createdAt: string;
+        lastSeenAt: string;
         aliases?: string[] | undefined;
         adoptionScope?: "local" | "project" | undefined;
     }> | undefined;
     locators?: Record<string, {
         observedAt: string;
-        root: string;
         platform: string;
         workspaceId: string;
+        root: string;
         kind?: "checkout" | "worktree" | undefined;
     }> | undefined;
 }>;

package/dist/schemas/profile.d.ts

@@ -11,16 +11,16 @@ export declare const CanonicalSourceSpec: z.ZodObject<{
     id: string;
     paths: string[];
     provider: "git" | "github";
+    $comment?: string | undefined;
     remote?: string | undefined;
     ref?: string | undefined;
-    $comment?: string | undefined;
 }, {
     id: string;
     provider: "git" | "github";
     paths?: string[] | undefined;
+    $comment?: string | undefined;
     remote?: string | undefined;
     ref?: string | undefined;
-    $comment?: string | undefined;
 }>;
 export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, unknown, unknown>, z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
@@ -63,34 +63,34 @@ export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, un
             id: string;
             paths: string[];
             provider: "git" | "github";
+            $comment?: string | undefined;
             remote?: string | undefined;
             ref?: string | undefined;
-            $comment?: string | undefined;
         }, {
             id: string;
             provider: "git" | "github";
             paths?: string[] | undefined;
+            $comment?: string | undefined;
             remote?: string | undefined;
             ref?: string | undefined;
-            $comment?: string | undefined;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         sources: {
             id: string;
             paths: string[];
             provider: "git" | "github";
+            $comment?: string | undefined;
             remote?: string | undefined;
             ref?: string | undefined;
-            $comment?: string | undefined;
         }[];
     }, {
         sources?: {
             id: string;
             provider: "git" | "github";
             paths?: string[] | undefined;
+            $comment?: string | undefined;
             remote?: string | undefined;
             ref?: string | undefined;
-            $comment?: string | undefined;
         }[] | undefined;
     }>>;
     monitor: z.ZodDefault<z.ZodObject<{
@@ -242,20 +242,21 @@ export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, un
         capabilities: string[];
         asc?: string | undefined;
     };
+    project: {
+        scm: string;
+        repository: string;
+    };
+    schemaVersion: 1;
     canonical: {
         sources: {
             id: string;
             paths: string[];
             provider: "git" | "github";
+            $comment?: string | undefined;
             remote?: string | undefined;
             ref?: string | undefined;
-            $comment?: string | undefined;
         }[];
     };
-    project: {
-        scm: string;
-        repository: string;
-    };
     policy: {
         hardDeny: string[];
         softDeny: string[];
@@ -265,7 +266,6 @@ export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, un
         lockedSettings: string[];
         unionLists?: Record<string, string[]> | undefined;
     };
-    schemaVersion: 1;
     optionalCapabilities: string[];
     workflow: {
         taskSource: string[];
@@ -273,6 +273,7 @@ export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, un
         blockSource?: string | undefined;
     };
     terminology: Record<string, string>;
+    $comment?: string | undefined;
     ownership?: Record<string, {
         paths: string[];
         authorities: string[];
@@ -282,7 +283,6 @@ export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, un
         resource: string;
         adapter: string;
     }[] | undefined;
-    $comment?: string | undefined;
 }, {
     id: string;
     project: {
@@ -301,14 +301,15 @@ export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, un
         capabilities?: string[] | undefined;
         asc?: string | undefined;
     } | undefined;
+    $comment?: string | undefined;
     canonical?: {
         sources?: {
             id: string;
             provider: "git" | "github";
             paths?: string[] | undefined;
+            $comment?: string | undefined;
             remote?: string | undefined;
             ref?: string | undefined;
-            $comment?: string | undefined;
         }[] | undefined;
     } | undefined;
     ownership?: Record<string, {
@@ -329,7 +330,6 @@ export declare const ProjectProfile: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, un
         lockedSettings?: string[] | undefined;
         unionLists?: Record<string, string[]> | undefined;
     } | undefined;
-    $comment?: string | undefined;
     optionalCapabilities?: string[] | undefined;
     workflow?: {
         $comment?: string | undefined;
@@ -371,6 +371,7 @@ export declare const OperationalPreset: z.ZodPipeline<z.ZodEffects<z.ZodUnknown,
     }>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
+    schemaVersion: 1;
     policy: {
         hardDeny?: string[] | undefined;
         softDeny?: string[] | undefined;
@@ -380,11 +381,11 @@ export declare const OperationalPreset: z.ZodPipeline<z.ZodEffects<z.ZodUnknown,
         lockedSettings?: string[] | undefined;
         unionLists?: Record<string, string[]> | undefined;
     };
-    schemaVersion: 1;
     $comment?: string | undefined;
 }, {
     id: string;
     schemaVersion: 1;
+    $comment?: string | undefined;
     policy?: {
         hardDeny?: string[] | undefined;
         softDeny?: string[] | undefined;
@@ -394,7 +395,6 @@ export declare const OperationalPreset: z.ZodPipeline<z.ZodEffects<z.ZodUnknown,
         lockedSettings?: string[] | undefined;
         unionLists?: Record<string, string[]> | undefined;
     } | undefined;
-    $comment?: string | undefined;
 }>>;
 export type OperationalPreset = z.infer<typeof OperationalPreset>;
 /**
@@ -491,6 +491,7 @@ export declare const UserOverride: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, unkn
         realtime?: boolean | undefined;
         roles?: string[] | undefined;
     };
+    schemaVersion: 1;
     approval: {
         preferredChannel?: string | undefined;
         messenger?: {
@@ -507,7 +508,6 @@ export declare const UserOverride: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, unkn
         lockedSettings?: string[] | undefined;
         unionLists?: Record<string, string[]> | undefined;
     };
-    schemaVersion: 1;
     identity: Record<string, string>;
     monitorIdentities: string[];
     $comment?: string | undefined;
@@ -520,6 +520,7 @@ export declare const UserOverride: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, unkn
         realtime?: boolean | undefined;
         roles?: string[] | undefined;
     } | undefined;
+    $comment?: string | undefined;
     approval?: {
         preferredChannel?: string | undefined;
         messenger?: {
@@ -536,7 +537,6 @@ export declare const UserOverride: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, unkn
         lockedSettings?: string[] | undefined;
         unionLists?: Record<string, string[]> | undefined;
     } | undefined;
-    $comment?: string | undefined;
     identity?: Record<string, string> | undefined;
     monitorIdentities?: string[] | undefined;
 }>>;
@@ -586,13 +586,13 @@ export declare const ProfileLock: z.ZodObject<{
     configurationDigest: z.ZodString;
     generatedAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
     profile: {
         id: string;
         source: string;
         digest: string;
     };
     capabilities: string[];
-    schemaVersion: 1;
     ascCore: {
         version: string;
         commit?: string | undefined;
@@ -607,12 +607,12 @@ export declare const ProfileLock: z.ZodObject<{
     } | undefined;
     overrideDigest?: string | undefined;
 }, {
+    schemaVersion: 1;
     profile: {
         id: string;
         source: string;
         digest: string;
     };
-    schemaVersion: 1;
     ascCore: {
         version: string;
         commit?: string | undefined;

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@asc-agent/runtime",
-  "version": "0.1.0",
-  "description": "ASC (Agent Session Control) — local-first human-in-the-loop agent control plane: core, CLI, and adapters",
-  "keywords": [
-    "agent",
-    "control-plane",
-    "human-in-the-loop",
-    "claude-code",
-    "local-first",
-    "session"
-  ],
-  "homepage": "https://github.com/colosair/asc#readme",
-  "bugs": {
-    "url": "https://github.com/colosair/asc/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/colosair/asc.git",
-    "directory": "packages/runtime"
-  },
-  "author": "colosair (https://github.com/colosair)",
-  "type": "module",
-  "bin": {
-    "asc": "./dist/cli/asc.js"
-  },
-  "main": "./dist/cli/asc.js",
-  "types": "./dist/cli/asc.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/cli/asc.d.ts",
-      "default": "./dist/cli/asc.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=24"
-  },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepack": "node scripts/build.mjs",
-    "test": "node --test \"tests/*.test.ts\"",
-    "dist:smoke": "node scripts/dist-smoke.mjs"
-  },
-  "dependencies": {
-    "zod": "^3.25.76"
-  },
-  "license": "ISC",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@asc-agent/runtime",
+  "version": "0.2.1",
+  "description": "ASC (Agent Session Control) — local-first human-in-the-loop agent control plane: core, CLI, and adapters",
+  "keywords": [
+    "agent",
+    "control-plane",
+    "human-in-the-loop",
+    "claude-code",
+    "local-first",
+    "session"
+  ],
+  "homepage": "https://github.com/colosair/asc#readme",
+  "bugs": {
+    "url": "https://github.com/colosair/asc/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/colosair/asc.git",
+    "directory": "packages/runtime"
+  },
+  "author": "colosair (https://github.com/colosair)",
+  "type": "module",
+  "bin": {
+    "asc": "./dist/cli/asc.js"
+  },
+  "main": "./dist/cli/asc.js",
+  "types": "./dist/cli/asc.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cli/asc.d.ts",
+      "default": "./dist/cli/asc.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "test": "node --test \"tests/*.test.ts\"",
+    "dist:smoke": "node scripts/dist-smoke.mjs"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
+}