@salsita-ai/sdk 0.50.0-develop.da8d27f5d7 → 0.50.0-develop.dbf0122072

package/dist/application-spec/generate-application/code/templates/phoenix-feedback-skill.js

@@ -1,31 +0,0 @@
-import{renderAgentSkill as e}from"./common/agent-skill.js";let t=`## When to Raise Feedback
-Draft feedback for the Phoenix team when one of these happens while you work in this project:
-- **Bug** — the SDK, the \`phoenix\` CLI or generated code crashes, produces wrong output or behaves differently from its documentation, and the cause is not in this project's own code.
-- **Misleading guidance** — a doc page, a Phoenix skill or an error message sent you the wrong way, or did not say what you needed.
-- **Missing feature** — something the SDK does not support forced a workaround, or a routine task took far more steps than it should.
-
-Do not draft feedback for problems in this project's own specs or code, for a suspicion you have not checked, or twice for the same problem. Write one draft per distinct problem.`,o=`## Ask Before You Send
-Never send feedback on your own. Show the user a draft and send it only after they approve it.
-
-When to ask is your judgement:
-- **Right away** — the problem is crucial: it blocks the task or forces a workaround the user should know about now. Interrupt the work, show the draft, and continue once the user has answered.
-- **At the end of the task** — everything else. Collect the details while you work and show all drafts together in your final message.
-- **When the user asks** you to send feedback — draft it and show it before sending.
-
-The draft is exactly what would be sent: the type, the message, the project if you name one with \`--projectSlug\`, and the contact if the user gave one. Send it unchanged after a yes; if the user edits it, send their version. If they decline, drop it and do not raise that problem again.`,a=`## Ask for a Rating After a Deploy
-When \`phoenix deploy\` reports that the configurator is live, tell the user the live URL first, then ask them to rate building with Phoenix so far:
-- Ask for a score from 0 to 10, where 10 is the best, and one optional sentence on what would have made it better. Say in the same question that the answer is sent to the Phoenix team as feedback.
-- Ask once per conversation, after the first deploy that goes live. Do not ask again after later deploys, and do not ask after a deploy that failed.
-- Never choose or guess the score yourself. If the user skips the question or declines, send nothing and do not ask again.
-
-A rating is feedback like any other, so the rules of this skill apply. Write the comment from the user's words, and take out anything the last section forbids: replace this project's product, customer and people names with generic words. Then show the user the three lines below exactly as they would be sent and send them only after a yes; if they edit the text, send their version. Use \`none\` when they gave no comment:
-\`\`\`bash
-pnpm phoenix feedback 'Rating: <score>/10
-Comment: <their comment, or none>
-Stage: after a deploy' --type other --agent '<your agent name>'
-\`\`\`
-Keep the three labels and their order, so the ratings can be read out of the feedback list. A rating is not a bug report: when the comment names a concrete problem, offer to draft it as its own feedback as the sections above describe.`,n=`## What Never Goes Into Feedback
-The message leaves this project and is read by the Phoenix team. Never include:
-- secrets: API tokens, keys, passwords or \`.env\` values;
-- customer or end-user data, or personal data such as names and email addresses, other than a contact the user asked you to add;
-- this project's source code, specs or business rules. Describe the shape of the problem in words, or reduce it to a generic example that contains nothing of the project.`;export const generatePhoenixFeedbackSkill=()=>e({name:"phoenix-feedback",description:"Drafting feedback about the Phoenix SDK, CLI, documentation or Studio for the Phoenix team and sending it with the phoenix feedback command once the user approves the draft, covering when to raise it, how to write it, the rating asked for after a deploy and what must never be included. Use when the SDK or CLI misbehaves, a doc or skill misled you, a missing feature forced a workaround, the user asks to send feedback, or phoenix deploy has just gone live and the user should be asked to rate the experience from 0 to 10.",sections:[t,o,"## How to Send It\n```bash\npnpm phoenix feedback '<message>' --type bug --agent '<your agent name>'\n```\n- Put the message in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside the message as `'\\''`; in PowerShell, double it instead.\n- `--type` is `bug`, `idea` or `other` (default `other`). Use `idea` for a missing feature or an improvement.\n- `--agent` names you, the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the user wants a reply and gave you the contact to use.\n- The workspace, user, SDK version and the spec's `project` are attached automatically. `--projectSlug <slug>` names another project of the workspace.\n- A message holds at most 5000 characters.\n\nWrite the message for someone who cannot see this project: what you ran or called, what you expected, what happened instead with the error text, and the workaround if you found one. Before quoting an error, replace this project's names, file paths and values in it with generic placeholders, as the list below requires.\n\nThe command needs `phoenix login`. If it answers that you are not signed in, tell the user once and continue; do not sign in yourself, because the sign-in is approved in a browser.\n\nAfter sending, confirm it to the user in one line.",a,n]});

package/dist/application-spec/generate-application/code/templates/phoenix-skill.js

@@ -1 +0,0 @@
-import{renderAgentSkill as e}from"./common/agent-skill.js";import{sdkGuidanceSections as t}from"./common/sdk-content.js";export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixSkill=({checkLatestCanary:n})=>e({name:"phoenix",description:`Phoenix SDK project conventions, covering project structure, architecture principles, key patterns, file and export rules, webhook membership, showing the user the dev preview and the build of a deploy, and how to search the SDK documentation${n?", and the internal-beta check for the latest canary SDK build":""}. Use before writing or changing specs or source code in this Phoenix configurator project.`,sections:[...n?["## Stay on the Latest Canary\nDuring the internal beta this project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before you change anything, compare the installed version with the newest canary:\n```bash\npnpm list @salsita-ai/sdk --depth 0\nnpm view @salsita-ai/sdk@canary version\n```\nWhen they differ, tell the user which version you are moving to, then update the project and regenerate its files:\n```bash\npnpm add @salsita-ai/sdk@canary\npnpm phoenix sync\n```\n`sync` rewrites the Phoenix skills, so read the ones you use again after it. When the user runs a globally installed `phoenix`, update that too with `npm install -g @salsita-ai/sdk@canary`. If the project no longer builds after the update, stop and tell the user; the `phoenix-feedback` skill covers reporting it."]:[],t.projectStructure,t.architecturePrinciples,t.keyPatterns,t.fileConventions,t.exportRules,t.webhookMembership,t.doNotEdit,"## Show the Preview While You Work\nThe user should see the configurator change as you build it. Before your first change in a conversation, make sure `pnpm phoenix dev` is running (start it in the background when it is not) and open the address it prints as `Preview: <url>` (also written to `.phoenix/phoenix-dev.log`) in the user's browser: `open '<url>'` on macOS, `xdg-open '<url>'` on Linux, `Start-Process '<url>'` in PowerShell, `start \"\" \"<url>\"` in cmd. Keep the quotes, the shell would otherwise read a `?` in the address as a pattern. The log keeps the lines of earlier runs, so when you have just started dev, wait for the `Preview:` line written after your start and use the last one. Open it once; the preview reloads on every change, so tell the user to keep that tab open instead of opening it again.","## Show the Build After a Deploy\n`pnpm phoenix deploy` starts a build on the server and waits for it to go live. Right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Run the deploy so that you can read its output while it runs, and open that link in the user's browser, quoted as above, as soon as it appears, so they can follow the build they just triggered. When the line is missing, the sign-in is older than the link: tell the user the build is listed under Deployments in Studio, and that `pnpm phoenix login <workspace>` brings the link back.","## Code Review\nUse the `phoenix-review` skill to review code changes before committing.",t.sdkDocumentation]});

package/dist/configurator/assistant/browser-details.js

@@ -1 +0,0 @@
-import{browserDetailsTool as e}from"@salsita-ai/contracts/assistant";let t=e=>{let t=[];for(let i=0;i<e.length;i+=64)t.push(e.slice(i,i+64));return t};export const browserDetailsClientTool=e.client(()=>{let e=(()=>{let e=[`User agent: ${navigator.userAgent}`,`Viewport: ${window.innerWidth} x ${window.innerHeight} px`,`Screen: ${window.screen.width} x ${window.screen.height} px`,`Device pixel ratio: ${window.devicePixelRatio}`,`Language: ${navigator.language}`,`Time zone: ${Intl.DateTimeFormat().resolvedOptions().timeZone}`].flatMap(t),i=document.createElement("canvas");i.width=720,i.height=48+26*e.length;let n=i.getContext("2d");if(!n)throw Error("The browser details capture failed because the canvas has no 2D context. Retry in another browser.");return n.fillStyle="#ffffff",n.fillRect(0,0,i.width,i.height),n.fillStyle="#111111",n.font="16px monospace",n.textBaseline="top",e.forEach((e,t)=>n.fillText(e,24,24+26*t)),i.toDataURL("image/png")})();return[{type:"image",source:{type:"data",value:e.slice(e.indexOf(",")+1),mimeType:"image/png"}}]});

package/dist/configurator/assistant/graphql-tools.js

@@ -1 +0,0 @@
-import{AssistantGraphQLToolInput as e,applyTool as t,queryTool as o}from"@salsita-ai/contracts/assistant";let a=e=>({results:[],committed:!1,message:e}),s=e=>JSON.parse(JSON.stringify(e)),i=t=>{let o=e.safeParse(t);if(!o.success){let e=o.error.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("; ");return{ok:!1,refusal:a(`Nothing was run, because the tool input is not a list of operations (${e}). Send { "operations": [{ "query": "<one GraphQL operation>" }] } with at least one item.`)}}return{ok:!0,operations:o.data.operations.map(({query:e,variables:t,operationName:o})=>({document:e,variables:t??void 0,operationName:o??void 0}))}};export const queryClientTool=o.client(async(e,{context:t})=>{let o=i(e);return o.ok?t.storeSystem.isInitialized?s({results:(await t.graphQLSystem.prepare(t.storeSystem.stateSlices.committed.value.state,o.operations)).map(({result:e})=>e),committed:!1}):a("Nothing was run, because the configuration is not loaded yet, so there is no state to query. Call the tool again once the configurator has finished loading."):o.refusal});export const applyClientTool=t.client(async(e,{context:t})=>{if("owner"!==t.getActiveMode())return a("Nothing was run, because changes cannot be applied in this session: the user may view this configuration but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it.");let o=i(e);return o.ok?s(await t.graphQLSystem.execute(o.operations)):o.refusal});

package/dist/configurator/assistant/index.d.ts

@@ -1 +0,0 @@
-export { useAssistantChat, type AssistantChatState } from './use-assistant-chat.js';

package/dist/configurator/assistant/index.js

@@ -1 +0,0 @@
-export{useAssistantChat}from"./use-assistant-chat.js";

package/dist/configurator/assistant/use-assistant-chat.d.ts

@@ -1,20 +0,0 @@
-import { type UIMessage } from '@tanstack/ai-react';
-/** Experimental assistant chat state and actions of the current configuration. */
-export interface AssistantChatState {
-    /** The thread as painted: hydrated from the server, then streamed. */
-    readonly messages: ReadonlyArray<UIMessage>;
-    /** True while a reply streams or a browser tool runs. */
-    readonly isLoading: boolean;
-    readonly error: Error | undefined;
-    /** Sends a user message stamped with its send time. */
-    readonly send: (content: string) => Promise<void>;
-    /** Stops the current reply in the browser and on the server. */
-    readonly stop: () => Promise<void>;
-}
-/**
- * Experimental: the conversational assistant of the current configuration. The server owns the
- * thread — the chat hydrates from it on mount and rejoins a reply still streaming — so the hook
- * keeps nothing in browser storage. Each message carries its send time for the model. The model's
- * `query` and `apply` calls run here, in the browser, against the configurator this hook is rendered in.
- */
-export declare const useAssistantChat: () => AssistantChatState;

package/dist/configurator/assistant/use-assistant-chat.js

@@ -1 +0,0 @@
-import{fetchServerSentEvents as t,useChat as e}from"@tanstack/ai-react";import{useCallback as a,useMemo as r}from"react";import{useAuthorizedClient as s,useConfigurationId as n,useDomain as o}from"#package/react-sdk";import{useConfigurator as i}from"../application-runtime/index.js";import{browserDetailsClientTool as c}from"./browser-details.js";import{applyClientTool as p,queryClientTool as l}from"./graphql-tools.js";let m=[c,l,p];export const useAssistantChat=()=>{let c=n(),p=s(),l=r(()=>p.getAssistantChatConnection(c),[p,c]),d=r(()=>{let e=async()=>({headers:await l.headers()}),a=t(l.url,e),r=t(`${l.url}/runs`,e);return{...a,joinRun:r.joinRun}},[l]),{graphQLSystem:u}=i(),{storeSystem:h,domainContextSelectors:f}=o(),{getActiveMode:w}=f,{messages:g,isLoading:j,error:y,sendMessage:C,stop:S,runId:$}=e({threadId:`assistant:${c}`,connection:d,persistence:!0,history:{pageSize:50},tools:m,context:r(()=>({graphQLSystem:u,storeSystem:h,getActiveMode:w}),[u,h,w])});return{messages:g,isLoading:j,error:y,send:a(async t=>{let e={sentAt:new Date().toISOString()};await C({content:t,metadata:e})},[C]),stop:a(async()=>{S(),null!=$&&await fetch(`${l.url}/runs/${encodeURIComponent($)}/cancel`,{method:"POST",headers:await l.headers()})},[l,$,S])}};

package/dist/extras/assistant/AssistantChat.d.ts

@@ -1,6 +0,0 @@
-/**
- * Experimental, unstyled assistant chat for the current configuration: streamed replies, reasoning
- * summaries, tool calls with their payloads, a pending indicator and a stop button. It renders
- * nothing, and contacts no server, when the application spec has no `assistant` section.
- */
-export declare const AssistantChat: () => import("react/jsx-runtime").JSX.Element | null;

package/dist/extras/assistant/AssistantChat.js

@@ -1 +0,0 @@
-import{jsx as e,jsxs as t}from"react/jsx-runtime";import{Alert as r,Box as a,Button as i,LinearProgress as n,Stack as o,TextField as l,Typography as s}from"@mui/material";import{useState as c}from"react";import{useAssistantChat as p}from"#package/configurator";import{useSpecAssistant as m}from"#package/react-sdk";let d=({part:t})=>{switch(t.type){case"text":return e(s,{sx:{whiteSpace:"pre-wrap"},children:t.content});case"thinking":return e(s,{variant:"body2",color:"text.secondary",sx:{fontStyle:"italic",whiteSpace:"pre-wrap"},children:t.content});case"tool-call":return e(s,{variant:"caption",component:"pre",sx:{m:0,whiteSpace:"pre-wrap"},children:`${t.name}(${JSON.stringify(t.input??t.arguments)}) \xb7 ${t.state}`});case"tool-result":{let r=(e=>{if("string"!=typeof e){for(let t of e)if("image"===t.type&&"data"===t.source.type)return`data:${t.source.mimeType};base64,${t.source.value}`}})(t.content);return r?e(a,{component:"img",src:r,alt:"Tool result",sx:{maxWidth:"100%",border:1}}):e(s,{variant:"caption",children:`Tool result \xb7 ${t.state}`})}default:return null}},u=()=>{let{messages:m,send:u,stop:h,isLoading:f,error:x}=p(),[g,v]=c("");return t(o,{spacing:1.5,sx:{p:2},children:[m.map(r=>t(a,{component:"div",sx:{alignSelf:"user"===r.role?"flex-end":"flex-start",maxWidth:"85%"},children:[e(s,{variant:"overline",children:r.role}),r.parts.map((t,r)=>e(d,{part:t},r))]},r.id)),f&&e(n,{"aria-label":"Assistant is responding"}),x&&e(r,{severity:"warning",children:x.message}),e("form",{onSubmit:e=>{e.preventDefault();let t=g.trim();t&&(v(""),u(t))},children:t(o,{direction:"row",spacing:1,children:[e(l,{size:"small",fullWidth:!0,placeholder:"Ask the assistant…",value:g,onChange:e=>v(e.target.value)}),f?e(i,{onClick:()=>void h(),children:"Stop"}):e(i,{type:"submit",variant:"contained",disabled:!g.trim(),children:"Send"})]})})]})};export const AssistantChat=()=>m()?e(u,{}):null;

package/dist/extras/assistant/index.d.ts

@@ -1 +0,0 @@
-export { AssistantChat } from './AssistantChat.js';

package/dist/extras/assistant/index.js

@@ -1 +0,0 @@
-export{AssistantChat}from"./AssistantChat.js";

package/dist/phoenix/application-spec/generate-assistant-prompt.js

@@ -1 +0,0 @@
-let e=["How to read the GraphQL schema of this configurator:","- A configuration is a set of entities. `root` is the root entity, `entities` lists every entity or the ones with the given ids, and `selectedEntity` is the entity the user has selected, or the root entity when nothing is selected.","- Every entity has an `id` of the form `<Type>-<number>`, for example `Table-1`, and a `type` with its entity type name. Ids are assigned by the configurator: read them from the configuration and never make one up.","- A field whose name starts with `_` is computed by the configurator from other values. It can be read like any other field and never written.","- Numbers are in the units the configuration stores them in. A field description names the unit when the product defines one.",'- A text field that only takes fixed values lists them in its description as "One of: ...". Use exactly those values.',"- A field typed as another entity type or as a list of one is a relation: select fields on it to read the related entities.","- Field and type descriptions come from the team that built the configurator and say what a value means for the product."],t=["How changes work:","- Every field of the `Mutation` type is one change. Its description says what it changes and what it returns.","- The configurator checks the whole configuration after each change. A change that would leave it invalid fails with an error that names the entities at fault, and it is not applied. Later changes of the same request are then not run.","- The configurator may adjust other values in response to a change, so read what a mutation returns instead of assuming the values you sent."],n=["How to add entities:","- Entities are added from recipes, the same ones the configurator offers the user. An entity type that can take children has a `meta` field; `meta { childRecipes }` lists its recipe groups and their recipes.","- List the recipes of the group first, pick one by its `key`, then call `addChild` with the id of the parent, the `groupId` and the `key`. Keys change with the configuration and the language, so never reuse one from memory.","- `dryRun` on a recipe shows what adding it would do without adding it: whether it is `ok`, the `changedEntities` it would add or modify, the `deletedEntityIds` it would remove, and the `errors` when it cannot be added. An entity whose id the configuration does not have yet is new. It is costly, so select it only on the recipes you are deciding between.","- Put each `addChild` in its own operation. The recipes of a group and what they add depend on the configuration before them, so after adding something, list the group again before adding from it once more."],a=["How to replace entities:","- An entity is replaced from recipes, the same ones the configurator offers the user. An entity type that can be replaced has a `meta` field; `meta { replaceRecipes }` lists its replace recipe groups and what the entity can be replaced with.","- List the recipes of the group first, pick one by its `key`, then call `replaceEntity` with the id of the entity, the `groupId` and the `key`. `dryRun` on a replace recipe shows what replacing would do without doing it: the replacement and everything else that changes are under `changedEntities`, and the replaced entity is among the `deletedEntityIds`.","- The replacement is a new entity with a new id, and its field values come from the recipe, so they can differ from those of the entity it replaces. Read the ids and values `replaceEntity` returns, and never use the old id again.","- Put each `replaceEntity` in its own operation. The recipes of a group and what they do depend on the configuration before them, so after replacing something, list the group of the replacement again before replacing once more."],i=["How to find the values a field can take:","- Some fields store a key whose choices the configurator holds elsewhere. Such a field has an edge under `meta` named after it: `meta { <field>Options }` lists its choices, each with the `value` to write and the `name` the user sees.","- Read the choices before you write such a field or name a choice to the user, and write the `value`, not the `name`. A value outside the list is rejected unless the edge description says the field is not checked.","- `dryRun` on an option shows what writing its value would do without writing it: whether it is `ok`, the `changedEntities` it would add or modify, the `deletedEntityIds` it would remove, and the `errors` when the value cannot be written. It is costly, so select it only on the options you are deciding between. It is null when the edge description says the options cannot be dry-run.","- The choices can depend on the entity and on its current state. Read them again after a change, unless the edge description says they are the same for all instances or do not change."],o=["How to use the `query` and `apply` tools:","- Both take `operations`, a list of GraphQL documents that run in order. Each document holds exactly one operation. To do several things, send several items in one call instead of several calls.","- Write values into the document as literals. Use `variables` only for a value that cannot be written as a literal.","- Select only the fields you need: results are returned whole.","- The result has one GraphQL result per operation, in the order sent. When an operation fails, its `errors` say why and the operations after it are not run.","- `query` reads the configuration the user has open and never changes it. Call it before you say anything about the configuration."],s=["- This configurator exposes no changes, so there is nothing for `apply` to run. Say so when the user asks you to change the configuration."],r=['- Mutations inside `query` answer "what if" questions. Each operation sees the changes of the ones before it, so a mutation followed by a query shows the configuration as it would be. Nothing is kept and the user sees no change.',"- `apply` makes the changes the user asked for. It is all or nothing: when any operation fails, nothing is changed; when all succeed, the user gets them as one undo step.","- `committed` in the result says whether the changes were kept. When it is false although no operation failed, `message` says why: the changes may be waiting for the approval of the user, the user may have changed the configuration meanwhile, or this session may not change the configuration at all. Without a `message`, the operations changed nothing. Never tell the user a change was made unless `committed` is true."];export const generateAssistantPrompt=h=>{let d=/^type Mutation\b/m.test(h.sdl);return[e,...d?[t]:[],.../^\s+addChild\(/m.test(h.sdl)?[n]:[],.../^\s+replaceEntity\(/m.test(h.sdl)?[a]:[],.../^type FieldOption\b/m.test(h.sdl)?[i]:[],[...o,...d?r:s]].map(e=>e.join("\n")).join("\n\n")};